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
)Arguments
- tbl
A gtsummary table object (e.g., from
tbl_summary(),tbl_regression())- pval
Logical indicating whether to add p-values. Default is
TRUE. WhenTRUE, 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 toclean_table(symbol = ...).- .args
Optional list of arguments to use instead of individual parameters. When provided, overrides
pval,overall,last,header, andsymbolarguments.- .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_funandtest.args). Seegtsummary::add_p()documentation for available arguments.
Details
The function applies the following modifications (in order):
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 with bold significance (only stratified summary tables)
Applies automatic labels if options are set (see Options section)
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.
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).
See also
gtsummary::add_overall()for adding overall columnsgtsummary::add_p()for adding p-valuesclean_table()for additional table styling
Examples
# \donttest{
# With p-values (default)
gtsummary::trial |>
gtsummary::tbl_summary(by = trt) |>
extras()
Overall
N = 2001
Drug A
N = 981
Drug B
N = 1021
p-value2
1 Median (Q1, Q3); n (%)
2 Wilcoxon rank sum test; Pearson’s Chi-squared test
# Using .args list
extra_args <- list(pval = TRUE, overall = TRUE, last = FALSE)
gtsummary::trial |>
gtsummary::tbl_summary(by = trt) |>
extras(.args = extra_args)
Overall
N = 2001
Drug A
N = 981
Drug B
N = 1021
p-value2
1 Median (Q1, Q3); n (%)
2 Wilcoxon rank sum test; Pearson’s Chi-squared test
# Without p-values
gtsummary::trial |>
gtsummary::tbl_summary(by = trt) |>
extras(pval = FALSE)
Overall
N = 2001
Drug A
N = 981
Drug B
N = 1021
1 Median (Q1, Q3); n (%)
# Custom header text
gtsummary::trial |>
gtsummary::tbl_summary(by = trt) |>
extras(header = "Variable")
Variable
Overall
N = 2001
Drug A
N = 981
Drug B
N = 1021
p-value2
1 Median (Q1, Q3); n (%)
2 Wilcoxon rank sum test; Pearson’s Chi-squared test
# 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)
))
Overall
N = 2001
Drug A
N = 981
Drug B
N = 1021
p-value2
1 Median (Q1, Q3); n (%)
2 Welch Two Sample t-test; Pearson’s Chi-squared test; Wilcoxon rank sum test
# }