Split gtsummary table by rows and/or columns

Source: R/tbl_split.R

[Experimental]
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.

tbl_split_by_rows(
  x,
  variables = NULL,
  row_numbers = NULL,
  variable_level = 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, variable_level

(tidy-select or integer)
Specifies where the table will be split.

  • variables: Tables will be separated after each of the variables specified. The x$table_body data frame must contains a 'variable' column to use this argument.

  • row_numbers: Row numbers after which the table will be split.

  • variable_level: A single column name in x$table_body. When specified, the table will be split at each unique level of the variable.

footnotes, caption

(string) [Experimental]
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 = 981		
      Drug B

N = 1021		
    
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)
1 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 = 981		
      Drug B

N = 1021		
    
    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)
1 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 = 1021		
    
Patient Died
60 (59%)
Months to Death/Censor
21.2 (14.5, 24.0)
1 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 = 1021		
    
Tumor Response
33 (34%)
    Unknown
4
Patient Died
60 (59%)
Months to Death/Censor
21.2 (14.5, 24.0)
1 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
      
        
TRT1

      		
    
Drug A

N = 982,3		
      Drug B

N = 1022,3		
    
T Stage



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