Customize a Summary Table with Grouping, Missing Data, and Custom Titles

Source: R/customize_table.R

This function customizes a gtsummary summary table by adding an overall column, handling missing data, applying group-specific statistics, and updating headers and captions. It provides flexible options for grouping, displaying missing data, and customizing table titles.

customize_table(
  base_table,
  by_group = FALSE,
  var_group,
  add_total,
  show_missing_data,
  show_n_per_group,
  group_title,
  table_title,
  var_title,
  var_tot = NULL,
  var_characteristic = NULL
)

Arguments

base_table

A gtsummary table object, typically generated using functions like gtsummary::tbl_summary.

by_group

A boolean (default is FALSE) to analyse by group.

var_group

A string or NULL, specifying the variable used for grouping in the table. If NULL, no group-specific modifications are applied.

add_total

A boolean to add total column or not when var_group is specified.

show_missing_data

A boolean indicating whether to display missing data counts and percentages in the table. If TRUE, columns for missing data will be added.

show_n_per_group

A boolean indicating whether to display group sizes (n) for each level of the grouping variable.

group_title

A string specifying the title for the group column in the table.

table_title

A string specifying the title of the entire table.

var_title

A string specifying the title for the variable column in the table.

var_tot

A string specifying the name of total column. Default is NULL and will guess from theme_gtsummary_language().

var_characteristic

A string specifying the name of characteristic column. Default is NULL and will guess from theme_gtsummary_language().

Value

A customized gtsummary table object with added columns, headers, captions, and modifications based on the provided arguments.

Details

  • The show_missing_data parameter determines whether missing data counts and percentages are displayed:

    • If TRUE, missing data columns are added.

    • If FALSE, only non-missing data counts are displayed.

  • Headers for columns and spanning headers are customized using the group_title, table_title, and var_title arguments.

  • An external function modify_table_body_func is called to further modify the table body.

Examples

# Example usage with a sample gtsummary table
library(gtsummary)
#> Warning: package 'gtsummary' was built under R version 4.4.3
base_table <- trial %>%
  tbl_summary(by = "trt", missing = "no")

customize_table(
  base_table,
  var_group = "trt",
  add_total = TRUE,
  show_missing_data = TRUE,
  show_n_per_group = FALSE,
  group_title = "Treatment Group",
  table_title = "Summary Statistics",
  var_title = "Variables",
  var_tot = "Total"
)



  
Summary Statistics
  
Characteristic
      N
      Drug A
      Drug B
    
Age
189 (11)
46 (37, 60)
48 (39, 56)
Marker Level (ng/mL)
190 (10)
0.84 (0.23, 1.60)
0.52 (0.18, 1.21)
T Stage
200 (0)



    T1


28 (29%)
25 (25%)
    T2


25 (26%)
29 (28%)
    T3


22 (22%)
21 (21%)
    T4


23 (23%)
27 (26%)
Grade
200 (0)



    I


35 (36%)
33 (32%)
    II


32 (33%)
36 (35%)
    III


31 (32%)
33 (32%)
Tumor Response
193 (7)
28 (29%)
33 (34%)
Patient Died
200 (0)
52 (53%)
60 (59%)
Months to Death/Censor
200 (0)
23.5 (17.4, 24.0)
21.2 (14.5, 24.0)