Table Properties

Introduction

In tplyr2, a table is defined by its specification. The tplyr_spec() function captures the full configuration – column variables, filters, treatment groups, population data, and layers – as a pure description of what you want. No data processing happens until you call tplyr_build(). This vignette covers the spec-level parameters that control the overall structure of your table.

Every tplyr2 workflow follows two steps: define a spec with tplyr_spec(), then build the table with tplyr_build(spec, data). Let’s look at an example using the included tplyr_adsl dataset.

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

result <- tplyr_build(spec, tplyr_adsl)
kable(result[, c("rowlabel1", grep("^res", names(result), value = TRUE))])

Note how the cols parameter defines the column structure of the output. Each unique value of TRT01P becomes a result column, and the column labels automatically include the group count as (N=xx).

Column Variables

The cols parameter accepts a character vector of one or more variable names that define the columns of your output table. The most common case is a single treatment variable:

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

result <- tplyr_build(spec, tplyr_adsl)
kable(result[, c("rowlabel1", grep("^res", names(result), value = TRUE))])

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

result <- tplyr_build(spec, tplyr_adsl)
kable(result[, c("rowlabel1", grep("^res", names(result), value = TRUE))])

Table-Level Filtering with where

The where parameter applies a filter to all data before any layer processing begins. This is useful when records should be excluded from the entire table.

spec <- tplyr_spec(
  cols = "TRT01P",
  where = SAFFL == "Y",
  layers = tplyr_layers(
    group_count(target_var = "AGEGR1", by = "Age Group"),
    group_desc(
      target_var = "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[, c("rowlabel1", "rowlabel2", grep("^res", names(result), value = TRUE))])

Both the count and descriptive statistics layers are computed on the safety population. Individual layers can also have their own where filters, which are applied in addition to the table-level filter.

Treatment Groups

Clinical tables often need columns beyond the individual treatment arms. tplyr2 provides total groups and custom groups for this purpose.

spec <- tplyr_spec(
  cols = "TRT01P",
  total_groups = list(
    total_group("TRT01P", label = "Total")
  ),
  layers = tplyr_layers(
    group_count(target_var = "SEX")
  )
)

result <- tplyr_build(spec, tplyr_adsl)
kable(result[, c("rowlabel1", grep("^res", names(result), value = TRUE))])

spec <- tplyr_spec(
  cols = "TRT01P",
  custom_groups = list(
    custom_group(
      "TRT01P",
      "Xanomeline" = c("Xanomeline High Dose", "Xanomeline Low Dose")
    )
  ),
  layers = tplyr_layers(
    group_count(target_var = "SEX")
  )
)

result <- tplyr_build(spec, tplyr_adsl)
kable(result[, c("rowlabel1", grep("^res", names(result), value = TRUE))])

spec <- tplyr_spec(
  cols = "TRT01P",
  custom_groups = list(
    custom_group(
      "TRT01P",
      "Xanomeline" = c("Xanomeline High Dose", "Xanomeline Low Dose")
    )
  ),
  total_groups = list(
    total_group("TRT01P", label = "Total")
  ),
  layers = tplyr_layers(
    group_count(target_var = "SEX")
  )
)

result <- tplyr_build(spec, tplyr_adsl)
kable(result[, c("rowlabel1", grep("^res", names(result), value = TRUE))])

Population Data

In many clinical analyses, denominators and header Ns should come from a different dataset than the analysis data. The classic example is an adverse event table: ADAE only contains subjects who experienced events, but percentages should reflect the full safety population from ADSL.

The pop_data() configuration specifies how the population dataset maps to the spec. The actual data is provided at build time.

spec <- tplyr_spec(
  cols = "TRTA",
  pop_data = pop_data(cols = c("TRTA" = "TRT01A")),
  layers = tplyr_layers(
    group_count(
      target_var = "AEBODSYS",
      settings = layer_settings(
        distinct_by = "USUBJID"
      )
    )
  )
)

result <- tplyr_build(spec, tplyr_adae, pop_data = tplyr_adsl)
kable(head(result[, c("rowlabel1", grep("^res", names(result), value = TRUE))], 8))

A few things to note:

• cols = "TRTA" matches the treatment variable in ADAE.
• pop_data(cols = c("TRTA" = "TRT01A")) maps TRT01A in the population data to TRTA in the analysis data (format: c("analysis_name" = "pop_name")).
• distinct_by = "USUBJID" counts each subject once per body system.
• Denominators and column Ns come from the full tplyr_adsl population.

header_n <- tplyr_header_n(result)
kable(header_n)

spec <- tplyr_spec(
  cols = "TRTA",
  pop_data = pop_data(
    cols = c("TRTA" = "TRT01A"),
    where = SAFFL == "Y"
  ),
  layers = tplyr_layers(
    group_count(
      target_var = "AEBODSYS",
      settings = layer_settings(
        distinct_by = "USUBJID"
      )
    )
  )
)

result <- tplyr_build(spec, tplyr_adae, pop_data = tplyr_adsl)
kable(tplyr_header_n(result))

Data Completion

When building count layers, tplyr2 automatically completes all combinations of factor levels and cross-variables. If a treatment group has zero subjects with a given characteristic, a 0 (0.0%) row still appears rather than being dropped.

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

result <- tplyr_build(spec, tplyr_adsl)
kable(result[, c("rowlabel1", grep("^res", names(result), value = TRUE))])

Every race category appears for every treatment group, even when the count is zero.

spec <- tplyr_spec(
  cols = "TRTA",
  pop_data = pop_data(cols = c("TRTA" = "TRT01A")),
  layers = tplyr_layers(
    group_count(
      target_var = "AEDECOD",
      by = "AEBODSYS",
      settings = layer_settings(
        distinct_by = "USUBJID",
        limit_data_by = c("AEBODSYS", "AEDECOD")
      )
    )
  )
)

result <- tplyr_build(spec, tplyr_adae, pop_data = tplyr_adsl)
kable(head(result[, c("rowlabel1", "rowlabel2", grep("^res", names(result), value = TRUE))], 10))

Where to Go From Here

This vignette covered the table-level properties that control the overall structure of your tplyr2 output. For details on specific layer types and additional features, see:

• vignette("count") – group_count() for frequency tables, including nested counts, distinct subject counts, population data, and missing value handling.
• vignette("denom") – denominator control in depth (this vignette and the denominators vignette both cover pop_data; that one goes deeper on denoms_by, denom_where, and confidence intervals).
• vignette("adverse-events") – a full adverse event table built end to end, the canonical use of population data.
• vignette("desc") – group_desc() for summary statistics.
• vignette("shift") – group_shift() for baseline-by-post-baseline cross-tabulations.
• vignette("sort") – how tplyr2 orders rows.
• vignette("options") – package-level options via tplyr2_options().