Render an Enrollment Flowchart

Computes counts from the pipeline, lays out nodes, and draws an EQUATOR-style enrollment diagram. This is the primary rendering function for interactive use; for saving to file with auto-sized dimensions, see flowsave().

Usage

flowchart(.flow, engine = c("grid", "dot"), count_first = NULL, ...)

# S3 method for class 'selecta'
plot(x, engine = c("grid", "dot"), ...)

Arguments

.flow

A selecta object created by enroll() or sources() and populated with pipeline steps.

engine

Character. Rendering engine: "grid" (default) for base R graphics, or "dot" to return a Graphviz DOT string (for use with DiagrammeR or a locally installed executable).

count_first

Logical. If TRUE, side-box labels are rendered as "214 Discontinued" (bold count before label) rather than the default "Discontinued (n = 214)". Applies to all box types. Default FALSE, supplied by the drawing routine rather than restated here, so this argument shows as NULL in the usage.

...

Additional styling and formatting arguments forwarded to the selected engine; arguments an engine does not recognize are ignored.

For engine = "grid":

cex, cex_side, cex_phase

Font-size multipliers for the main, side-box, and phase text

box_fill, phase_fill

Fill colors for boxes and phase strips

vpad, margin

Vertical spacing between elements and the outer margin, in inches

font_family

Font family for text

number_format

Locale-aware count formatter

For engine = "dot":

formatting

Label markup: "plain" (default) for robust, pixel-accurate centering across all fonts, or "rich" for HTML-like inline bold and italic that match the grid engine's typography at the cost of small centering drift on non-Helvetica fonts

bullets

Prefix side-box sub-reasons with a bullet; defaults on under "plain" (where indentation alone is a weak cue) and off under "rich"

font_family, padding_pt, padding_adjust

Font family (default "Helvetica") and the uniform horizontal label padding in points (default 14) with its fine adjustment

ortho

Use orthogonal (right-angled) edge routing

box_fill, side_fill, border_col, arrow_col

Box, side-box, border, and arrow colors

source_fill, source_header_fill, source_header_text

Source-box fill, header fill, and header text color

phase_labels, phase_fill, phase_text_col

Toggle and color the phase-band labels (on by default when the flow defines phases; the dot engine draws them as horizontal left-margin bands rather than the grid engine's vertical strips)

rank_sep, node_sep

Spacing of ranks and nodes, in inches

number_format

Locale-aware count formatter, shared with the grid engine

x

A selecta object.

Value

For engine = "grid": invisibly returns the computed graph structure (a list of nodes, edges, and phases data.tables). For engine = "dot": returns a DOT-language string.

Details

flowchart() is the primary rendering entry point and accepts a completed pipeline object. The grid engine draws the diagram to the active graphics device using the grid system and is intended for publication-quality figures with phase strips, precise dimensions, and locale-aware counts; the dot engine instead returns a Graphviz DOT-language string for prototyping or rendering through external Graphviz tooling, and draws nothing itself. Styling, font, and number-format options are forwarded to the chosen engine through ...; options unsupported by an engine (for example the phase strips, which the dot engine does not draw) are ignored. flowchart() is normally the last call in a pipeline; for direct file output use flowsave(), and to size a canvas use recdims.

See also

flowsave for saving to file, recdims for dimension recommendations, plot.selecta for S3 plot method

Other flowchart output functions: flowsave(), print.selecta(), recdims(), summary.selecta()

Examples

# Build a flow once, then render it. Most of the package's pipeline
# functions are modular and intended to be composed like this rather
# than run in isolation; see the vignettes for fuller treatments.
flow <- enroll(n = 1200) |>
  phase("Enrollment") |>
  exclude("Excluded", n = 150,
    reasons = c("Did not meet criteria" = 55,
                "Declined to participate" = 48,
                "Other reasons" = 47)) |>
  phase("Allocation") |>
  allocate(labels = c("Treatment", "Control"),
           n = c(520, 530)) |>
  phase("Analysis") |>
  endpoint("Final Analysis")

# The "dot" engine returns a Graphviz DOT string and draws nothing,
# so it runs anywhere without opening a graphics device.
dot <- flowchart(flow, engine = "dot")
substr(dot, 1, 50)
#> [1] "digraph selecta {\n  rankdir=TB;\n  splines=ortho;\n "

# The "grid" engine draws to the active graphics device. These calls are
# guarded with interactive() so they render in an interactive session but
# are skipped during non-interactive documentation builds, where the
# diagram cannot be sized to the page and would render incorrectly.
if (interactive()) {
  flowchart(flow)            # draws to the active device
  plot(flow)                 # plot() is a thin wrapper around flowchart()

  # Locale-aware counts: a European thousands separator.
  enroll(n = 12500) |>
    exclude("Excluded", n = 1450) |>
    endpoint("Analyzed") |>
    flowchart(number_format = "eu")
}