Package 'clerkR'

Access a single clerkR colour by name

Description

Convenience accessor for a single named colour from the clerkR palette.

Usage

clerk_colour(name)

Arguments

name	Character string. One of the named entries in clerk_palette().

Value

A single hex colour string.

Examples

clerk_colour("navy")
clerk_colour("header_bg")

---

Synthetic partial correlation results for clerkR examples

Description

A synthetic dataset of partial correlation results (age + sex controlled) between eight predictor variables and two cognitive outcomes, designed to illustrate tbl_correlation(). All values are simulated and bear no relation to any real study.

Usage

clerk_cor_example

Format

A data frame with 16 rows and 5 variables:

variable

Predictor variable name (character).

outcome

Outcome variable name: "tmt_time" or "verbal_fluency" (character).

n

Sample size for each correlation (integer).

r

Partial correlation coefficient (numeric).

p

Two-tailed p-value (numeric).

Source

Simulated data generated in data-raw/clerk_cor_example.R.

---

Build a clerkR diverging colour scale

Description

Returns a vector of n hex colours interpolated along the clerkR diverging scale: dusty terracotta (⁠#D4907E⁠) — neutral off-white (⁠#F0EEEC⁠) — navy (⁠#293681⁠). Suitable for use with gt::data_color() or scales::col_numeric().

Usage

clerk_diverging(n = 9, reverse = FALSE)

Arguments

n	Integer. Number of colour steps (default 9). Use an odd number to include the neutral midpoint.
reverse	Logical. Reverse the scale direction (default FALSE, terracotta = low, navy = high).

Value

A character vector of n hex colour codes.

Examples

clerk_diverging()
clerk_diverging(n = 5)
clerk_diverging(n = 11, reverse = TRUE)

---

Synthetic example dataset for clerkR

Description

A synthetic dataset of 300 participants with demographic, metabolic, anthropometric, cognitive, and mental health variables, designed to illustrate tbl_descriptive() and other clerkR table constructors. All values are simulated and bear no relation to any real study.

Usage

clerk_example

Format

A data frame with 300 rows and 12 variables:

sex

Factor: "Female" / "Male".

age

Age in years (numeric).

hdl

HDL cholesterol in mmol/L (numeric).

glucose

Fasting glucose in mmol/L (numeric).

bmi

Body mass index in kg/m² (numeric).

waist

Waist circumference in cm (numeric).

systolic_bp

Systolic blood pressure in mmHg (numeric).

tmt_time

Trail Making Test completion time in seconds, log-scale analysis recommended (numeric).

verbal_fluency

Verbal fluency score — number of words in 60 s (numeric).

bdi

Beck Depression Inventory total score (numeric).

panas_neg

PANAS negative affect subscale score (numeric).

life_satisfaction

Life Satisfaction Scale total score (numeric).

Source

Simulated data generated in data-raw/clerk_example.R.

---

Synthetic heritability estimates for clerkR examples

Description

A synthetic data frame of narrow-sense heritability (h²) estimates for three cortical shape metrics across four covariate models, designed to illustrate tbl_heritability(). Column names match the output of R-itable::herit_batch() for direct compatibility. All values are simulated.

Usage

clerk_h2_example

Format

A data frame with 12 rows and 7 variables:

trait

Phenotype name (character).

covariates

Covariate model label (character).

h2

Narrow-sense heritability point estimate (numeric).

ci_lo

Lower 95% profile-likelihood CI bound (numeric).

ci_hi

Upper 95% profile-likelihood CI bound (numeric).

pval

One-sided LRT p-value (numeric).

sigma2_a

Additive genetic variance component (numeric).

sigma2_e

Residual variance component (numeric).

Source

Simulated data generated in data-raw/clerk_h2_example.R.

---

clerkR session options

Description

clerk_options() gets or sets session-level formatting defaults used by all ⁠tbl_*⁠ constructors. Defaults are loaded automatically when the package is attached and follow biomed/APA conventions.

Call with no arguments to inspect current settings. Call with named arguments to change one or more. Call with reset = TRUE to restore factory defaults.

Usage

clerk_options(
  digits = NULL,
  r_digits = NULL,
  p_digits = NULL,
  p_threshold = NULL,
  p_style = NULL,
  stars = NULL,
  star_thresholds = NULL,
  fdr_ns = NULL,
  fdr_alpha = NULL,
  fdr_ns_label = NULL,
  domain_other = NULL,
  reset = FALSE
)

Arguments

digits	Integer. Decimal places for continuous summary statistics (default 2).
r_digits	Integer. Decimal places for correlation coefficients and h² estimates (default 3).
p_digits	Integer. Decimal places for p-values (default 3).
p_threshold	Numeric. Raw p-values below this are shown as "< {threshold}" (default 0.001). Display only, not a significance threshold.
p_style	Character string controlling p-value display style: "apa" APA format: ⁠= 0.032⁠, ⁠< 0.001⁠ (default). "plain" Plain decimal: 0.032, ⁠< 0.001⁠. "stars" Significance stars only, no numeric p. "stars_p" Stars alongside numeric p.
stars	Logical. Append significance stars (default FALSE).
star_thresholds	Numeric vector of length 3. Cutoffs for *, ⁠**⁠, ⁠***⁠ (default c(0.05, 0.01, 0.001)).
fdr_ns	Logical. Replace the FDR p-value cell with fdr_ns_label when p(FDR) >= fdr_alpha (default TRUE).
fdr_alpha	Numeric. Alpha applied to the BH-adjusted p-value. Cells where p(FDR) >= fdr_alpha show fdr_ns_label (default 0.05).
fdr_ns_label	Character string for non-surviving FDR cells (default "ns").
domain_other	Character string used as the domain label for variables not assigned to any domain, and for all variables when no domains are specified. Default "" (blank — no section header shown). Set to e.g. "Other" to collect unassigned variables under a named section.
reset	Logical. Restore factory defaults (default FALSE).

Value

A named list of current option values, returned invisibly.

Examples

clerk_options()
clerk_options(p_style = "apa", stars = TRUE)
clerk_options(fdr_alpha = 0.01)
clerk_options(domain_other = "Other")
clerk_options(reset = TRUE)

---

clerkR colour palette

Description

Returns the named clerkR colour palette as a character vector of hex codes. Individual colours can be accessed by name via clerk_colour().

The palette pairs a formal cool-blue range (navy → light teal → near-white) with a dusty terracotta warm pole for diverging scales.

Usage

clerk_palette()

Value

A named character vector of hex codes.

Examples

clerk_palette()
clerk_palette()[["header_bg"]]

---

Synthetic regression results for clerkR examples

Description

A synthetic data frame of linear regression results (outcome: log TMT completion time) designed to illustrate tbl_regression(). Mimics the output of broom::tidy(lm(...), conf.int = TRUE). All values are simulated.

Usage

clerk_reg_example

Format

A data frame with 7 rows and 6 variables:

term

Model term / predictor name (character).

estimate

Regression coefficient β (numeric).

std.error

Standard error of the estimate (numeric).

conf.low

Lower 95% confidence interval bound (numeric).

conf.high

Upper 95% confidence interval bound (numeric).

p.value

Two-tailed p-value (numeric).

Source

Simulated data generated in data-raw/clerk_reg_example.R.

---

Render a clerk_tbl to its target output format

Description

Dispatches to the correct renderer based on the output slot set at construction time (tbl_descriptive(..., output = "gt"|"html"|"latex")). All render arguments (title, subtitle, footnote, footnotes) can be supplied here and are forwarded to the underlying renderer.

Usage

clerk_render(
  x,
  title = NULL,
  subtitle = NULL,
  footnote = NULL,
  footnotes = NULL,
  fdr_footnote = TRUE,
  ...
)

Arguments

x	A clerk_tbl object.
title	Optional character string for the table title.
subtitle	Optional character string for the table subtitle.
footnote	Optional character vector of blanket footnote text, rendered as one source note per element, below the table. Appended after any automatic footnotes (log-transform, FDR).
footnotes	Optional list of targeted footnotes, each attached to specific rows or columns rather than the whole table. Each element is a list with a text string and either a rows (variable names, matched against the table stub) or cols (column names) character vector. See vignette("formatting-options") for examples.
fdr_footnote	Logical. Automatically add a source note explaining the FDR correction when a p_fdr column is present (default TRUE).
...	Passed to the underlying render_gt(), render_reactable(), or render_latex().

Value

A gt_tbl, htmltools::tagList, or knit_asis object depending on the output slot of x.

Examples

tbl_descriptive(clerk_example, group = sex, output = "gt", fdr = TRUE) |>
  clerk_render(title = "Table 1")

tbl_descriptive(clerk_example, group = sex, output = "html") |>
  clerk_render(title = "Sample characteristics")

---

Build a clerkR sequential colour scale

Description

Returns a vector of n hex colours interpolated along the clerkR sequential scale: near-white (⁠#D0E7E6⁠) → navy (⁠#293681⁠). Suitable for shading columns by magnitude (e.g. heritability h², correlation r).

Usage

clerk_sequential(n = 7, reverse = FALSE)

Arguments

n	Integer. Number of colour steps (default 7).
reverse	Logical. Reverse the scale direction (default FALSE, light = low, dark = high).

Value

A character vector of n hex colour codes.

Examples

clerk_sequential()
clerk_sequential(n = 5, reverse = TRUE)

---

Apply the clerkR gt theme to a gt table

Description

Applies the clerkR visual style to an existing gt_tbl object: light teal column headers with navy text, near-white row group bars, clean borders, and consistent typography. Can be applied after any gt pipeline.

This function is called automatically by render_gt() and render_latex(); you only need it directly if you are building a gt table outside of the ⁠tbl_*⁠ constructors.

Usage

clerk_theme(gt_tbl)

Arguments

gt_tbl

A gt_tbl object.

Value

A gt_tbl object with clerkR styling applied.

Examples

## Not run: 
gt::gt(mtcars) |> clerk_theme()

## End(Not run)

---

Render a clerk_tbl as a gt table (Word / PDF)

Description

Renders a clerk_tbl as a gt table with clerkR styling applied via clerk_theme(). Domain groupings become row-group labels; log-transformed variables receive an automatic footnote; FDR-corrected tables receive an automatic source note. Typically called indirectly via clerk_render().

Domains may be nested (a named list of named lists) to express sub-sections within a domain, e.g. repeated timepoints within a "Mental health" domain. gt itself has no native support for two-level row-group headers, so a nested domain renders as a single compound row group: the domain and subdomain names joined with an em dash, e.g. "Mental health" + "Baseline" becomes one row group labelled ⁠Mental health - Baseline⁠ (rendered with a true em dash, not a hyphen). For a table with true expandable nested groups, use output = "html" instead (see render_reactable()).

Usage

render_gt(
  x,
  title = NULL,
  subtitle = NULL,
  footnote = NULL,
  footnotes = NULL,
  fdr_footnote = TRUE,
  ...
)

Arguments

x	A clerk_tbl object.
title	Optional table title.
subtitle	Optional table subtitle.
footnote	Optional character vector of blanket footnotes, one source note per element.
footnotes	Optional list of targeted footnotes. Each element is a list with text and either rows (variable names) or cols (column names).
fdr_footnote	Logical. Add an automatic FDR source note when a p_fdr column is present (default TRUE).
...	Reserved for future use.

Value

A gt_tbl object.

Examples

tbl_descriptive(clerk_example, group = sex) |>
  render_gt(title = "Table 1")

---

Render a clerk_tbl as a LaTeX table

Description

Renders a clerk_tbl as a LaTeX table via gt::as_latex(). Typically called indirectly via clerk_render().

Usage

render_latex(
  x,
  title = NULL,
  subtitle = NULL,
  footnote = NULL,
  footnotes = NULL,
  fdr_footnote = TRUE,
  ...
)

Arguments

x	A clerk_tbl object.
title	Optional table title (used as the ⁠\caption{}⁠).
subtitle	Optional subtitle appended to the caption.
footnote	Optional character vector of blanket footnotes.
footnotes	Optional list of targeted footnotes (see render_gt()).
fdr_footnote	Logical. Add an automatic FDR source note (default TRUE).
...	Reserved for future use.

Value

A knit_asis character object containing the LaTeX table source.

Examples

tbl_descriptive(clerk_example, group = sex, output = "latex") |>
  clerk_render(title = "Sample characteristics by sex")

---

Render a clerk_tbl as an interactive HTML table

Description

Renders a clerk_tbl as a reactable interactive HTML table with optional title and subtitle rendered above the widget. Typically called indirectly via clerk_render().

Unlike render_gt(), nested domains (a named list of named lists) render as genuine two-level expandable/collapsible row groups here, via reactable's groupBy = c("domain", "subdomain") – this is the one output format where nested domains show as an actual hierarchy rather than a compound label.

Usage

render_reactable(
  x,
  title = NULL,
  subtitle = NULL,
  footnote = NULL,
  footnotes = NULL,
  ...
)

Arguments

x	A clerk_tbl object.
title	Optional character string displayed as a heading above the table.
subtitle	Optional character string displayed as a subheading.
footnote	Optional character vector of blanket footnote text, displayed as a note list below the table.
footnotes	Optional list of targeted footnotes (see render_gt()). reactable has no per-cell footnote-marker equivalent, so these are displayed alongside footnote as plain note text rather than attached to specific rows/columns.
...	Passed to reactable::reactable().

Value

An htmltools::tagList containing the title, reactable widget, and optional footnote, or a bare reactable if no title/subtitle/footnote are provided.

Examples

tbl_correlation(clerk_cor_example, output = "html") |>
  clerk_render(title = "Partial correlations", subtitle = "age + sex controlled")

---

Correlation / partial correlation table

Description

Formats a tidy data frame of (partial) correlation results into a publication-ready table. Column-name arguments accept character strings. Defaults match a typical correlation results frame with columns named variable, outcome, r, and p.

Formatting defaults are inherited from clerk_options() and can be overridden per call.

Usage

tbl_correlation(
  data,
  predictor = "variable",
  outcome = "outcome",
  r = "r",
  p = "p",
  n = NULL,
  extra_cols = NULL,
  domains = list(),
  fdr = FALSE,
  fdr_within = NULL,
  r_digits = NULL,
  p_digits = NULL,
  p_threshold = NULL,
  p_style = NULL,
  stars = NULL,
  fdr_ns = NULL,
  fdr_alpha = NULL,
  domain_other = NULL,
  pivot = FALSE,
  output = c("gt", "html", "latex")
)

Arguments

data	A tidy data frame of correlation results.
predictor	Character string. Predictor column name. Default "variable".
outcome	Character string. Outcome column name. Default "outcome".
r	Character string. Correlation coefficient column. Default "r".
p	Character string. P-value column. Default "p".
n	Character string or NULL. Sample size column. Default NULL.
extra_cols	Character vector of additional columns to carry through.
domains	A named list mapping predictor names to domain/section labels. An entry may itself be a named list to create a nested sub-section within a domain (e.g. repeated timepoints) – see vignette("formatting-options").
fdr	Logical. Apply BH FDR correction (default FALSE).
fdr_within	Character string or NULL. Column to group FDR within.
r_digits	Integer. Decimal places for r.
p_digits	Integer. Decimal places for p-values.
p_threshold	Numeric. P-values below this are shown as "< {threshold}". Inherits from clerk_options()$p_threshold if NULL.
p_style	Character. P-value style.
stars	Logical. Append significance stars.
fdr_ns	Logical. Replace non-surviving FDR p-values with "ns".
fdr_alpha	Numeric. Alpha level for FDR survival (BH-adjusted p).
domain_other	Character string. Label for variables not assigned to any domain. Default "" (blank). Inherits from clerk_options()$domain_other.
pivot	Logical. Pivot to wide format (default FALSE).
output	Character string. One of "gt" (default), "html", or "latex".

Value

A clerk_tbl object with type "correlation".

Examples

tbl_correlation(
  clerk_cor_example,
  domains = list(
    "Metabolic"      = c("hdl", "glucose", "bmi"),
    "Anthropometric" = c("waist", "systolic_bp"),
    "Mental health"  = c("bdi", "panas_neg")
  ),
  fdr    = TRUE,
  output = "gt"
) |> clerk_render(title = "Partial correlations (age + sex controlled)")

---

Descriptive summary table with group comparisons (Table 1)

Description

Produces a descriptive/Table 1-style summary of a data frame, with optional group comparisons. Formatting defaults are inherited from clerk_options().

Usage

tbl_descriptive(
  data,
  group = NULL,
  vars = NULL,
  domains = list(),
  log_vars = character(0),
  digits = NULL,
  p_digits = NULL,
  p_threshold = NULL,
  p_style = NULL,
  stars = NULL,
  fdr = FALSE,
  fdr_ns = NULL,
  fdr_alpha = NULL,
  domain_other = NULL,
  overall = TRUE,
  output = c("gt", "html", "latex")
)

Arguments

data	A data frame.
group	<tidy-select> Grouping variable.
vars	<tidy-select> Variables to include. Defaults to all columns except group.
domains	A named list mapping variable names to domain/section labels. An entry may itself be a named list to create a nested sub-section within a domain (e.g. repeated timepoints) – see vignette("formatting-options").
log_vars	Character vector of log-transformed variable names.
digits	Integer. Decimal places for continuous variables.
p_digits	Integer. Decimal places for p-values.
p_threshold	Numeric. P-values below this are shown as "< {threshold}". Inherits from clerk_options()$p_threshold if NULL.
p_style	Character. P-value style ("apa", "plain", "stars", "stars_p").
stars	Logical. Append significance stars.
fdr	Logical. Apply BH FDR correction (default FALSE).
fdr_ns	Logical. Replace non-surviving FDR p-values with "ns".
fdr_alpha	Numeric. Alpha level for FDR survival (BH-adjusted p).
domain_other	Character string. Label for variables not assigned to any domain. Default "" (blank). Inherits from clerk_options()$domain_other.
overall	Logical. Include an overall column (default TRUE).
output	Character string. One of "gt", "html", or "latex".

Value

A clerk_tbl object with type "descriptive".

Examples

tbl_descriptive(
  clerk_example,
  group   = sex,
  domains = list(
    "Metabolic"    = c("hdl", "glucose", "bmi"),
    "Cognitive"    = c("tmt_time", "verbal_fluency"),
    "Mental health"= c("bdi", "panas_neg")
  ),
  log_vars = "tmt_time",
  output   = "gt"
) |> clerk_render(title = "Table 1. Sample characteristics by sex")

---

Heritability and variance components table

Description

Formats a tidy data frame of narrow-sense heritability estimates (h2) into a publication-ready table. Column-name defaults match R-itable::herit_batch() output directly. Formatting defaults inherited from clerk_options().

Usage

tbl_heritability(
  data,
  metric = "trait",
  h2 = "h2",
  ci_low = "ci_lo",
  ci_high = "ci_hi",
  p = "pval",
  sigma2_a = NULL,
  sigma2_e = NULL,
  model = NULL,
  domains = list(),
  fdr = FALSE,
  fdr_within = NULL,
  r_digits = NULL,
  p_digits = NULL,
  p_threshold = NULL,
  p_style = NULL,
  stars = NULL,
  fdr_ns = NULL,
  fdr_alpha = NULL,
  domain_other = NULL,
  output = c("gt", "html", "latex")
)

Arguments

data	A tidy data frame with one row per trait x covariate model.
metric	Character string. Trait column name. Default "trait".
h2	Character string. h2 estimate column. Default "h2".
ci_low	Character string. Lower CI column. Default "ci_lo".
ci_high	Character string. Upper CI column. Default "ci_hi".
p	Character string. P-value column. Default "pval".
sigma2_a	Character string or NULL. Additive genetic variance column.
sigma2_e	Character string or NULL. Residual variance column.
model	Character string or NULL. Covariate model column. Pass "covariates" for herit_batch() output.
domains	A named list mapping trait names to domain/section labels. An entry may itself be a named list to create a nested sub-section within a domain (e.g. repeated timepoints) – see vignette("formatting-options").
fdr	Logical. Apply BH FDR correction (default FALSE).
fdr_within	Character string or NULL. Column to group FDR within.
r_digits	Integer. Decimal places for h2 and variance components.
p_digits	Integer. Decimal places for p-values.
p_threshold	Numeric. P-values below this are shown as "< {threshold}". Inherits from clerk_options()$p_threshold if NULL.
p_style	Character. P-value style.
stars	Logical. Append significance stars.
fdr_ns	Logical. Replace non-surviving FDR p-values with "ns".
fdr_alpha	Numeric. Alpha level for FDR survival (BH-adjusted p).
domain_other	Character string. Label for variables not assigned to any domain. Default "" (blank). Inherits from clerk_options()$domain_other.
output	Character string. One of "gt", "html", or "latex".

Value

A clerk_tbl object with type "heritability".

Examples

tbl_heritability(
  clerk_h2_example,
  model    = "covariates",
  sigma2_a = "sigma2_a",
  sigma2_e = "sigma2_e",
  fdr      = TRUE,
  output   = "gt"
) |> clerk_render(title = "Heritability estimates")

---

Regression coefficients table

Description

Formats a tidy data frame of regression results into a publication-ready table. Accepts broom::tidy() output directly. Formatting defaults inherited from clerk_options().

Usage

tbl_regression(
  data,
  term = "term",
  estimate = "estimate",
  std_error = "std.error",
  conf_low = "conf.low",
  conf_high = "conf.high",
  p = "p.value",
  model = NULL,
  domains = list(),
  exponentiate = FALSE,
  fdr = FALSE,
  fdr_within = NULL,
  ci_sep = ", ",
  digits = NULL,
  p_digits = NULL,
  p_threshold = NULL,
  p_style = NULL,
  stars = NULL,
  fdr_ns = NULL,
  fdr_alpha = NULL,
  domain_other = NULL,
  output = c("gt", "html", "latex")
)

Arguments

data	A tidy data frame of regression results.
term	Character string. Model term column. Default "term".
estimate	Character string. Coefficient column. Default "estimate".
std_error	Character string. SE column. Default "std.error".
conf_low	Character string. Lower CI column. Default "conf.low".
conf_high	Character string. Upper CI column. Default "conf.high".
p	Character string. P-value column. Default "p.value".
model	Character string or NULL. Multiple-model column.
domains	A named list mapping term names to domain/section labels. An entry may itself be a named list to create a nested sub-section within a domain (e.g. repeated timepoints) – see vignette("formatting-options").
exponentiate	Logical. Exponentiate estimates and CIs (default FALSE).
fdr	Logical. Apply BH FDR correction (default FALSE).
fdr_within	Character string or NULL. Column to group FDR within.
ci_sep	Character string separating CI bounds (default ", ").
digits	Integer. Decimal places for estimates.
p_digits	Integer. Decimal places for p-values.
p_threshold	Numeric. P-values below this are shown as "< {threshold}". Inherits from clerk_options()$p_threshold if NULL.
p_style	Character. P-value style.
stars	Logical. Append significance stars.
fdr_ns	Logical. Replace non-surviving FDR p-values with "ns".
fdr_alpha	Numeric. Alpha level for FDR survival (BH-adjusted p).
domain_other	Character string. Label for variables not assigned to any domain. Default "" (blank). Inherits from clerk_options()$domain_other.
output	Character string. One of "gt", "html", or "latex".

Value

A clerk_tbl object with type "regression".

Examples

tbl_regression(
  clerk_reg_example,
  domains = list(
    "Cardiometabolic" = c("bmi", "waist", "systolic_bp"),
    "Mental health"   = c("bdi", "panas_neg")
  ),
  fdr    = TRUE,
  output = "gt"
) |> clerk_render(title = "Linear regression: TMT completion time")

---

Simple descriptive summary table (no inferential tests)

Description

Produces a concise descriptive summary — mean ± SD for continuous variables and n (%) for categorical variables — with no group comparisons or statistical tests. Formatting defaults inherited from clerk_options().

Usage

tbl_simple(
  data,
  vars = NULL,
  domains = list(),
  log_vars = character(0),
  digits = NULL,
  domain_other = NULL,
  output = c("gt", "html", "latex")
)

Arguments

data	A data frame.
vars	<tidy-select> Variables to include. Defaults to all columns.
domains	A named list mapping variable names to domain/section labels. An entry may itself be a named list to create a nested sub-section within a domain (e.g. repeated timepoints) – see vignette("formatting-options").
log_vars	Character vector of log-transformed variable names.
digits	Integer. Decimal places for continuous variables.
domain_other	Character string. Label for variables not assigned to any domain. Default "" (blank). Inherits from clerk_options()$domain_other.
output	Character string. One of "gt" (default), "html", or "latex".

Value

A clerk_tbl object with type "simple".

Examples

tbl_simple(
  clerk_example,
  domains  = list(
    "Metabolic"    = c("hdl", "glucose", "bmi"),
    "Mental health"= c("bdi", "panas_neg")
  ),
  log_vars = "tmt_time",
  output   = "gt"
) |> clerk_render(title = "Descriptive statistics")

---