Modify table styling

This function is for developers. It does little checking of its arguments, by design. Most users should reach for the functions built on it: modify_header(), modify_spanning_header(), modify_column_hide(), modify_column_unhide(), modify_footnote_header(), modify_footnote_body(), modify_abbreviation(), modify_column_alignment(), modify_fmt_fun(), modify_indent(), modify_column_merge(), modify_missing_symbol(), modify_bold() and modify_italic().

modify_table_styling() records styling instructions for one or more columns by appending to the data frames of x$table_styling. The object definition article describes them.

Usage

modify_table_styling(
  x,
  columns,
  rows = NULL,
  label = NULL,
  spanning_header = NULL,
  hide = NULL,
  footnote = NULL,
  footnote_abbrev = NULL,
  align = NULL,
  missing_symbol = NULL,
  fmt_fun = NULL,
  text_format = NULL,
  undo_text_format = NULL,
  indent = NULL,
  text_interpret = "md",
  cols_merge_pattern = NULL
)

Arguments

x: (ltsummary)
An ltsummary object.
columns: (selector)
Columns of x$table_body.
rows: (predicate expression)
Expression selecting rows of x$table_body, e.g. row_type == "label". Used for footnotes, formatting functions, missing symbols, indentation and text formatting. Default is NULL, which selects every row (or, for a footnote, places it in the column header). See the section below.
label: (character)
Column header label(s), recycled over columns.
spanning_header: (string)
Text of a spanning header.
hide: (scalar logical)
Whether to hide the columns.
footnote: (string)
Footnote text.
footnote_abbrev: (string)
An abbreviation definition, e.g. "CI = Confidence Interval".
align: (string)
Column alignment, one of c("left", "right", "center").
missing_symbol: (string)
Text shown for missing values.
fmt_fun: (function)
Function that formats the values in the selected columns and rows.
text_format, undo_text_format: (string, scalar logical)
text_format is "bold" or "italic"; undo_text_format = TRUE removes the formatting instead of adding it.
indent: (integer)
Number of spaces of indentation.
text_interpret: (string)
How label, spanning_header, footnote and footnote_abbrev are interpreted: "md" (the default; the markdown subset **bold**, _italic_ and line breaks), "html" (raw HTML) or "none" (verbatim).
cols_merge_pattern: (string)
Glue-style pattern merging columns of x$table_body, e.g. "{conf.low}, {conf.high}". The first column named in the pattern must be the single column passed in columns; the other columns are hidden.

Value

An ltsummary object.

rows argument

The rows argument is a predicate expression that selects the rows the styling applies to. It is evaluated in x$table_body, so its column names are available as variables, and it must give a logical vector. To style the rows of the age variable pass rows = variable == "age"; to style the variable label rows pass rows = row_type == "label". A logical vector, a vector of row numbers or a function of table_body are also accepted.

Objects from the calling environment can be used in the expression, e.g. rows = variable == vars[1], as long as they do not share a name with a column of x$table_body. The expression is stored, not its result, and resolved when the table is printed, so it survives later changes to the table such as remove_row_type().

cols_merge_pattern argument

Merging replaces the first column of the pattern with the merged text after the formatting functions of every column have been applied, so a numeric column becomes character once merged. The merge is recorded and carried out at print time.

Examples

# Example 1 ----------------------------------
# bold the label rows of the statistic columns
trial |>
  tbl_summary(include = c(age, grade), by = trt) |>
  modify_table_styling(
    columns = all_stat_cols(),
    rows = row_type == "label",
    text_format = "bold"
  )

# Example 2 ----------------------------------
# a header, an abbreviation and a footnote in one call
trial |>
  tbl_summary(include = age, by = trt) |>
  modify_table_styling(
    columns = all_stat_cols(),
    label = c("**A**", "**B**"),
    footnote = "Median (IQR)",
    footnote_abbrev = "IQR = Interquartile Range"
  )