Stratified tables

Builds one table per stratum of data and combines them into a single table with tbl_merge() (side by side, the default) or tbl_stack() (on top of each other). The tables are built independently within each stratum, so combining works best when they are alike; see tbl_merge(). The interface is that of gtsummary::tbl_strata().

tbl_strata() passes each stratum's data frame to .tbl_fun as .x; tbl_strata2() also passes the stratum's evaluated .header as .y. The data frame handed to .tbl_fun no longer contains the strata columns. Rows where a strata column is NA form their own stratum, labelled "NA".

The deprecated .quiet argument of gtsummary is not mirrored; pass .combine_args = list(quiet = TRUE) to silence the combine step.

Usage

tbl_strata(
  data,
  strata,
  .tbl_fun,
  ...,
  .sep = ", ",
  .combine_with = c("tbl_merge", "tbl_stack"),
  .combine_args = NULL,
  .header = ifelse(.combine_with == "tbl_merge", "**{strata}**", "{strata}")
)

tbl_strata2(
  data,
  strata,
  .tbl_fun,
  ...,
  .sep = ", ",
  .combine_with = c("tbl_merge", "tbl_stack"),
  .combine_args = NULL,
  .header = ifelse(.combine_with == "tbl_merge", "**{strata}**", "{strata}")
)

Arguments

data

(data.frame)
A data frame.

strata

(selector)
Columns of data to stratify by. Only observed combinations of their values appear.

.tbl_fun

(function or formula)
The table built within each stratum: a function of the stratum's data frame, or a one-sided formula where .x is the data frame, e.g. ~ .x |> tbl_summary() |> add_p(). In tbl_strata2() the stratum's header is available as .y.

...

Additional arguments passed to .tbl_fun.

.sep

(string)
Separator between the values of several strata variables in the headers. Default is ", ".

.combine_with

(string)
"tbl_merge" or "tbl_stack", the function that combines the stratified tables. Default is "tbl_merge".

.combine_args

(named list)
Additional arguments passed to the combine function, e.g. list(group_header = NULL) to stack without group rows.

.header

(string)
Header placed over (merge) or above (stack) each stratum's table. The values {strata} (the stratum), {n} (rows in the stratum), {N} (rows in data) and {p} (n/N) are available in braces. Default is "**{strata}**" when merging and "{strata}" when stacking.

Value

A table of class c("tbl_strata", <combine class>, "ltsummary") whose df_strata element records the strata and their headers.

See also

Other stack and merge: tbl_merge(), tbl_split_by_rows(), tbl_stack(), tbl_strata_nested_stack()

Other table builders: tbl_continuous(), tbl_cross(), tbl_custom_summary(), tbl_likert(), tbl_merge(), tbl_regression(), tbl_stack(), tbl_strata_nested_stack(), tbl_summary(), tbl_survfit(), tbl_uvregression(), tbl_wide_summary()

Examples

# Example 1 ----------------------------------
# a summary table within each tumor grade
trial |>
  tbl_strata(
    strata = grade,
    .tbl_fun = ~ .x |> tbl_summary(by = trt, include = c(age, stage), missing = "no"),
    .header = "**Grade {strata}**, N = {n}"
  )

# Example 2 ----------------------------------
# stacked instead of merged, with the header as the group row
trial |>
  tbl_strata(
    strata = grade,
    .tbl_fun = ~ .x |> tbl_summary(include = c(age, response), missing = "no"),
    .combine_with = "tbl_stack"
  )
#> Column headers among stacked tables differ.
#> ℹ Use `modify_header()` to update or `quiet = TRUE` to suppress this message.
#> Table 1 Column Name   Header
#> label                 "**Characteristic**"
#> stat_0                "**N = 62**"
#> Table 2 Column Name   Header
#> label                 "**Characteristic**"
#> stat_0                "**N = 83**"
#> Table 3 Column Name   Header
#> label                 "**Characteristic**"
#> stat_0                "**N = 55**"

# Example 3 ----------------------------------
# tbl_strata2() passes the header to the function as .y
trial |>
  tbl_strata2(
    strata = grade,
    .tbl_fun = ~ .x |>
      tbl_summary(include = response, missing = "no", label = list(response = .y)) |>
      modify_header(stat_0 = "**Rate**"),
    .combine_with = "tbl_stack",
    .combine_args = list(group_header = NULL)
  )