Split gtsummary table by rows and/or columns — tbl_split

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.

Value

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

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.

Examples

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


  Characteristic
      Drug A

N = 98¹
      Drug B

N = 102¹
    
Tumor Response
28 (29%)
33 (34%)
    Unknown
3
4
Patient Died
52 (53%)
60 (59%)
Months to Death/Censor
23.5 (17.4, 24.0)
21.2 (14.5, 24.0)
¹ Median (Q1, Q3); n (%)
    

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


  Characteristic
      Drug A

N = 98¹
      Drug B

N = 102¹
    
    T3
22 (22%)
21 (21%)
    T4
23 (23%)
27 (26%)
Grade



    I
35 (36%)
33 (32%)
    II
32 (33%)
36 (35%)
    III
31 (32%)
33 (32%)
Tumor Response
28 (29%)
33 (34%)
    Unknown
3
4
Patient Died
52 (53%)
60 (59%)
Months to Death/Censor
23.5 (17.4, 24.0)
21.2 (14.5, 24.0)
¹ Median (Q1, Q3); n (%)
    

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


  Characteristic
      Drug B

N = 102¹
    
Patient Died
60 (59%)
Months to Death/Censor
21.2 (14.5, 24.0)
¹ n (%); Median (Q1, Q3)
    

# 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")) |>
  dplyr::last() # Print only last table for simplicity


  Characteristic
      Drug B

N = 102¹
    
Tumor Response
33 (34%)
    Unknown
4
Patient Died
60 (59%)
Months to Death/Censor
21.2 (14.5, 24.0)
¹ Median (Q1, Q3); n (%)
    

# 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") |>
  dplyr::nth(n = 2) # Print only one but not last table for simplicity


  Characteristic
      
        TRT¹
      
    
Drug A

N = 98^2,3
      Drug B

N = 102^2,3
    
T Stage



    T1
28 (29%)
25 (25%)
    T2
25 (26%)
29 (28%)
    T3
22 (22%)
21 (21%)
    T4
23 (23%)
27 (26%)
¹ Treatment
    
² Median (Q1, Q3); n (%)
    
³ All but four subjects received both treatments in a crossover design

Characteristic	Drug A N = 98¹	Drug B N = 102¹
Tumor Response	28 (29%)	33 (34%)
Unknown	3	4
Patient Died	52 (53%)	60 (59%)
Months to Death/Censor	23.5 (17.4, 24.0)	21.2 (14.5, 24.0)
¹ Median (Q1, Q3); n (%)

Characteristic	Drug A N = 98¹	Drug B N = 102¹
T3	22 (22%)	21 (21%)
T4	23 (23%)	27 (26%)
Grade
I	35 (36%)	33 (32%)
II	32 (33%)	36 (35%)
III	31 (32%)	33 (32%)
Tumor Response	28 (29%)	33 (34%)
Unknown	3	4
Patient Died	52 (53%)	60 (59%)
Months to Death/Censor	23.5 (17.4, 24.0)	21.2 (14.5, 24.0)
¹ Median (Q1, Q3); n (%)

Characteristic	TRT¹
Characteristic	Drug A N = 98^2,3	Drug B N = 102^2,3
T Stage
T1	28 (29%)	25 (25%)
T2	25 (26%)	29 (28%)
T3	22 (22%)	21 (21%)
T4	23 (23%)	27 (26%)
¹ Treatment
² Median (Q1, Q3); n (%)
³ All but four subjects received both treatments in a crossover design