Label and Trim Split Tables

Source: R/modify_split_caption.R

Post-process a table that was paginated with gtsummary::tbl_split_by_rows() (via its variable_level argument). For each page, a subtitle is built from the split level using a glue() pattern, and the now-redundant split column is hidden.

This is useful for any split {gtsummary} table, such as listings (tbl_listing()) split by treatment, or baseline/change tables (tbl_baseline_chg()) and shift tables (tbl_shift()) split by PARAM.

The label is set both as a {gtsummary} caption (via gtsummary::modify_caption()) and on the native variable_level attribute. The caption makes the subtitle visible when the table is printed on its own (it renders inside the table's <caption> element), while variable_level lets downstream reporting engines promote the same text to a dedicated subtitle row.

modify_split_caption(
  x,
  spl_col,
  pattern = "Parameter: {spl_level}",
  hide_spl_col = TRUE
)

Arguments

x

(tbl_split, list, or gtsummary)
a table split with gtsummary::tbl_split_by_rows(), the list of split tables, or a single split page.

spl_col

(string)
name of the column the table was split by (the variable_level passed to gtsummary::tbl_split_by_rows()). Used to hide that column on each page when hide_spl_col = TRUE.

pattern

(string)
a glue() pattern used to build each page's subtitle from the split level. The {spl_level} token is replaced by the split value. Defaults to "Parameter: {spl_level}", matching parameter-split tables such as laboratory tables split by PARAM.

hide_spl_col

(flag)
whether to hide spl_col on each split page, since it is redundant after a single-level split. Defaults to TRUE. Silently does nothing when the column is absent or already hidden.

Value

an object of the same class as x, with the split subtitle set as a caption and on the variable_level attribute (and the split column hidden) on each page.

Examples

lst <- gtsummary::trial |>
  dplyr::select(trt, age, grade) |>
  dplyr::arrange(trt) |>
  tbl_listing(split_by_rows = list(variable_level = "trt"))

# Split a listing by treatment, then subtitle each page and drop the column
modify_split_caption(lst, spl_col = "trt", pattern = "Treatment: {spl_level}")[[1]]



  
Treatment: Drug A
  
Age
      Grade
    
23
II
31
II


III
51
III
37
II
32
I
31
II
38
III
57
III
46
II
47
I
52
II
61
I
38
I
63
II
78
I
37
II
36
I
51
I
48
III
31
II
61
III
54
III
38
III
39
I
36
III
71
I
31
II
30
II
51
I
40
III


III
21
II
54
III
67
III
41
I
34
I
34
I
6
I
36
I
58
III
27
I
47
I


I
52
III
38
III
60
I
50
II
60
I
39
III
48
I
65
III
61
I
34
I


I
58
III
17
I
68
III
66
I
67
II
48
I
62
III
53
II
47
II
43
III
45
II
44
II
44
II
51
I
63
II
61
II
33
II
42
I
55
II
20
II
50
II
74
II
76
III
56
II
46
I
43
III
41
I
19
III
75
I
37
I
45
III
35
I
46
III


II
42
II
60
III
31
II
45
III


II
69
II
66
III


III
64
I

# Keep the split column and use the default "Parameter:" subtitle
modify_split_caption(lst, spl_col = "trt", hide_spl_col = FALSE)[[1]]



  
Parameter: Drug A
  
Chemotherapy Treatment
      Age
      Grade
    
Drug A
23
II
Drug A
31
II
Drug A


III
Drug A
51
III
Drug A
37
II
Drug A
32
I
Drug A
31
II
Drug A
38
III
Drug A
57
III
Drug A
46
II
Drug A
47
I
Drug A
52
II
Drug A
61
I
Drug A
38
I
Drug A
63
II
Drug A
78
I
Drug A
37
II
Drug A
36
I
Drug A
51
I
Drug A
48
III
Drug A
31
II
Drug A
61
III
Drug A
54
III
Drug A
38
III
Drug A
39
I
Drug A
36
III
Drug A
71
I
Drug A
31
II
Drug A
30
II
Drug A
51
I
Drug A
40
III
Drug A


III
Drug A
21
II
Drug A
54
III
Drug A
67
III
Drug A
41
I
Drug A
34
I
Drug A
34
I
Drug A
6
I
Drug A
36
I
Drug A
58
III
Drug A
27
I
Drug A
47
I
Drug A


I
Drug A
52
III
Drug A
38
III
Drug A
60
I
Drug A
50
II
Drug A
60
I
Drug A
39
III
Drug A
48
I
Drug A
65
III
Drug A
61
I
Drug A
34
I
Drug A


I
Drug A
58
III
Drug A
17
I
Drug A
68
III
Drug A
66
I
Drug A
67
II
Drug A
48
I
Drug A
62
III
Drug A
53
II
Drug A
47
II
Drug A
43
III
Drug A
45
II
Drug A
44
II
Drug A
44
II
Drug A
51
I
Drug A
63
II
Drug A
61
II
Drug A
33
II
Drug A
42
I
Drug A
55
II
Drug A
20
II
Drug A
50
II
Drug A
74
II
Drug A
76
III
Drug A
56
II
Drug A
46
I
Drug A
43
III
Drug A
41
I
Drug A
19
III
Drug A
75
I
Drug A
37
I
Drug A
45
III
Drug A
35
I
Drug A
46
III
Drug A


II
Drug A
42
II
Drug A
60
III
Drug A
31
II
Drug A
45
III
Drug A


II
Drug A
69
II
Drug A
66
III
Drug A


III
Drug A
64
I