sumExtras (version 0.3.0)

add_group_styling: Apply styling to variable group headers in gtsummary tables

Description

Adds customizable formatting to variable group headers in gtsummary tables. Variable groups are created using gtsummary::add_variable_group_header() to organize variables into sections. This function enhances table readability by making group headers visually distinct from individual variable labels.

Usage

add_group_styling(tbl, format = c("bold", "italic"), indent_labels = 0L)

Value

A gtsummary table object with specified formatting applied to variable group headers

Arguments

tbl

A gtsummary table object (e.g., from tbl_summary(), tbl_regression())

format

Character vector specifying text formatting. Options include "bold", "italic", or both. Default is c("bold", "italic").

indent_labels

Integer specifying indentation level (in spaces) for variable labels under group headers. Default is 0L (left-aligned). Set to 4L to preserve gtsummary's default group indentation, or use any non-negative integer for custom spacing.

Details

The function targets rows where row_type == 'variable_group' and applies the specified text formatting to the label column. This is particularly useful for tables with multiple sections or stratified analyses where clear visual hierarchy improves interpretation.

By default, variable labels are left-aligned (indent_labels = 0L) to distinguish them from categorical levels and statistics. Use indent_labels = 4L to preserve the default gtsummary behavior where grouped variables are indented under their group headers.

See Also

• gtsummary::modify_table_styling() for general table styling options

• gtsummary::add_variable_group_header() for creating variable group headers

Examples

# \donttest{
# Default formatting (bold and italic)
gtsummary::trial |>
  gtsummary::tbl_summary(by = trt, include = c(age, marker, grade)) |>
  gtsummary::add_variable_group_header(
    header = "Patient Characteristics",
    variables = age:grade
  ) |>
  add_group_styling()

# Bold only
gtsummary::trial |>
  gtsummary::tbl_summary(by = trt, include = c(age, marker)) |>
  gtsummary::add_variable_group_header(
    header = "Demographics",
    variables = age:marker
  ) |>
  add_group_styling(format = "bold")

# Multiple group headers
gtsummary::trial |>
  gtsummary::tbl_summary(by = trt) |>
  gtsummary::add_variable_group_header(
    header = "Demographics",
    variables = age
  ) |>
  gtsummary::add_variable_group_header(
    header = "Clinical Measures",
    variables = marker:response
  ) |>
  add_group_styling()

# Custom indentation for grouped variables
gtsummary::trial |>
  gtsummary::tbl_summary(by = trt, include = c(age, marker)) |>
  gtsummary::add_variable_group_header(
    header = "Patient Measures",
    variables = age:marker
  ) |>
  add_group_styling(indent_labels = 4L)  # Variables indented under header
# }