Introduction to sumExtras

The extras() Function

If you’ve worked with {gtsummary} before, you’re familiar with the typical workflow of building summary tables: creating a base table with tbl_summary(), then progressively adding features like overall columns, p-values, and formatting tweaks. While {gtsummary}’s modular approach provides flexibility, the same sequence of functions appears repeatedly in analysis scripts.

extras() consolidates the most common {gtsummary} formatting steps into one call: bold labels, a clean header, an overall column, p-values, and missing value cleanup.

theme_gtsummary_compact("jama")

trial |>
  tbl_summary(by = trt) |>
  add_overall() |>
  add_p() |>
  bold_labels() |>
  bold_p() |>
  modify_header(label = "")

use_jama_theme()

trial |>
  tbl_summary(by = trt) |>
  extras()

# Without p-values
trial |>
  tbl_summary(by = trt) |>
  extras(pval = FALSE)

# Overall column last instead of first
trial |>
  tbl_summary(by = trt) |>
  extras(last = TRUE)

# Custom header text
trial |>
  tbl_summary(by = trt) |>
  extras(header = "Variable")

my_args <- list(pval = TRUE, overall = TRUE, last = TRUE)

trial |>
  select(age, grade, stage, trt) |>
  tbl_summary(by = trt) |>
  extras(.args = my_args)

# Regression tables work too
glm(response ~ age + grade, data = trial, family = binomial) |>
  tbl_regression(exponentiate = TRUE) |>
  extras()

t1 <- trial |>
  tbl_summary(by = trt, include = c(age, grade)) |>
  extras()

t2 <- trial |>
  tbl_summary(by = trt, include = c(marker, stage)) |>
  extras()

tbl_merge(list(t1, t2), tab_spanner = c("**Set A**", "**Set B**"))

Cleaning Missing Values

clean_table() standardizes missing or zero-count representations ("0 (NA%)", "NA (NA)", "NA, NA", etc.) to "---". It runs automatically inside extras(), but you can also use it on its own. The symbol parameter controls the replacement text (default "---"). You can also pass symbol through extras().

demo_trial <- trial |>
  mutate(
    age = if_else(trt == "Drug B", 0, age),
    marker = if_else(trt == "Drug A", NA, marker)
  ) |>
  select(trt, age, marker)

demo_trial |>
  tbl_summary(by = trt)

demo_trial |>
  tbl_summary(by = trt) |>
  clean_table()

Automatic Labeling

add_auto_labels() applies human-readable variable labels from a dictionary. Manual labels set in tbl_summary() always take priority.

dictionary <- tibble::tribble(
  ~variable,    ~description,
  "trt",        "Chemotherapy Treatment",
  "age",        "Age at Enrollment (years)",
  "marker",     "Marker Level (ng/mL)",
  "stage",      "T Stage",
  "grade",      "Tumor Grade"
)

trial |>
  tbl_summary(by = trt, include = c(age, grade, marker)) |>
  add_auto_labels(dictionary = dictionary) |>
  extras()

For more on label priority, pre-labeled data, and auto-discovery, see vignette("labeling").

Pipeline Order

When combining with group headers and styling, order matters:

tbl_summary(by = ...) |>
  extras() |> # always first
  add_variable_group_header() |> # after extras()
  add_group_styling() |> # format group headers
  add_group_colors() # must be last (converts to gt)

add_variable_group_header() must come after extras(), and add_group_colors() must be last since it converts the table to gt.

Other Vignettes

• vignette("labeling") – dictionary-based labeling
• vignette("themes") – JAMA compact themes for {gtsummary} and {gt} for gtsummary and gt tables
• vignette("styling") – group headers, formatting, and background colors
• vignette("options") – .Rprofile options for automatic labeling