Introduction to sumExtras

Overview

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.

sumExtras streamlines this process by providing convenience functions that apply commonly-used formatting patterns in a single step. The package handles three main pain points:

1. Repetitive styling workflows - Combining multiple formatting steps into one function call
2. Inconsistent missing value displays - Standardizing how NA values appear across tables
3. Manual variable labeling - Automating label assignment from data dictionaries

This vignette will get you started with the core functions. For more specialized workflows, see:

• vignette("labeling") - Comprehensive guide to automatic variable labeling across tables and plots
• vignette("styling") - Advanced table styling and formatting techniques

The extras() Function

The signature function of this package, extras(), consolidates the most common table enhancements into a single step. At minimum, it adds bold labels, removes the “Characteristic” header, and standardizes missing value display. With default settings, it also adds an overall column and p-values.

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

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

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

# Table without overall column
trial |>
  tbl_summary(by = trt) |>
  extras(overall = FALSE)

# Overall column as last column (default is to set it as first)
trial |>
  tbl_summary(by = trt) |>
  extras(last = TRUE)

# Define standard table settings for a project
standard_table_args <- list(
  pval = TRUE,
  overall = TRUE,
  last = TRUE
)

# Apply consistently across multiple tables
trial |>
  select(age, grade, stage, trt) |>
  tbl_summary(by = trt) |>
  extras(.args = standard_table_args)

Cleaning Missing Values

One subtle but important aspect of table presentation is how missing or undefined values are displayed. gtsummary tables can show various representations of missing data: “0 (NA%)”, “NA (NA)”, “NA, NA”, etc. These inconsistencies create visual clutter and make tables harder to scan.

The clean_table() function (which is called automatically by extras()) standardizes all zero (0 (0%)) or missing value representations to “—”:

trial_missing |>
  tbl_summary(by = trt)

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

You can also use clean_table() independently if you prefer to build tables step-by-step:

trial_missing |>
  tbl_summary(by = trt) |>
  add_overall() |>
  add_p() |>
  clean_table()

Quick Start: Automatic Labeling

One of the most time-consuming aspects of creating publication-ready tables is labeling variables with human-readable descriptions. sumExtras provides a streamlined labeling system using data dictionaries:

# Create a simple dictionary
dictionary <- tibble::tribble(
  ~Variable,    ~Description,
  "trt",        "Chemotherapy Treatment",
  "age",        "Age at Enrollment (years)",
  "marker",     "Marker Level (ng/mL)",
  "stage",      "T Stage",
  "grade",      "Tumor Grade"
)

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

The add_auto_labels() function is intelligent and flexible:

• Pass a dictionary explicitly, or let it find one in your environment automatically
• Works with pre-labeled data (from haven, Hmisc, or manual labeling)
• Manual labels in tbl_summary() always override automatic ones
• Compatible with regression tables via tbl_regression()

Basic Theme Setup

sumExtras is designed to work best with the JAMA compact theme. Use use_jama_theme() to apply this theme to all gtsummary tables in your session:

# Apply JAMA compact theme (typically done once at the beginning)
use_jama_theme()
#> Setting theme "Compact"
#> Applied JAMA compact theme to {gtsummary}

This is equivalent to calling gtsummary::set_gtsummary_theme(gtsummary::theme_gtsummary_compact("jama")) but provides a more convenient interface. You can reset to the default gtsummary theme at any time with gtsummary::reset_gtsummary_theme().

For information about matching gt table styles, creating styled group headers, and advanced formatting techniques, see vignette("styling").

Putting It All Together

Here’s a simple workflow demonstrating how these core functions work together:

# 1. Define your dictionary (typically done once per project)
my_dictionary <- tibble::tribble(
  ~Variable,    ~Description,
  "trt",        "Chemotherapy Treatment",
  "age",        "Age at Enrollment (years)",
  "marker",     "Marker Level (ng/mL)",
  "stage",      "T Stage",
  "grade",      "Tumor Grade",
  "response",   "Tumor Response"
)

# 2. Set the recommended theme (once per session)
use_jama_theme()
#> Setting theme "Compact"
#> Applied JAMA compact theme to {gtsummary}

# 3. Create a clean, labeled table with one function call
trial |>
  select(age, marker, stage, grade, response, trt) |>
  tbl_summary(
    by = trt,
    missing = "no"
  ) |>
  add_auto_labels(dictionary = my_dictionary) |>
  extras()

That’s it! With just a few lines of code, you have a publication-ready table with automatic labeling, clean missing values, bold labels, an overall column, and p-values.

Next Steps

This vignette covered the essential functions to get you started quickly. For more advanced usage:

• vignette("labeling") - Learn about the complete labeling system, including cross-package workflows with ggplot2, controlling label priority, working with pre-labeled data, and real-world analysis examples

• vignette("styling") - Explore advanced styling techniques including group headers, background colors, text formatting, and creating visually polished tables

For detailed information about individual functions, see their help documentation:

• ?extras - Main styling function
• ?clean_table - Missing value standardization
• ?add_auto_labels - Automatic variable labeling
• ?use_jama_theme - Apply JAMA compact theme

The package is designed to reduce repetitive code while maintaining the flexibility of gtsummary’s modular approach. Use as much or as little as fits your workflow.