sumExtras (version 1.0.0)

extras: Add standard styling and formatting to gtsummary tables

Description

Applies a consistent set of formatting options to gtsummary tables including overall column, bold labels, clean headers, and optional p-values. Wraps the common workflow of adding multiple formatting functions into one call. Always succeeds by applying what works and warning about the rest.

Usage

extras(
  tbl,
  pval = TRUE,
  overall = TRUE,
  last = FALSE,
  header = "",
  symbol = "---",
  .args = NULL,
  .add_p_args = NULL
)

Value

A gtsummary table object with standard formatting applied

Arguments

tbl

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

pval

Logical indicating whether to add p-values. Default is TRUE. When TRUE, uses gtsummary's default statistical tests (Kruskal-Wallis for continuous variables with 3+ groups, chi-square for categorical variables).

overall

Logical indicating whether to add overall column

last

Logical indicating if Overall column should be last. Aligns with default from gtsummary::add_overall().

header

Character string for the label column header. Default is "" (blank). Use "Characteristic" or any custom text.

symbol

Character string for missing value replacement in clean_table(). Default is "---". Passed directly to clean_table(symbol = ...).

.args

Optional list of arguments to use instead of individual parameters. When provided, overrides pval, overall, last, header, and symbol arguments.

.add_p_args

Optional named list of arguments to pass to gtsummary::add_p(). Allows customization of statistical tests and p-value formatting. User-provided arguments override the default arguments (pvalue_fun and test.args). See gtsummary::add_p() documentation for available arguments.

Options

Set options(sumExtras.auto_labels = TRUE) for automatic labeling. See vignette("options") for details.

Pipeline Ordering

Call extras() before add_variable_group_header() and add_group_colors() last. See vignette("sumExtras-intro").

Table Type Support

Full features (overall, p-values, bold p-values) require a stratified tbl_summary or tbl_svysummary. Regression tables get bold labels, bold model p-values, header cleaning, and clean_table(). Stacked (tbl_strata) and merged (tbl_merge) tables get bold labels, header cleaning, and clean_table(). Warnings only fire when the user explicitly requests unsupported features (e.g., overall = TRUE on a non-stratified table).

Details

The function applies the following modifications (in order):

1. Bolds variable labels for emphasis (all table types)

2. Removes the "Characteristic" header label (all table types)

3. Adds an "Overall" column (only stratified summary tables)

4. Optionally adds p-values with bold significance (only stratified summary tables)

5. Applies automatic labels if options are set (see Options section)

6. Applies clean_table() styling (all table types)

The function automatically detects whether the input table is stratified (has a by argument) and what type of table it is (tbl_summary, tbl_regression, tbl_strata, etc.).

For tables that don't support overall columns or p-values (non-stratified tables, regression tables, or stacked tables), the function warns and applies only basic formatting (bold_labels and modify_header).

For merged tables (tbl_merge), call extras() on each sub-table before merging. All formatting carries through.

If any individual step fails (e.g., due to unexpected table structure), the function warns and continues without that feature.

See Also

• gtsummary::add_overall() for adding overall columns

• gtsummary::add_p() for adding p-values

• clean_table() for additional table styling

Examples

# \donttest{
# With p-values (default)
gtsummary::trial |>
  gtsummary::tbl_summary(by = trt) |>
  extras()

# Using .args list
extra_args <- list(pval = TRUE, overall = TRUE, last = FALSE)
gtsummary::trial |>
  gtsummary::tbl_summary(by = trt) |>
  extras(.args = extra_args)

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

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

# Customize add_p() behavior
gtsummary::trial |>
  gtsummary::tbl_summary(by = trt) |>
  extras(.add_p_args = list(
    test = list(age ~ "t.test", marker ~ "t.test"),
    pvalue_fun = ~ gtsummary::style_pvalue(.x, digits = 2)
  ))
# }