tbl_split_by: Split gtsummary table by rows and/or columns

In gtsummary: Presentation-Ready Data Summary and Analytic Result Tables

Split gtsummary table by rows and/or columns

Description

The tbl_split_by_rows() and tbl_split_by_columns() functions split a single gtsummary table into multiple tables. Both column-wise splitting (that is, splits by columns in x$table_body) and row-wise splitting is possible.

Usage

tbl_split_by_rows(
  x,
  variables = NULL,
  row_numbers = NULL,
  footnotes = c("all", "first", "last"),
  caption = c("all", "first", "last")
)

tbl_split_by_columns(
  x,
  keys,
  groups,
  footnotes = c("all", "first", "last"),
  caption = c("all", "first", "last")
)

## S3 method for class 'tbl_split'
print(x, ...)

Arguments

x	(gtsummary or list) gtsummary table.
variables, row_numbers	(tidy-select or integer) variables or row numbers at which to split the gtsummary table rows (tables will be separated after each of these variables).
footnotes, caption	(string) can be either "first", "all", or "last", to locate global footnotes or caption only on the first, in each, or in the last table, respectively. It defaults to "all". Reference footnotes are always present wherever they appear.
keys	(tidy-select) columns to be repeated in each table split. It defaults to the first column if missing (usually label column).
groups	(list of character vectors) list of column names that appear in x$table_body. Each group of column names represent a different table in the output list.
...	These dots are for future extensions and must be empty.

Details

Run show_header_names() to print all column names to split by.

Footnotes and caption handling are experimental and may change in the future.

row_numbers indicates the row numbers at which to split the table. It means that the table will be split after each of these row numbers. If the last row is selected, the split will not happen as it is supposed to happen after the last row.

Value

tbl_split object. If multiple splits are performed (e.g., both by row and columns), the output is returned a single level list.

Examples

# Example 1 ----------------------------------
# Split by rows
trial |>
  tbl_summary(by = trt) |>
  tbl_split_by_rows(variables = c(marker, grade)) |>
  tail(n = 1) # Print only last table for simplicity

# Example 2 ----------------------------------
# Split by rows with row numbers
trial |>
  tbl_summary(by = trt) |>
  tbl_split_by_rows(row_numbers = c(5, 7)) |>
  tail(n = 1) # Print only last table for simplicity

# Example 3 ----------------------------------
# Split by columns
trial |>
  tbl_summary(by = trt, include = c(death, ttdeath)) |>
  tbl_split_by_columns(groups = list("stat_1", "stat_2")) |>
  tail(n = 1) # Print only last table for simplicity

# Example 4 ----------------------------------
# Both row and column splitting
trial |>
  tbl_summary(by = trt) |>
  tbl_split_by_rows(variables = c(marker, grade)) |>
  tbl_split_by_columns(groups = list("stat_1", "stat_2")) |>
  tail(n = 1) # Print only last table for simplicity

# Example 5 ------------------------------
# Split by rows with footnotes and caption
trial |>
  tbl_summary(by = trt, missing = "no") |>
  modify_footnote_header(
    footnote = "All but four subjects received both treatments in a crossover design",
    columns = all_stat_cols(),
    replace = FALSE
  ) |>
  modify_footnote_body(
    footnote = "Tumor grade was assessed _before_ treatment began",
    columns = "label",
    rows = variable == "grade" & row_type == "label"
  ) |>
  modify_spanning_header(
    c(stat_1, stat_2) ~ "**TRT**"
  ) |>
  modify_abbreviation("I = 1, II = 2, III = 3") |>
  modify_caption("_Some caption_") |>
  modify_footnote_spanning_header(
    footnote = "Treatment",
    columns = c(stat_1)
  ) |>
  modify_source_note("Some source note!") |>
  tbl_split_by_rows(variables = c(marker, stage, grade), footnotes = "last", caption = "first") |>
  tail(n = 2) |>
  head(n = 1) # Print only one but not last table for simplicity

gtsummary documentation built on Aug. 9, 2025, 1:08 a.m.