Data Is Separated from Configuration

In v1, data lives inside the table object from the moment you create it:

# Tplyr v1: data bound at table creation
t <- tplyr_table(adsl, TRT01P)

In tplyr2, the spec knows nothing about data. You supply data only when you are ready to build:

spec <- tplyr_spec(
  cols = "TRT01P",
  layers = tplyr_layers(
    group_count("SEX")
  )
)

# Data provided at build time
result <- tplyr_build(spec, tplyr_adsl)

This means the same spec can be applied to different datasets without modifying the spec itself.

Variable Names Are Quoted Strings

In v1, variable names are bare symbols. In tplyr2, they are character strings. This is required for JSON/YAML serialization and simpler programmatic construction. The one exception is where, which accepts bare expressions:

# Tplyr v1: bare symbols              # tplyr2: quoted strings
group_count(SEX)                       group_count("SEX")
group_desc(AGE)                        group_desc("AGE")

group_count("SEX", where = SAFFL == "Y")

Settings Are Collected in an Object

In v1, you configure layers by piping modifier functions:

# Tplyr v1: piped modifiers
group_count(RACE) %>%
  set_format_strings(f_str("xx (xx.x%)", n, pct)) %>%
  set_distinct_by(USUBJID) %>%
  set_denoms_by(TRT01P)

In tplyr2, all configuration lives in a single layer_settings() object:

# tplyr2: declarative settings
group_count("RACE",
  settings = layer_settings(
    format_strings = list(n_counts = f_str("xx (xx.x%)", "n", "pct")),
    distinct_by = "USUBJID",
    denoms_by = "TRT01P"
  )
)

Format Strings Use Quoted Variable Names

The f_str() function works the same way, but variable names are now strings. For desc layers, format strings are a named list (each name becomes a row label). For count layers, the list key is n_counts:

# v1: bare symbols                     # tplyr2: quoted strings
f_str("xx (xx.x%)", n, pct)            f_str("xx (xx.x%)", "n", "pct")

# Desc layer: named list of format strings
format_strings = list(
  "n"         = f_str("xxx", "n"),
  "Mean (SD)" = f_str("xx.x (xx.xx)", "mean", "sd")
)
# Count layer: key is n_counts
format_strings = list(n_counts = f_str("xx (xx.x%)", "n", "pct"))

Demographics Table

# Tplyr v1 approach (not evaluated)
tplyr_table(adsl, TRT01P, where = SAFFL == "Y") %>%
  add_layer(
    group_count(SEX, by = "Sex n (%)")
  ) %>%
  add_layer(
    group_desc(AGE, by = "Age (Years)") %>%
      set_format_strings(
        "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)
      )
  ) %>%
  build()

spec <- tplyr_spec(
  cols = "TRT01P",
  where = SAFFL == "Y",
  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)
kable(result[, !grepl("^ord", names(result))])

Adverse Events Table (Nested Counts)

# Tplyr v1 approach (not evaluated)
tplyr_table(adae, TRTA) %>%
  add_layer(
    group_count(vars(AEBODSYS, AEDECOD)) %>%
      set_distinct_by(USUBJID) %>%
      set_format_strings(f_str("xxx (xx.x%)", distinct_n, distinct_pct)) %>%
      set_order_count_method("bycount") %>%
      set_ordering_cols("Xanomeline High Dose")
  ) %>%
  build()

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")
        ),
        order_count_method = "bycount",
        ordering_cols = "Xanomeline High Dose"
      )
    )
  )
)

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

Comparative and Inferential Statistics

tplyr2 can attach cross-arm comparisons directly to a layer – something Tplyr v1 handled only through add_risk_diff():

• Risk difference via risk_diff in layer_settings() (the direct successor to add_risk_diff()) – one rdiff column per comparison with a confidence interval. See vignette("riskdiff").
• Association tests via assoc_test() – an omnibus p-value column (Fisher, chi-square, CMH, ANOVA/Kruskal on group_desc) or a pairwise per-level mode that emits a pval column per comparison, including on nested SOC/PT layers. See vignette("binding-statistics").
• Single-proportion confidence intervals via the ci_lower/ci_upper f_str keywords with ci_method/ci_level (Clopper-Pearson, Wilson, and more). See vignette("denom").

Binding External Results and Display Helpers

apply_formats() gained na, width, and pad arguments for formatting externally computed statistics (e.g. MMRM/ANCOVA results) into fixed-width cells you can row-bind onto a table, and as_display() returns a render-ready frame (rowlabel*/res*/rdiff*/pval* only). group_desc() also adds an n_records statistic (records assessed), and shift layers gain a denom_row (the “n” denominator line). See vignette("binding-statistics") and vignette("post_processing").

Multi-Column Count Layouts

Count layers can display each statistic in its own column per treatment group – a layout Tplyr v1 could not produce. The stat_columns setting takes a named list of format strings; each entry becomes a separate result column (e.g. a distinct-subject “n (%)” column beside an event-count “E” column under every arm):

group_count("AEDECOD",
  settings = layer_settings(
    distinct_by = "USUBJID",
    stat_columns = list(
      "n (%)" = f_str("xxx (xx.x%)", "distinct_n", "distinct_pct"),
      "E"     = f_str("xxx", "n")
    )
  )
)

See vignette("count") for details.

Spec Serialization

Specs can be saved to disk as JSON or YAML and loaded later, enabling centralized spec authoring with distributed execution:

spec <- tplyr_spec(
  cols = "TRT01P",
  layers = tplyr_layers(
    group_count("SEX"),
    group_desc("AGE")
  )
)

tmp <- tempfile(fileext = ".json")
tplyr_write_spec(spec, tmp)
spec_loaded <- tplyr_read_spec(tmp)
spec_loaded
#> tplyr2 table specification
#> Column variables: TRT01PLayers: 2[1] count: SEX (Layer 1)[2] desc: AGE (Layer 2)

Custom Analysis Layers

group_analyze() accepts a user-defined function for arbitrary computations. The function receives each group’s data subset and returns a data.frame of numeric results:

custom_fn <- function(.data, .target_var) {
  vals <- .data[[.target_var]]
  data.frame(
    geo_mean = exp(mean(log(vals[vals > 0]), na.rm = TRUE)),
    geo_sd   = exp(sd(log(vals[vals > 0]), na.rm = TRUE))
  )
}

spec <- tplyr_spec(
  cols = "TRT01P",
  layers = tplyr_layers(
    group_analyze("AGE", analyze_fn = custom_fn, settings = layer_settings(
      format_strings = list(
        "Geometric Mean (SD)" = f_str("xx.xx (xx.xx)", "geo_mean", "geo_sd")
      )
    ))
  )
)

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

Cell-Level Metadata

When metadata = TRUE is passed to tplyr_build(), every cell carries metadata tracing back to source data rows for auditability:

spec <- tplyr_spec(
  cols = "TRT01P",
  layers = tplyr_layers(group_count("SEX"))
)
result <- tplyr_build(spec, tplyr_adsl, metadata = TRUE)
row_ids <- generate_row_ids(result)

# Inspect the metadata for one cell, then retrieve its source rows
tplyr_meta_result(result, row_ids[1], "res1")
#> tplyr_meta [layer 1]
#>   Names: TRT01P, SEX
#>   Filters:
#>     TRT01P == "Placebo"
#>     SEX == "F"
source_rows <- tplyr_meta_subset(result, row_ids[1], "res1", tplyr_adsl)
kable(head(source_rows[, c("USUBJID", "SEX", "TRT01P")]))

ARD Conversion and Numeric Data

tplyr_to_ard() converts results into long-format Analysis Results Data. tplyr_numeric_data() provides raw unformatted numbers for validation:

spec <- tplyr_spec(
  cols = "TRT01P",
  layers = tplyr_layers(group_count("SEX"))
)
result <- tplyr_build(spec, tplyr_adsl)

kable(head(tplyr_to_ard(result), 10))

kable(tplyr_numeric_data(result, layer = 1))

Overall Speedup by Layer Type

The grand median speedup across all scenarios is 4.0x.

Detailed Results