selecta

selecta | /seˈlɛk.ta/ | Latin, n. pl. of selectum, past participle of seligere: things chosen out

Declarative EQUATOR-style diagrams for clinical studies.

Overview

The selecta package provides a pipe-friendly, declarative interface for constructing EQUATOR-style flow diagrams. A diagram is specified as a sequence of operations—enrollment, exclusion, stratification, recombination, and endpoint—that mirrors the natural language description of a study’s participant flow. The package supports multiple reporting guidelines (CONSORT, STROBE, STARD, PRISMA, MOOSE), hybrid or custom topologies, automatic count computation, arithmetic checking, diagram render via grid graphics or Graphviz DOT, and optionally return of the analysis-ready cohort at any stage of the selection process.

For a more comprehensive description of this package and its features, see the full documentation and vignettes.

Installation

This package is not yet available on CRAN. Install it from GitHub (stable) or Codeberg (development):

# Stable release
devtools::install_github("phmcc/selecta")

# Development version
devtools::install_git("https://codeberg.org/phmcc/selecta.git")

Package Composition

Design Principles

The architecture of selecta reflects four guiding principles:

1. Declarative specification. Diagrams are defined as a linear sequence of named operations. The code reads top-to-bottom, matching the visual top-to-bottom flow of an EQUATOR diagram and the narrative order in which investigators describe their enrollment process.

2. Dual-mode operation. The same API supports both data mode (counts computed automatically from a data frame) and manual mode (counts supplied directly as integers). This permits use at any stage of a project—from protocol drafting through final manuscript preparation.

3. Diagram–data duality. A selecta object is simultaneously a diagram specification and a data pipeline. flowchart() renders the visual output; cohort() extracts the resulting dataset. The same object serves both reporting and analysis.

4. Minimal dependencies. The package requires only data.table for data manipulation and grid (part of base R) for rendering. No external graphics libraries, web frameworks, or layout engines are imposed.

These principles manifest in the standard calling convention:

flow <- enroll(data, id = "patient_id") |>
  exclude("Excluded", criterion = <condition>) |>
  allocate("treatment_variable") |>
  endpoint("Final Analysis")

flowchart(flow)  # render the diagram
cohort(flow)     # extract the analysis-ready dataset

Supported Guidelines

selecta provides dedicated functions for each guideline’s specific structural requirements, all composable within the same pipe-oriented framework:

Functional Reference

Diagram construction

Functions for building the enrollment flow. Each returns a modified selecta object and is designed for use in a pipe chain.

Rendering and export

Data extraction

Inspection

Operating Modes

selecta supports two modes, selected automatically by the arguments passed to enroll():

Flow Topologies

selecta supports three distinct flow topologies, distinguished by what happens after a split:

Visual Customization

All rendering functions accept the following styling parameters:

Regional number formatting

The number_format argument accepts named presets ("us", "eu", "space", "none") or a custom c(big.mark, decimal.mark) vector. The choice may be set globally for a session:

options(selecta.number_format = "eu")   # 1.234 instead of 1,234
options(selecta.vpad = 0.35)            # increase default vertical spacing

Diagnostic output

For inspecting flow diagram layout specifics, selecta can emit a structured trace of its internal computation. The trace is controlled by a single session option:

options(selecta.debug_layout = TRUE)

Comparison with Related Packages

The R ecosystem includes several packages for generating CONSORT diagrams. The following comparison identifies areas of overlap and distinction:

_{✓ Full support | ◐ Partial support | — Not available}

A detailed feature comparison is available in the package documentation.

Illustrative Example

The selectaex* datasets included with this package provide simulated clinical trial selection cohorts with various inclusion/exclusion criteria, as well as different arm allocation criteria. The following example demonstrates how selecta functions can be used to generate a CONSORT diagram from the two-armed dataset selectaex2, using data-driven counts, count-first formatting, and automatic subcohort extraction.

Step 0: Data Preparation

Prior to analysis, load the package and the dataset:

library(selecta)

# Load example data
data("selectaex2")

Step 1: Flowchart Creation

Use a pipe-based workflow to sequentially string together the various elements of the flowchart, from top to bottom. The exclude() function pares down the dataset based on the condition supplied to the criterion parameter, whereas allocate()/stratify() sets arms. Export the output using the flowsave() function.

flow <- enroll(selectaex2, id = "patient_id") |>
    phase("Screening") |>
    exclude("Duplicate records", criterion = is_duplicate == TRUE,
            included_label = "Unique records") |>
    exclude("Failed eligibility", criterion = eligible == FALSE,
            reasons = "exclusion_reason",
            included_label = "Eligible cohort") |>
    phase("Allocation") |>
    allocate("treatment") |>
    phase("Follow-up") |>
    exclude("Discontinued", criterion = discontinued == TRUE,
            reasons = "discontinuation_reason") |>
    phase("Analysis") |>
    endpoint("Analysis cohort")

flowsave(flow, "consort.pdf", count_first = TRUE)

Step 2: Cohort Extraction

The diagram is not merely a figure—selecta maintains the dataset state at every step, allowing direct extraction of the analysis-ready cohort:

# The final cohort
final <- cohort(flow)

# Split by arm
by_arm <- cohort(flow, split = TRUE)

# A single arm
drug_a <- cohort(flow, arm = "Drug A")

Moreover, every intermediate stage is accessible via cohorts(), enabling inspection of participants removed at each step:

stages <- cohorts(flow)

# Participants excluded for failing eligibility
stages[["Failed eligibility"]]$excluded

# Dataset remaining after the eligibility exclusion
stages[["Failed eligibility"]]$included

Development

Repository

• Primary development: codeberg.org/phmcc/selecta
• GitHub releases: github.com/phmcc/selecta

Contributing

Bug reports and feature requests may be submitted via the issue tracker (Codeberg or GitHub). Contributions are welcome; prospective contributors are directed to the contributing guidelines prior to submitting pull requests.

Acknowledgments

The design of selecta draws inspiration from several existing packages and reference standards:

• EQUATOR Network — Reporting-guideline standards (CONSORT, STROBE, STARD, PRISMA, MOOSE)
• consort (Alim Dayim) — CONSORT diagram conventions in R
• stard (Chiara Herzog) — STARD diagram conventions in R
• DiagrammeR (Iannone) — R Graphviz/DOT rendering
• data.table (Dowle & Srinivasan) — High-performance data operations

License

GPL (>= 3.0)

Citation

citation("selecta")

To cite selecta in publications, use:

  McClelland PH (2026). _selecta: EQUATOR-Style Enrollment Diagrams
  for Clinical Studies_. R package version 0.6.0,
  <https://phmcc.codeberg.page/selecta/>.

A BibTeX entry for LaTeX users is

  @Manual{,
    title = {selecta: EQUATOR-Style Enrollment Diagrams for Clinical Studies},
    author = {Paul Hsin-ti McClelland},
    year = {2026},
    note = {R package version 0.6.0},
    url = {https://phmcc.codeberg.page/selecta/},
  }

Further Resources

• Function documentation: ?function_name or the reference index
• Companion package: summata for publication-ready summary tables
• Issue tracker: Codeberg Issues, GitHub Issues

_{The selecta package is under active development. Any breaking changes to the API will be reported in the changelog.}