Set or Update Study-Level Table Theme

fr_theme() sets study-level defaults that are automatically applied to every subsequent fr_table() call. Define font size, page layout, tokens, running header/footer, and line rules once at the top of your program; all tables inherit these settings without repeating them.

Usage

fr_theme(
  orientation = NULL,
  paper = NULL,
  margins = NULL,
  col_gap = NULL,
  font_family = NULL,
  font_size = NULL,
  spaces = NULL,
  split = NULL,
  stub = NULL,
  pagehead = NULL,
  pagefoot = NULL,
  tokens = NULL,
  hlines = NULL,
  vlines = NULL,
  spacing = NULL,
  n_format = NULL,
  continuation = NULL,
  page_by_bold = NULL,
  page_by_align = NULL,
  page_by_visible = NULL,
  group_keep = NULL,
  header = NULL,
  footnote_separator = NULL
)

Arguments

orientation: "landscape" or "portrait". NULL leaves unchanged.
paper: "letter", "a4", or "legal". NULL leaves unchanged.
margins: Margin(s) in inches (same formats as fr_page()). NULL leaves unchanged.
col_gap: Inter-column padding in points (integer). NULL leaves unchanged. See fr_page() for details.
font_family: Font family name. NULL leaves unchanged.
font_size: Font size in points. NULL leaves unchanged.
spaces: How to handle leading spaces in cell data. One of "indent" (convert to paragraph-level indent) or "preserve" (keep literal spaces). NULL leaves unchanged. See fr_cols() .spaces parameter for details.
split: Logical. TRUE to enable column splitting for wide tables, FALSE to disable. NULL leaves unchanged. See fr_cols() .split parameter for details.
stub: Character vector of column names to mark as stub columns (repeated in every panel during column splitting). NULL leaves unchanged. See fr_col() stub parameter for details.
pagehead: Named list with left, center, right, font_size, bold elements — same as fr_pagehead() arguments. NULL leaves unchanged.
pagefoot: Named list with left, center, right, font_size, bold elements — same as fr_pagefoot() arguments. NULL leaves unchanged.
tokens: Named list of {token} values. NULL leaves unchanged.
hlines: Horizontal rule preset string (e.g. "header"). NULL leaves unchanged.
vlines: Vertical rule preset string (e.g. "box"). NULL leaves unchanged.
spacing: Named list with titles_after, footnotes_before, pagehead_after, pagefoot_before, page_by_after (integer blank lines). NULL leaves unchanged. See fr_spacing().
n_format: A glue-style format string for N-count labels. Applied to all tables that use fr_col(n = ...) or fr_cols(.n = ...) without an explicit .n_format. Available tokens: {label} and {n}. NULL leaves unchanged.
continuation: Character scalar appended to column headers on continuation pages (e.g. "(continued)"). NULL leaves unchanged. See fr_page() for details.
page_by_bold: Logical. Whether page_by group labels are bold. NULL leaves unchanged. See fr_rows() for details.
page_by_align: Alignment for page_by group labels. One of "left", "center", "right", or "decimal". NULL leaves unchanged. See fr_rows() for details.
page_by_visible: Logical. Whether page_by group labels are displayed. NULL leaves unchanged. See fr_rows() for details.
group_keep: Logical. Whether group_by groups are kept together on the same page. NULL leaves unchanged. See fr_rows() for details.
header: Named list of header defaults. Supports all fr_header() parameters: bold, align, valign, bg, fg, font_size, repeat_on_page, plus span_gap (logical, insert gap columns between adjacent spans, default TRUE). NULL leaves unchanged.
footnote_separator: Logical. Whether to draw a separator above the footnote block. NULL leaves unchanged.

Value

Invisibly NULL.

Details

This follows the same pattern as ggplot2 theme management. Calling fr_theme(...) (or its alias fr_theme_set(...)) merges new settings into the current global theme without discarding keys you did not mention. This is analogous to ggplot2::theme_update().

Use fr_theme_reset() to clear all settings and return to built-in defaults, or fr_theme_get() to inspect the current state.

How the theme is applied

When fr_table() is called, it automatically applies the stored theme to the new fr_spec. You can still override any setting per-table by calling the corresponding verb after fr_table(). Per-table overrides always win.

Theme settings are stored in the package's internal environment and persist for the duration of the R session. Call fr_theme_reset() to clear all settings and fr_theme_get() to inspect the current theme.

Examples

## ── Define study theme at the top of your program ────────────────────────

fr_theme(
  orientation = "landscape",
  paper       = "letter",
  font_size   = 9,
  tokens      = list(study = "TFRM-2024-001", cutoff = "31DEC2024"),
  pagehead    = list(
    left  = "Study: {study}",
    right = "Database Cutoff: {cutoff}"
  ),
  pagefoot    = list(
    left  = "{program}",
    right = "{datetime}"
  ),
  hlines = "header",
  vlines = "box"
)

# All subsequent fr_table() calls inherit the theme — no need to repeat
tbl_demog |>
  fr_table() |>
  fr_titles("Table 14.1.1 Demographics", "Full Analysis Set")
#> 
#> ── fr_spec: Table 
#> Data: 28 rows x 6 columns
#> Page: landscape letter, 9pt Courier New
#> Titles (2):
#> 1. [center] "Table 14.1.1 Demographics"
#> 2. [center] "Full Analysis Set"
#> Header: valign=bottom
#> Rules: 1 hline(s)

tbl_ae_soc |>
  fr_table() |>
  fr_titles("Table 14.3.2 Adverse Events", "Safety Analysis Set")
#> 
#> ── fr_spec: Table 
#> Data: 96 rows x 7 columns
#> Page: landscape letter, 9pt Courier New
#> Titles (2):
#> 1. [center] "Table 14.3.2 Adverse Events"
#> 2. [center] "Safety Analysis Set"
#> Header: valign=bottom
#> Rules: 1 hline(s)

## ── Set section spacing (blank lines between table parts) ─────────────────

fr_theme(spacing = list(titles_after = 1L, footnotes_before = 1L))

## ── Merge additional settings (does not discard existing ones) ────────────

fr_theme(font_size = 9, hlines = "header")
fr_theme(vlines = "box")          # adds vlines; font_size and hlines kept
fr_theme_get()                    # inspect
#> $orientation
#> [1] "landscape"
#> 
#> $paper
#> [1] "letter"
#> 
#> $font_size
#> [1] 9
#> 
#> $pagehead
#> $pagehead$left
#> [1] "Study: {study}"
#> 
#> $pagehead$right
#> [1] "Database Cutoff: {cutoff}"
#> 
#> 
#> $pagefoot
#> $pagefoot$left
#> [1] "{program}"
#> 
#> $pagefoot$right
#> [1] "{datetime}"
#> 
#> 
#> $tokens
#> $tokens$study
#> [1] "TFRM-2024-001"
#> 
#> $tokens$cutoff
#> [1] "31DEC2024"
#> 
#> 
#> $hlines
#> [1] "header"
#> 
#> $vlines
#> [1] "box"
#> 
#> $spacing
#> $spacing$titles_after
#> [1] 1
#> 
#> $spacing$footnotes_before
#> [1] 1
#> 
#> 

## ── Override a theme setting for one specific table ───────────────────────

tbl_ae_soc |>
  fr_table() |>
  fr_page(orientation = "portrait")   # overrides the landscape theme default
#> 
#> ── fr_spec: Table 
#> Data: 96 rows x 7 columns
#> Page: portrait letter, 9pt Courier New
#> Header: valign=bottom
#> Rules: 1 hline(s)

## ── Theme with spacing configuration ──────────────────────────────────────

fr_theme_reset()
fr_theme(
  font_size = 9,
  spacing   = list(titles_after = 2L, footnotes_before = 2L,
                   pagehead_after = 1L)
)
fr_theme_get()$spacing   # check the spacing settings
#> $titles_after
#> [1] 2
#> 
#> $footnotes_before
#> [1] 2
#> 
#> $pagehead_after
#> [1] 1
#> 

## ── Theme with leading-space handling ────────────────────────────────────

fr_theme_reset()
fr_theme(spaces = "indent")   # default: leading spaces → paragraph indent
fr_theme_get()$spaces         # "indent"
#> [1] "indent"

fr_theme(spaces = "preserve") # keep leading spaces as literal characters
fr_theme_get()$spaces         # "preserve"
#> [1] "preserve"

## ── Theme with footnote_separator ────────────────────────────────────────

fr_theme_reset()
fr_theme(footnote_separator = FALSE, hlines = "header")
fr_theme_get()$footnote_separator   # FALSE
#> [1] FALSE

## ── Theme auto-applied: inspect spec after fr_table() ────────────────────

fr_theme_reset()
fr_theme(font_size = 8, orientation = "portrait", hlines = "header")
spec <- tbl_demog |> fr_table()
spec$page$font_size      # 8 (inherited from theme)
#> [1] 8
spec$page$orientation    # "portrait" (inherited from theme)
#> [1] "portrait"

## ── Reset all theme settings ──────────────────────────────────────────────

fr_theme_reset()