modify: Modify column headers, footnotes, spanning headers, and table...

modifyR Documentation

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.


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

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

  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)



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.


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


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


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


Logical indicating if an abbreviation is being updated.


a string of the table caption/title


logical whether to include print of modify_header() example


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}".


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 are assigned based on output type.

  • gt::gt(caption=)

  • flextable::set_caption(caption=)

  • huxtable::set_caption(value=)

  • knitr::kable(caption=)

Example Output

Example 1

image of rendered example table

Example 2

image of rendered example table

Example 3

image of rendered example table


Daniel D. Sjoberg

See Also

Other tbl_summary tools: add_ci(), 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()


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

# print the column names that can be modified

# 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)

gtsummary documentation built on Dec. 7, 2022, 1:12 a.m.