Set, get, and reset the ltsummary theme

A theme is a named list of theme elements that changes the defaults of the package's functions: the statistics tbl_summary() reports, the tests add_p() runs, the decimal mark, the language of the default headers and footnotes, and so on. Themes only change defaults; an argument passed explicitly always wins, and a theme outranks the ltsummary.* options.

set_ltsummary_theme() activates the elements of x on top of whatever theme is already active, so themes layer; reset_ltsummary_theme() clears every element. get_ltsummary_theme() returns the active theme as a named list. with_ltsummary_theme() evaluates one expression with a theme active and then restores the previous theme, which keeps code chunks and tests self-contained, and without_ltsummary_theme() evaluates one with no theme active, the package defaults, before restoring it. check_ltsummary_theme() reports whether a list is a valid theme without setting it.

Element names follow gtsummary's grammar, "<fn>-<kind>:<name>", e.g. "tbl_summary-arg:statistic" or "pkgwide-str:language", so a theme list written for gtsummary carries over element by element. The theme_ltsummary constructors return ready-made lists.

Usage

set_ltsummary_theme(x)

get_ltsummary_theme()

reset_ltsummary_theme()

check_ltsummary_theme(x)

with_ltsummary_theme(x, expr)

without_ltsummary_theme(expr, env = parent.frame())

Arguments

x

(named list)
A named list of theme elements, e.g. the return value of a theme_ltsummary_*() function called with set_theme = FALSE.

expr

An expression to evaluate while the theme of x is active, or with no theme active.

env

(environment)
Where expr is evaluated. Default is the calling environment.

Value

set_ltsummary_theme(), reset_ltsummary_theme() and check_ltsummary_theme() return NULL invisibly; get_ltsummary_theme() returns a named list; with_ltsummary_theme() and without_ltsummary_theme() return the value of expr.

See also

The theme_ltsummary_*() constructors.

Other themes: theme_ltsummary

Examples

# activate a theme, build a table, then clear it
set_ltsummary_theme(theme_ltsummary_mean_sd(set_theme = FALSE))
tbl_summary(trial, include = age)
reset_ltsummary_theme()

# scope a theme to one expression
with_ltsummary_theme(
  theme_ltsummary_journal("jama", set_theme = FALSE),
  tbl_summary(trial, by = trt, include = age)
)

# the package defaults while a theme is active
set_ltsummary_theme(theme_ltsummary_mean_sd(set_theme = FALSE))
without_ltsummary_theme(tbl_summary(trial, include = age))
reset_ltsummary_theme()