Modify column headers and spanning headers

These functions change the headers of a table.

• modify_header() updates column headers and makes the columns visible

• modify_spanning_header() adds or updates a header spanning several columns

• remove_spanning_header() removes a spanning header

• show_header_names() prints the column names of the table and the values that can be inserted into their headers

The functions refer to columns by the names of x$table_body. Run show_header_names() to print them.

Usage

modify_header(x, ..., text_interpret = c("md", "html", "none"))

modify_spanning_header(
  x,
  ...,
  text_interpret = c("md", "html", "none"),
  level = 1L
)

remove_spanning_header(x, columns = everything(), level = 1L)

show_header_names(x, show_hidden = FALSE)

Arguments

x

(ltsummary)
An ltsummary object.

...

(formula-list)
The new headers. modify_*(colname = "new header") updates a single column, and a formula selects columns, e.g. modify_*(all_stat_cols() ~ "**{level}**"). A named list is also accepted: modify_header(x, list(label = "Variable")).

text_interpret

(string)
How the text is interpreted: "md" (the default; the markdown subset **bold**, _italic_ and line breaks), "html" (raw HTML) or "none" (shown verbatim).

level

(integer)
The level of the spanning header; 1 (the default) is closest to the column headers. The current lt release renders a single row of spanning headers, so only level 1 is shown; higher levels are stored for future use.

columns

(selector)
Columns from which to remove spanning headers.

show_hidden

(scalar logical)
Whether to print the hidden columns as well. Default is FALSE.

Value

An ltsummary object. show_header_names() returns x invisibly after printing.

Dynamic values

Header and spanning-header text can include the number of observations as {N}. The statistic columns of a summary table also provide {level}, {n} and {p}: the column's label, the number of observations behind it and their proportion. With a by variable those describe each level of it, and without one they describe the overall column. A regression table adds {N_event}, and a survival table {time} or {prob}.

Which values a column carries depends on how the table was built, and show_header_names() prints those available for each one.

The syntax follows glue, so expressions can be used as well, e.g. all_stat_cols() ~ "**{level}**, N = {n} ({style_percent(p)}%)". The functions of this package, such as style_number() and style_percent(), are available inside the braces.

See also

Other modify and format: add_variable_group_header(), bold_italicize_labels_levels, bold_p(), modify_abbreviation(), modify_caption(), modify_footnote_header(), modify_source_note(), remove_row_type(), separate_p_footnotes(), sort_p()

Examples

# create summary table
tbl <- trial |>
  tbl_summary(by = trt, missing = "no", include = c(age, grade, trt)) |>
  add_p()

# print the column names that can be modified
show_header_names(tbl)
#>  Column Name Header                   level* N*  n*  p*   
#>  label       "**Characteristic**"            200          
#>  stat_1      "**Drug A**  \\nN = 95"  Drug A 200 95  0.475
#>  stat_2      "**Drug B**  \\nN = 105" Drug B 200 105 0.525
#>  p.value     "**p-value**"                   200          
#> 
#> * These values may be placed into headers with `modify_header()`, e.g. "**{level}**, N = {n}".

# Example 1 ----------------------------------
# updating column headers
tbl |>
  modify_header(label = "**Variable**", p.value = "**P**")

# Example 2 ----------------------------------
# updating headers with the group counts, and adding a spanning header
tbl |>
  modify_header(all_stat_cols() ~ "**{level}**, N = {n} ({style_percent(p)}%)") |>
  modify_spanning_header(all_stat_cols() ~ "**Treatment Received**")

# Example 3 ----------------------------------
# a spanning header over the arms only, and the total N in the caption
tbl |>
  add_overall() |>
  modify_spanning_header(c(stat_1, stat_2) ~ "**Randomized arm**") |>
  modify_caption("**Table 1. Patient characteristics (N = {N})**")