Variable Group Header

Some data are inherently grouped, and should be reported together. Grouped variables are all indented together. This function indents the variables that should be reported together while adding a header above the group.

Usage

add_variable_group_header(x, header, variables, indent = 4L)

Arguments

x

(tbl_summary)
gtsummary object of class 'tbl_summary'

header

(string)
string of the header to place above the variable group

variables

(tidy-select)
Variables to group that appear in x$table_body. Selected variables should be appear consecutively in table.

indent

(integer)
An integer indicating how many space to indent text. All rows in the group will be indented by this amount. Default is 4.

Value

a gtsummary table

Details

This function works by inserting a row into the x$table_body and indenting the group of selected variables. This function cannot be used in conjunction with all functions in gtsummary; for example, bold_labels() will bold the incorrect rows after running this function.

Examples

# Example 1 ----------------------------------
set.seed(11234)
data.frame(
  exclusion_age = sample(c(TRUE, FALSE), 20, replace = TRUE),
  exclusion_mets = sample(c(TRUE, FALSE), 20, replace = TRUE),
  exclusion_physician = sample(c(TRUE, FALSE), 20, replace = TRUE)
) |>
  tbl_summary(
    label = list(exclusion_age = "Age",
                 exclusion_mets = "Metastatic Disease",
                 exclusion_physician = "Physician")
  ) |>
  add_variable_group_header(
    header = "Exclusion Reason",
    variables = starts_with("exclusion_")
  ) |>
  modify_caption("**Study Exclusion Criteria**")


  
Study Exclusion Criteria

  
Characteristic
      
N = 201
    
Exclusion Reason

    Age
9 (45%)
    Metastatic Disease
10 (50%)
    Physician
8 (40%)
1 n (%)
    

# Example 2 ----------------------------------
lm(marker ~ trt + grade + age, data = trial) |>
  tbl_regression() |>
  add_global_p(keep = TRUE, include = grade) |>
  add_variable_group_header(
    header = "Treatment:",
    variables = trt
  ) |>
  add_variable_group_header(
    header = "Covariate:",
    variables = -trt
  ) |>
  # indent levels 8 spaces
  modify_column_indent(
    columns = "label",
    rows = row_type == "level",
    indent = 8L
  )


  
Characteristic
      
Beta
      
95% CI
      
p-value
    
Treatment:





    Chemotherapy Treatment





        Drug A
—
—

        Drug B
-0.18
-0.43, 0.08
0.2
Covariate:





    Grade




0.052
        I
—
—

        II
-0.38
-0.68, -0.07
0.017
        III
-0.11
-0.42, 0.20
0.5
    Age
0.00
-0.01, 0.01
>0.9
Abbreviation: CI = Confidence Interval