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) can be supplied here and are forwarded to the underlying renderer.

Usage

clerk_render(
  x,
  title = NULL,
  subtitle = NULL,
  footnote = 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 additional footnote text. Appended after any automatic footnotes (log-transform, FDR).
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().

Usage

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

Arguments

x	A clerk_tbl object.
title	Optional table title.
subtitle	Optional table subtitle.
footnote	Optional additional footnote.
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,
  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 additional footnote.
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().

Usage

render_reactable(x, title = NULL, subtitle = NULL, footnote = 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 string displayed as a note below the table.
...	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.
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.
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.
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.
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.
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")

---