A Grammar of Clinical Summary Tables

Implements a grammar of summary data for clinical reports. Clinical summary tables are decomposed into modular layers, each representing an independent summary block. Supports count, descriptive statistics, and shift layer types with a declarative spec-based API built on data.table for performance.

output: github_document

tplyr2

{tplyr2} is a grammar of clinical summary tables. Clinical reports -- demographics tables, adverse event summaries, lab shift tables -- all share a common structural pattern. Each section is some kind of summary: a set of counts, a block of descriptive statistics, or a cross-tabulation. Rather than writing bespoke data manipulation code for every table, {tplyr2} lets you describe what the table should contain using a declarative specification, and handles the computing, formatting, and assembly for you.

{tplyr2} is a ground-up rewrite of {Tplyr}, built on data.table for performance. The spec-based API separates configuration from data, making specs portable, reusable, and serializable to JSON/YAML.

Installation

You can install the development version of {tplyr2} from GitHub:

# install.packages("devtools")
devtools::install_github("atorus-research/tplyr2")

Example

Every table starts with a tplyr_spec() that declares the column structure and layers. Data is supplied at build time with tplyr_build().

library(tplyr2)

spec <- tplyr_spec(
  cols = "TRT01P",
  layers = tplyr_layers(
    group_count("SEX", by = "Sex n (%)"),
    group_desc(
      "AGE",
      by = "Age (Years)",
      settings = layer_settings(
        format_strings = list(
          "n"         = f_str("xxx", "n"),
          "Mean (SD)" = f_str("xx.x (xx.xx)", "mean", "sd"),
          "Median"    = f_str("xx.x", "median"),
          "Min, Max"  = f_str("xx, xx", "min", "max")
        )
      )
    )
  )
)

result <- tplyr_build(spec, tplyr_adsl)
knitr::kable(result[, !grepl("^ord", names(result))])

Key Concepts

• Spec: A tplyr_spec() object is pure configuration -- no data, no side effects. It describes the column variable, filters, population data, and layers.
• Layers: Each layer is a summary block created with group_count(), group_desc(), group_shift(), or group_analyze().
• Build: tplyr_build(spec, data) executes the spec against a dataset and returns a formatted data frame.
• Format strings: f_str() declarations control numeric precision and alignment (e.g., f_str("xx.x (xx.xx)", "mean", "sd")).

Layer Types

Count Layers

Tabulate frequencies of categorical variables, with support for nested counts, distinct subject counting, and total rows.

spec <- tplyr_spec(
  cols = "TRTA",
  layers = tplyr_layers(
    group_count(
      c("AEBODSYS", "AEDECOD"),
      settings = layer_settings(
        distinct_by = "USUBJID",
        format_strings = list(
          n_counts = f_str("xxx (xx.x%)", "distinct_n", "distinct_pct")
        )
      )
    )
  )
)

result <- tplyr_build(spec, tplyr_adae)
knitr::kable(head(result[, !grepl("^ord", names(result))], 10))

Descriptive Statistics Layers

Summarize continuous variables with built-in statistics (n, mean, sd, median, min, max, q1, q3, var, iqr, missing) or custom summary functions.

Shift Layers

Cross-tabulate a baseline value against a post-baseline value within each treatment arm using group_shift().

Analyze Layers

Run user-defined analysis functions with group_analyze() for full flexibility.

Features

• Population data: Control denominators with pop_data() and display (N=n) header counts with tplyr_header_n()
• Total & custom groups: Add "Total" columns or combine treatment arms with total_group() and custom_group()
• Auto-precision: Dynamically set decimal places based on collected precision with the precision cap system
• Risk difference: Compute risk differences and confidence intervals on count layers
• Post-processing: Row masks, row label collapsing, conditional formatting, and text wrapping helpers
• Metadata: Cell-level traceability to trace any result back to its source records
• Numeric data: Access raw unformatted results via tplyr_numeric_data()
• Serialization: Save and load specs as JSON or YAML with tplyr_write_spec() / tplyr_read_spec()
• ARD: Convert to and from Analysis Results Data format with tplyr_to_ard() / tplyr_from_ard()

Learning More

Getting started

• vignette("tplyr2") -- Getting started
• vignette("table") -- Spec-level table properties

Layers

• vignette("count") -- Count layers in depth
• vignette("desc") -- Descriptive statistics layers
• vignette("shift") -- Shift layers
• vignette("analyze") -- Custom analyze layers
• vignette("adverse-events") -- A full adverse event table, end to end

Formatting

• vignette("format_strings") -- The format string system
• vignette("precision_alignment") -- Data-driven precision and parenthesis hugging
• vignette("display_conventions") -- <1%, zero-count suppression, statistics as columns

Table customization

• vignette("denom") -- Denominators, population data, header N
• vignette("sort") -- Ordering rows and layers
• vignette("options") -- Session options
• vignette("post_processing") -- Post-processing helpers

Statistics and traceability

• vignette("riskdiff") -- Risk difference columns
• vignette("binding-statistics") -- Association tests and binding external model results
• vignette("metadata") -- Cell-level metadata and traceability
• vignette("serialization") -- Saving and loading specs
• vignette("ard") -- Analysis Results Data conversion
• vignette("migration") -- Moving from Tplyr v1