sumExtras (version 0.3.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. Streamlines the common workflow of adding multiple formatting functions. The function always succeeds by applying what works and warning about unsupported features.

Usage

extras(
  tbl,
  pval = TRUE,
  overall = TRUE,
  last = FALSE,
  .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().

.args

Optional list of arguments to use instead of individual parameters. When provided, overrides pval, overall, and last 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.

Table Type Support

The function applies features based on table type and stratification:

• bold_labels() and modify_header(): Work on all table types

• add_overall(): Only works on stratified summary tables (tbl_summary with by)

• add_p(): Only works on stratified summary tables (tbl_summary with by)

Full feature support: tbl_summary and tbl_svysummary with by argument

Partial support (basic formatting only): tbl_regression, tbl_strata, and non-stratified tables. When applied to these table types and overall/pval = TRUE, the function warns about unsupported features but applies the formatting that works.

Details

The function applies the following modifications:

• Bolds variable labels for emphasis (all table types)

• Removes the "Characteristic" header label (all table types)

• Adds an "Overall" column (only stratified summary tables)

• Optionally adds p-values (only stratified summary tables)

• 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 will issue a warning and continue by applying only the universally supported features (bold_labels and modify_header). This ensures the function always succeeds rather than failing midway through the pipeline.

If any individual formatting step fails (e.g., due to unexpected table structure), the function will issue a warning and continue without that feature. This provides robustness while keeping you informed of what was skipped.

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)

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

# Chain with other functions
# Create required dictionary first
dictionary <- tibble::tribble(
  ~Variable, ~Description,
  'record_id', 'Participant ID',
  'age', 'Age at enrollment',
  'sex', 'Biological sex'
)
gtsummary::trial |>
  gtsummary::tbl_summary(by = trt) |>
  add_auto_labels() |>
  extras(pval = TRUE) |>
  add_group_styling()
# }