Heritability and variance components table

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")


  
Heritability estimates
    

      
covariates
      
h²
      
95% CI
      
p
      
σ²a
      
σ²e
      
p (FDR)
    

    
K (tension)
unadj
0.480
[0.280, 0.700]
< 0.001
0.312
0.338
< 0.001
S (shape)
unadj
0.730
[0.570, 0.880]
< 0.001
0.474
0.176
< 0.001
I (isometric)
unadj
0.450
[0.270, 0.640]
< 0.001
0.293
0.358
< 0.001
K (tension)
cov1
0.610
[0.450, 0.790]
< 0.001
0.396
0.254
< 0.001
S (shape)
cov1
0.810
[0.620, 1.000]
< 0.001
0.527
0.123
< 0.001
I (isometric)
cov1
0.690
[0.540, 0.870]
< 0.001
0.448
0.202
< 0.001
K (tension)
cov2
0.620
[0.400, 0.820]
< 0.001
0.403
0.247
< 0.001
S (shape)
cov2
0.840
[0.670, 1.000]
< 0.001
0.546
0.104
< 0.001
I (isometric)
cov2
0.670
[0.480, 0.830]
< 0.001
0.436
0.214
< 0.001
K (tension)
cov3
0.630
[0.460, 0.790]
< 0.001
0.410
0.240
< 0.001
S (shape)
cov3
0.810
[0.590, 0.990]
< 0.001
0.527
0.123
< 0.001
I (isometric)
cov3
0.670
[0.460, 0.880]
< 0.001
0.436
0.214
< 0.001
p (FDR): Benjamini-Hochberg false discovery rate correction applied.