Modify column headers, footnotes, spanning headers, and table captions

These functions assist with updating or adding column headers (modify_header()), footnotes (modify_footnote()), spanning headers (modify_spanning_header()), and table captions (modify_caption()). Use show_header_names() to learn the column names.

modify_header(
  x,
  update = NULL,
  ...,
  text_interpret = c("md", "html"),
  quiet = NULL,
  stat_by = NULL
)

modify_footnote(
  x,
  update = NULL,
  ...,
  abbreviation = FALSE,
  text_interpret = c("md", "html"),
  quiet = NULL
)

modify_spanning_header(
  x,
  update = NULL,
  ...,
  text_interpret = c("md", "html"),
  quiet = NULL
)

modify_caption(x, caption, text_interpret = c("md", "html"))

show_header_names(x = NULL, include_example = TRUE, quiet = NULL)

Arguments

x

a gtsummary object

update, ...

use these arguments to assign updates to headers, spanning headers, and footnotes. See examples below.

• update expects a list of assignments, with the variable name or selector on the LHS of the formula, and the updated string on the RHS. Also accepts a named list.

• ... pass individual updates outside of a list, e.g, modify_header(p.value = "**P**", all_stat_cols() ~ "**{level}**")

Use the show_header_names() to see the column names that can be modified.

text_interpret

String indicates whether text will be interpreted with gt::md() or gt::html(). Must be "md" (default) or "html".

quiet

Logical indicating whether to print messages in console. Default is FALSE

stat_by

DEPRECATED, use update = all_stat_cols() ~ "<label>" instead.

abbreviation

Logical indicating if an abbreviation is being updated.

caption

a string of the table caption/title

include_example

logical whether to include print of modify_header() example

Value

Updated gtsummary object

tbl_summary(), tbl_svysummary(), and tbl_cross()

When assigning column headers, footnotes, spanning headers, and captions for these gtsummary tables, you may use {N} to insert the number of observations. tbl_svysummary objects additionally have {N_unweighted} available.

When there is a stratifying by= argument present, the following fields are additionally available to stratifying columns: {level}, {n}, and {p} ({n_unweighted} and {p_unweighted} for tbl_svysummary objects)

Syntax follows glue::glue(), e.g. all_stat_cols() ~ "**{level}**, N = {n}".

tbl_regression()

When assigning column headers for tbl_regression tables, you may use {N} to insert the number of observations, and {N_event} for the number of events (when applicable).

captions

Captions are assigned based on output type.

• gt::gt(caption=)

• flextable::set_caption(caption=)

• huxtable::set_caption(value=)

• knitr::kable(caption=)

Example Output

Example 1

Example 2

Example 3

See also

Other tbl_summary tools: add_n.tbl_summary(), add_overall(), add_p.tbl_summary(), add_q(), add_stat_label(), bold_italicize_labels_levels, inline_text.tbl_summary(), inline_text.tbl_survfit(), separate_p_footnotes(), tbl_custom_summary(), tbl_merge(), tbl_split(), tbl_stack(), tbl_strata(), tbl_summary()

Other tbl_svysummary tools: add_n.tbl_summary(), add_overall(), add_p.tbl_svysummary(), add_q(), add_stat_label(), separate_p_footnotes(), tbl_merge(), tbl_split(), tbl_stack(), tbl_strata(), tbl_svysummary()

Other tbl_regression tools: add_global_p(), add_q(), bold_italicize_labels_levels, combine_terms(), inline_text.tbl_regression(), tbl_merge(), tbl_regression(), tbl_split(), tbl_stack(), tbl_strata()

Other tbl_uvregression tools: add_global_p(), add_q(), bold_italicize_labels_levels, inline_text.tbl_uvregression(), tbl_merge(), tbl_split(), tbl_stack(), tbl_strata(), tbl_uvregression()

Other tbl_survfit tools: add_n.tbl_survfit(), add_nevent.tbl_survfit(), add_p.tbl_survfit(), tbl_merge(), tbl_split(), tbl_stack(), tbl_strata(), tbl_survfit()

Author

Daniel D. Sjoberg

Examples

# \donttest{
# create summary table
tbl <- trial[c("age", "grade", "trt")] %>%
  tbl_summary(by = trt, missing = "no") %>%
  add_p()

# print the column names that can be modified
show_header_names(tbl)
#> 
#> ℹ As a usage guide, the code below re-creates the current column headers.
#> modify_header(
#>   label = '**Characteristic**',
#>   stat_1 = '**Drug A**, N = 98',
#>   stat_2 = '**Drug B**, N = 102',
#>   p.value = '**p-value**'
#> )
#> 
#> 
#> Column Name   Column Header       
#> ------------  --------------------
#> label         **Characteristic**  
#> stat_1        **Drug A**, N = 98  
#> stat_2        **Drug B**, N = 102 
#> p.value       **p-value**         

# Example 1 ----------------------------------
# updating column headers, footnote, and table caption
modify_ex1 <- tbl %>%
  modify_header(label = "**Variable**", p.value = "**P**") %>%
  modify_footnote(all_stat_cols() ~ "median (IQR) for Age; n (%) for Grade") %>%
  modify_caption("**Patient Characteristics** (N = {N})")

# Example 2 ----------------------------------
# updating headers, remove all footnotes, add spanning header
modify_ex2 <- tbl %>%
  modify_header(all_stat_cols() ~ "**{level}**, N = {n} ({style_percent(p)}%)") %>%
  # use `modify_footnote(everything() ~ NA, abbreviation = TRUE)` to delete abbrev. footnotes
  modify_footnote(update = everything() ~ NA) %>%
  modify_spanning_header(all_stat_cols() ~ "**Treatment Received**")

# Example 3 ----------------------------------
# updating an abbreviation in table footnote
modify_ex3 <-
  glm(response ~ age + grade, trial, family = binomial) %>%
  tbl_regression(exponentiate = TRUE) %>%
  modify_footnote(ci = "CI = Credible Interval", abbreviation = TRUE)
# }