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)
a gtsummary object
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
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 1
Example 2
Example 3
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()
# \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)
# }