flow_diagram: Draw the eligibility flow as a CONSORT-style flowchart

In autocodebook: Automatic Codebook and Tracking for 'Spark' and 'dplyr' Pipelines

Draw the eligibility flow as a CONSORT-style flowchart

Description

Renders a publication-ready CONSORT-style diagram (a 'ggplot' object) from the information captured during the pipeline. The layout is computed automatically, so no manual positioning is needed:

Usage

flow_diagram(
  title = "Eligibility flowchart",
  show_exclusions = TRUE,
  box_fill = "white",
  border_col = "grey25",
  text_size = 3.5
)

Arguments

title	Plot title. Default: "Eligibility flowchart".
show_exclusions	Logical. Show the side box listing the linear exclusion steps? Default: TRUE.
box_fill	Fill colour of the boxes. Default: "white".
border_col	Border colour of the boxes. Default: "grey25".
text_size	Base text size for the box labels. Default: 3.5.

Details

• A vertical trunk built from the linear eligibility steps (recorded by auto_filter() / track_step()): the cohort baseline at the top, a single side box listing every exclusion and its count, and the eligible cohort below.

• One column of boxes per subgroup leaf of the flow tree (built with track_split()), shown side by side under the eligible cohort.

• Outcome boxes (added with track_outcomes()) stacked beneath each subgroup column, one row per outcome, with the event count and percent.

Either part is optional: with only linear steps you get the trunk; with only a split tree you get the cohort box and its subgroup columns. The function reads the current session state and writes nothing to disk.

Requires the 'ggplot2' package (a soft dependency).

Value

A 'ggplot' object, or invisible NULL if there is nothing to draw.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  cb_init(id_col = "id_indiv")
  df <- data.frame(
    id_indiv  = sprintf("ID%04d", 1:400),
    sgm       = sample(c(0L, 1L), 400, replace = TRUE, prob = c(0.95, 0.05)),
    self_harm = sample(c(0L, 1L), 400, replace = TRUE, prob = c(0.97, 0.03))
  )
  df <- track_split(df, by = "sgm", label = "SGM status",
                    value_labels = c("0" = "Non-SGM", "1" = "SGM"))
  track_outcomes(df, vars = "self_harm",
                 labels = list(self_harm = "Self-harm"))
  flow_diagram()
}

autocodebook documentation built on June 9, 2026, 1:09 a.m.