Set or clear the session default preset

Stash a preset_spec in the package-internal session environment. Every subsequent tabular() chain that does not attach its own preset() inherits these knobs at render time. Mirrors ggplot2's ggplot2::theme_set(): one call up front, many tables downstream.

Usage

set_preset(new = NULL, ..., .template = NULL, .style = NULL, .reset = FALSE)

Arguments

new

A preset_spec to install wholesale. <preset_spec | NULL>: default NULL. When non-NULL, replaces the session preset in one call without touching knobs. The primary use is the save/restore round-trip (old <- set_preset(...); set_preset(old)) — new accepts any preset_spec previously returned by set_preset() or get_preset().

Mutually exclusive with ..., .template, .style, .reset: passing any of those alongside a non-NULL new raises tabular_error_input.

...

Named preset knobs. Same shape as preset(); see that verb for the full list of 13 recognised knobs. Unknown names raise tabular_error_input. Mutually exclusive with a non-NULL new.

.template

A preset_spec to bulk-apply before .... <preset_spec | NULL>: default NULL. Same semantics as preset()'s .template: every knob set away from its factory default feeds in as the base layer; user-supplied ... knobs then merge on top with shallow-merge per list-valued knob.

.style

A style_template() to layer into the session default. <style_template | NULL>: default NULL. Same semantics as preset()'s .style: the template's accumulated layers feed in as session-default style, layered before any per-spec style() calls.

.reset

Discard the existing session preset before applying .... <logical(1)>: default FALSE. With no knobs, clears the session default back to NULL.

Value

The previous session preset_spec (invisible). Returns NULL when no session preset was attached prior to the call. Capture it to round-trip a temporary override: old <- set_preset(...); set_preset(old). Mirrors ggplot2::theme_set() and base::options() — the canonical tidyverse save/restore primitive.

Details

Persistence. The session preset lives in a package-internal environment populated when tabular is loaded and emptied when the namespace unloads. There is no on-disk persistence; set the default at the top of each analysis script (or in a project-level .Rprofile) when a sticky house style is needed.

Merge, not replace. A second set_preset() call merges its knobs onto the existing session preset; unspecified knobs keep their prior value. Pass .reset = TRUE to discard the existing session preset and start from preset_spec() defaults. set_preset(.reset = TRUE) with no knobs clears the session default back to NULL.

Save and restore. Every call returns the previous session preset invisibly, the same primitive ggplot2's ggplot2::theme_set() ships. Capture it once, render, and restore by passing the saved value back as the positional new argument:

old <- set_preset(font_size = 10, paper_size = "a4")
# ... one renegade render at 10pt A4 ...
set_preset(old)        # restore

When the prior was NULL (no session preset ever attached), the restore is set_preset(.reset = TRUE) instead — set_preset(NULL) is the same shape as set_preset() and falls through to factory defaults rather than clearing the session.

Cascade with preset(). A per-spec preset() always wins over the session default. The session default fills in only when the spec carries no preset of its own.

Examples

# ---- Example 1: Sticky session default for an analysis script ----
#
# The submission's safety tables all use portrait letter, 9pt
# Times New Roman with 1-inch margins. Set once at the top of the
# analysis script and every `tabular()` chain inherits it — no
# per-table `preset()` call needed unless one table deviates.
set_preset(
  font_size   = 9,
  font_family = "Times New Roman",
  orientation = "portrait",
  paper_size  = "letter",
  margins     = 1
)

# Subsequent tabular() chains pick up the session preset at render.
demo_n <- stats::setNames(cdisc_saf_n$n, cdisc_saf_n$arm_short)
tabular(
  cdisc_saf_ae,
  titles = c(
    "Table 14.3.1",
    "Overall Summary of Adverse Events",
    "Safety Population"
  ),
  footnotes = "Subjects counted once per category."
) |>
  cols(
    stat_label = col_spec(label = "Category"),
    placebo    = col_spec(label = "Placebo\nN={demo_n['placebo']}"),
    drug_50    = col_spec(label = "Drug 50\nN={demo_n['drug_50']}"),
    drug_100   = col_spec(label = "Drug 100\nN={demo_n['drug_100']}"),
    Total      = col_spec(label = "Total\nN={demo_n['Total']}")
  )
 
Table 14.3.1
Overall Summary of Adverse Events
Safety Population
 

Category Placebo
N=86 Drug 50
N=96 Drug 100
N=72 Total
N=254
Any TEAE 65 (75.6) 84 (87.5) 68 (94.4) 217 (85.4)
Any Serious AE (SAE) 0 (0.0) 2 (2.1) 1 (1.4) 3 (1.2)
Any AE Related to Study Drug 43 (50.0) 77 (80.2) 64 (88.9) 184 (72.4)
Any AE Leading to Death 2 (2.3) 1 (1.0) 0 (0.0) 3 (1.2)
Any AE Recovered / Resolved 47 (54.7) 61 (63.5) 49 (68.1) 157 (61.8)
  Maximum severity: Mild 36 (41.9) 21 (21.9) 20 (27.8) 77 (30.3)
  Maximum severity: Moderate 24 (27.9) 47 (49.0) 40 (55.6) 111 (43.7)
  Maximum severity: Severe 5 (5.8) 16 (16.7) 8 (11.1) 29 (11.4)
Subjects counted once per category.

# ---- Example 2: Reset the session default mid-script ----
#
# The first half of the script produces safety tables at 9pt; the
# second half produces efficacy tables at 10pt on landscape A4. A
# single `set_preset(.reset = TRUE, ...)` resets the cascade before
# the second batch starts.
set_preset(font_size = 9, paper_size = "letter")
get_preset()@font_size  # 9
#> [1] 9

set_preset(
  .reset      = TRUE,
  font_size   = 10,
  orientation = "landscape",
  paper_size  = "a4"
)
get_preset()@orientation  # "landscape"
#> [1] "landscape"

# Reset the session default so subsequent examples / R sessions
# are not affected.
set_preset(.reset = TRUE)

# ---- Example 3: Save and restore around a renegade table ----
#
# Most of the submission renders portrait letter at 9pt. One
# renegade efficacy table needs landscape A4 at 10pt. Capture
# the prior session preset, render the renegade, then restore.
set_preset(font_size = 9, paper_size = "letter")

old <- set_preset(
  font_size   = 10,
  paper_size  = "a4",
  orientation = "landscape"
)
# ... one renegade render ...
if (is.null(old)) {
  set_preset(.reset = TRUE)   # was no prior — clear
} else {
  set_preset(old)              # round-trip via the positional `new` arg
}
get_preset()@paper_size  # "letter" — restored
#> [1] "letter"

# ---- Example 4: Snapshot current preset, mutate, restore ----
#
# Capture whatever the session preset is right now (may be NULL),
# let a downstream helper mutate it, then put it back when done.
set_preset(font_size = 9, paper_size = "letter")
snapshot <- get_preset()

# Simulate downstream code mutating session state.
set_preset(font_size = 11, orientation = "landscape")

# Restore. The wholesale-install path of `set_preset(new)`
# accepts any `preset_spec` returned by `get_preset()` /
# `set_preset()`.
if (is.null(snapshot)) {
  set_preset(.reset = TRUE)
} else {
  set_preset(snapshot)
}
get_preset()@font_size    # 9 — restored
#> [1] 9

# Reset for subsequent examples / R sessions.
set_preset(.reset = TRUE)

Category	Placebo N=86	Drug 50 N=96	Drug 100 N=72	Total N=254
Any TEAE	65 (75.6)	84 (87.5)	68 (94.4)	217 (85.4)
Any Serious AE (SAE)	0 (0.0)	2 (2.1)	1 (1.4)	3 (1.2)
Any AE Related to Study Drug	43 (50.0)	77 (80.2)	64 (88.9)	184 (72.4)
Any AE Leading to Death	2 (2.3)	1 (1.0)	0 (0.0)	3 (1.2)
Any AE Recovered / Resolved	47 (54.7)	61 (63.5)	49 (68.1)	157 (61.8)
Maximum severity: Mild	36 (41.9)	21 (21.9)	20 (27.8)	77 (30.3)
Maximum severity: Moderate	24 (27.9)	47 (49.0)	40 (55.6)	111 (43.7)
Maximum severity: Severe	5 (5.8)	16 (16.7)	8 (11.1)	29 (11.4)

Usage

Arguments

Value

Details

See also

Examples