Package 'Ritable'

Build an additive genetic relationship matrix from a pedigree

Description

Constructs the additive genetic relationship matrix A (= 2 x kinship matrix) for a set of study subjects, using a pedigree that may include additional founder parents not in the study sample.

Usage

build_grm(
  ped_df,
  study_ids = NULL,
  id_col = "id",
  pat_col = "pat",
  mom_col = "mom",
  sex_col = "sex"
)

Arguments

ped_df	A data frame with at least the columns id, pat, mom, and sex. Missing parents should be NA or 0. sex should be numeric: 1 = male, 2 = female (any other value is recoded to 1 with a warning).
study_ids	Character or integer vector of IDs for the study subjects whose sub-matrix should be extracted. Defaults to all IDs in ped_df.
id_col, pat_col, mom_col, sex_col	Column names for the four required pedigree fields. Defaults are "id", "pat", "mom", "sex".

Details

The function calls kinship2::kinship() on the full pedigree (including founders), then multiplies by 2 to obtain the additive relationship matrix, and finally subsets to study_ids. Including founders in the pedigree ensures that kinship coefficients between study subjects connected only through founders are estimated correctly.

Value

A symmetric numeric matrix of dimension ⁠length(study_ids) x length(study_ids)⁠, with diagonal entries equal to 1 for non-inbred individuals and row/column names matching study_ids.

Examples

# Minimal two-generation pedigree: two couples, four offspring
ped <- data.frame(
  id  = 1:8,
  pat = c(0, 0, 0, 0, 1, 1, 3, 3),
  mom = c(0, 0, 0, 0, 2, 2, 4, 4),
  sex = c(1, 2, 1, 2, 1, 2, 1, 2)
)
A <- build_grm(ped, study_ids = 5:8)
round(A, 3)

---

Batch heritability estimation over multiple traits

Description

A convenience wrapper around herit_vc() that iterates over a vector of trait names, optionally across multiple covariate models, and returns a tidy data frame.

Usage

herit_batch(
  traits,
  grm,
  data,
  covs_list = NULL,
  id_col = "IID",
  min_n = 80L,
  ci_level = 0.95,
  .progress = TRUE
)

Arguments

traits	Character vector of trait column names in data.
grm	Numeric matrix: additive genetic relationship matrix as returned by build_grm().
data	Data frame containing ID, trait, and covariate columns.
covs_list	A named list of covariate vectors, where each element defines one covariate model. If NULL, a single unadjusted model is run. Example: list(unadj = NULL, cov1 = c("age", "sex"), cov2 = c("age", "sex", "age2")).
id_col	Name of the individual ID column. Default "IID".
min_n	Minimum sample size to attempt estimation. Default 80.
ci_level	Profile-likelihood CI level. Default 0.95.
.progress	Logical. Show a cli progress bar. Default TRUE.

Value

A data frame (tibble-compatible) with one row per successfully fitted model and columns: label, trait, covariates, n, h2, se, ci_lo, ci_hi, pval, sigma2_a, sigma2_e. Failed / skipped models are silently omitted.

See Also

herit_vc(), build_grm(), plot_forest()

Examples

## Not run: 
A    <- build_grm(my_pedigree, study_ids = my_data$IID)

res  <- herit_batch(
  traits     = c("bmi", "systolic_bp", "hdl"),
  grm        = A,
  data       = my_data,
  covs_list  = list(
    unadj = NULL,
    cov1  = c("age", "sex"),
    cov2  = c("age", "sex", "age2")
  )
)

# Significant adjusted models
subset(res, grepl("cov2", label) & pval < 0.05)

## End(Not run)

---

Profile-likelihood variance-components heritability estimation

Description

Estimates narrow-sense heritability (h²) for a single quantitative trait using a profile-likelihood variance-components approach equivalent to SOLAR Eclipse. The phenotype is inverse-normal transformed internally.

Usage

herit_vc(
  trait,
  grm,
  data,
  covs = NULL,
  id_col = "IID",
  label = NULL,
  min_n = 80L,
  ci_level = 0.95,
  verbose = TRUE
)

Arguments

trait	Character string: name of the trait column in data.
grm	Numeric matrix: the additive genetic relationship matrix for all individuals in data, as returned by build_grm(). Row and column names must match the ID column of data.
data	Data frame containing id_col, trait, and any covariate columns.
covs	Character vector of covariate column names, or NULL for an intercept-only model. Covariates are mean-centred and scaled to unit variance before fitting.
id_col	Name of the individual ID column in data. Default "IID".
label	Optional string label for this model (used in batch output). If NULL, defaults to "<trait>_adj" or "<trait>_unadj".
min_n	Minimum number of complete observations required to attempt estimation. Models with fewer observations return NULL silently. Default 80.
ci_level	Confidence level for the profile-likelihood interval. Default 0.95.
verbose	Logical. Print progress to the console. Default TRUE.

Details

Model: Omega = sigma2_p [h2 A + (1 - h2) I_n]

Optimisation: eigendecomposition of A followed by 1-D profile-likelihood optimisation over h2 in (0, 1) using a coarse grid to seed stats::optimize().

LRT: one-sided chi-squared(1) boundary correction – the null is on the boundary of the parameter space (h2 = 0), so the p-value is halved relative to a standard chi-squared test. This matches the SOLAR Eclipse convention.

CIs: derived by uniroot() on the profile log-likelihood, falling back to a Wald interval if the root-finding fails.

Value

A named list with elements:

label

Model label.

trait

Trait name.

covariates

Covariate names joined by "+", or "".

n

Sample size after dropping missing values.

h2

MLE of narrow-sense heritability.

se

Standard error from profile-likelihood curvature (Wald).

ci_lo, ci_hi

Profile-likelihood confidence interval bounds.

pval

One-sided LRT p-value with chi-squared(1) boundary correction.

var_covariates

Proportion of phenotypic variance explained by fixed-effect covariates (R² on INT-transformed phenotype). NA for unadjusted models. Corresponds to the "variance explained" column in Leocadio-Miguel et al. (2025).

sigma2_a

Additive genetic variance (sigma²_g in SOLAR notation).

sigma2_e

Residual environmental variance (sigma²_e).

Returns NULL if n < min_n or if the GRM subset is degenerate.

See Also

build_grm(), herit_batch(), int_transform()

Examples

## Not run: 
# Build GRM then estimate heritability
A   <- build_grm(my_pedigree, study_ids = my_data$IID)
res <- herit_vc("bmi", grm = A, data = my_data,
                covs = c("age", "sex", "age2"))
str(res)

## End(Not run)

---

Inverse-normal (rank-based) transformation

Description

Applies a rank-based inverse-normal transformation (INT) to a numeric vector, placing empirical quantiles onto a standard normal scale.

Usage

int_transform(x, ties = "average")

Arguments

x	Numeric vector. NAs are preserved.
ties	Method passed to base::rank(). Default "average".

Details

The Blom-style formula used is:

$\Phi^{-1}\!\left(\frac{r_i - 0.5}{n}\right)$

where $r_i$ is the rank of observation $i$ and $n$ is the number of non-missing observations. This is the standard transformation used in SOLAR Eclipse and most variance-components heritability software.

Value

A numeric vector of the same length as x, with NAs in the same positions and non-missing values transformed to approximate normality.

Examples

set.seed(1)
x <- rexp(200, rate = 0.5)   # right-skewed
hist(x,              main = "Raw")
hist(int_transform(x), main = "INT")

---

Forest plot of heritability estimates

Description

Produces a ggplot2 forest plot from the output of herit_batch() or a list of herit_vc() results coerced to a data frame.

Usage

plot_forest(
  results,
  model_filter = NULL,
  colour_by = "trait",
  sig_threshold = 0.05,
  title = NULL,
  x_limits = c(0, 1)
)

Arguments

results	Data frame as returned by herit_batch(), containing at least columns label, trait, h2, ci_lo, ci_hi, pval.
model_filter	Optional character vector of model name substrings to keep (matched against label). E.g. "cov2" to show only the age + sex + age-squared model.
colour_by	Column to colour points by. Default "trait". Set to NULL for a monochrome plot.
sig_threshold	Numeric. Traits with pval below this threshold are shown with a filled point; others with an open point. Default 0.05.
title	Optional plot title string.
x_limits	Numeric vector of length 2 for the x-axis range. Default c(0, 1).

Details

Requires ggplot2 (listed in Suggests). An informative error is thrown if it is not installed.

Value

A ggplot2::ggplot object. Colours follow the Ritable_colours palette by default (pink ⁠#FE9EC7⁠ and blue ⁠#44ACFF⁠ as the primary pair).

See Also

herit_batch(), Ritable_colours

Examples

## Not run: 
res <- herit_batch(c("bmi", "hdl", "systolic_bp"),
                   grm = A, data = my_data,
                   covs_list = list(unadj = NULL,
                                    cov2  = c("age", "sex", "age2")))

plot_forest(res, model_filter = "cov2", title = "Adjusted heritability")

## End(Not run)

---

R-itable colour palette

Description

A named character vector of the four brand colours used throughout R-itable figures and documentation.

Usage

Ritable_colours

Format

An object of class character of length 4.

Details

pink

⁠#FE9EC7⁠ – primary accent; significant traits, sex effect

blue

⁠#44ACFF⁠ – primary brand colour; estimates, CI lines

sky

⁠#89D4FF⁠ – secondary blue; muted elements, CI shading

cream

⁠#F9F6C4⁠ – soft highlight; code backgrounds

Examples

Ritable_colours

---