Profile-likelihood heritability estimation for family cohort studies β no SOLAR required.
β οΈ R-itable is in early development. The API may change without notice, and the package has not undergone peer review.
herit_ace()/herit_bivar()/herit_bivar_batch()have been validated against real SOLAR Eclipse output (28 of 31 real-cohort trait pairs match to 4 decimal places -- seeNEWS.mdfor methodology and the two known exceptions);herit_vc()/herit_batch()have not yet undergone the same formal comparison. Verify outputs independently before using in any research context.
R-itable (library(Ritable)) estimates narrow-sense heritability (hΒ²) for
quantitative traits in pedigree-based family cohort studies. It implements a
profile-likelihood variance-components approach equivalent to SOLAR Eclipse β
without any proprietary dependencies, compiled code, or external binaries.
Built for neuroimaging and biomedical cohorts where you need to run heritability over dozens of traits across multiple covariate models and get results you can trace back to first principles.
build_grm(mz_col = ...) gives monozygotic pairs (or
larger groups) the correct kinship of 1.0, instead of the ordinary
full-sibling 0.5.herit_ace() fits nested
sporadic/AE/CE/ACE models and tests whether A and C are jointly
identifiable in your sample, with optional SOLAR--screen-style
automatic covariate screening (covs = ...).herit_bivar() /
herit_bivar_batch() estimate rhoG, rhoE, and derived rhoP between trait
pairs, with LRTs and Benjamini-Hochberg FDR correction across a batch.uniroot().int_transform() for use in other pipelines.herit_batch() iterates over traits Γ covariate models
and returns a tidy data frame, ready for tables and figures.plot_forest() for immediate visualisation of batch
output (requires ggplot2).kinship2,
rlang, and cli.Install from r-universe (recommended β pre-built binaries):
install.packages(
"Ritable",
repos = c("https://circadia-bio.r-universe.dev", "https://cloud.r-project.org")
)
Or install the development version from GitHub:
install.packages("pak")
pak::pak("circadia-bio/R-itable")
library(Ritable)
# 1. Build GRM from pedigree
A <- build_grm(my_pedigree, study_ids = my_data$IID)
# 2. Single trait
herit_vc("bmi", grm = A, data = my_data, covs = c("age", "sex"))
# 3. Many traits x models -> tidy data frame with columns:
# label, trait, covariates, n, h2, se, ci_lo, ci_hi, pval,
# var_covariates, sigma2_a, sigma2_e
res <- herit_batch(
traits = c("bmi", "hdl", "systolic_bp"),
grm = A,
data = my_data,
covs_list = list(
unadj = NULL,
cov1 = c("age", "sex"),
cov2 = c("age", "sex", "age2")
)
)
# 4. Forest plot
plot_forest(res, model_filter = "cov2")
# GRM with MZ-twin relatedness override (mztwin_col groups MZ pairs/triplets)
A <- build_grm(twin_pedigree, study_ids = twin_data$IID, mz_col = "mztwin")
C <- build_household(twin_pedigree$hhid, twin_pedigree$id)
# A vs C identifiability: sporadic / AE / CE / full ACE
herit_ace("anxiety_score", grm = A, household = C, data = twin_data, id_col = "IID")
# ...with automatic covariate screening (SOLAR's polygenic -screen algorithm:
# single-pass LRT test of each candidate, drop if p >= prob_level)
twin_data$age_sex <- twin_data$age * twin_data$sex
res <- herit_ace("anxiety_score", grm = A, household = C, data = twin_data,
covs = c("age", "sex", "age_sex"), id_col = "IID")
res$covs_kept # covariates that survived screening
res$covariate_lrt_p # each candidate's individual LRT p-value
# Bivariate genetic/environmental correlation between two traits
herit_bivar("anxiety_score", "depression_score", grm = A, data = twin_data, id_col = "IID")
# Many trait pairs at once, with BH-FDR correction per correlation type
pairs <- data.frame(
trait1 = c("anxiety_score", "depression_score"),
trait2 = c("sleep_quality", "sleep_quality")
)
herit_bivar_batch(pairs, grm = A, data = twin_data, id_col = "IID")
For a full walkthrough see vignette("getting-started", package = "Ritable"), and
vignette("twin-cohorts", package = "Ritable") for the workflow above in more detail.
R-itable/
βββ R/
β βββ Ritable-package.R # package-level docs and colour palette
β βββ build_grm.R # build additive GRM from pedigree (incl. MZ twins)
β βββ build_household.R # build household/shared-environment matrix
β βββ int_transform.R # rank-based inverse-normal transform
β βββ herit_vc.R # single-trait VC estimator
β βββ herit_batch.R # batch wrapper
β βββ herit_ace.R # A vs C identifiability (sporadic/AE/CE/ACE)
β βββ herit_bivar.R # bivariate genetic/environmental correlation
β βββ vc_utils.R # internal general-ML helpers (ACE, bivariate)
β βββ plot_forest.R # ggplot2 forest plot
βββ man/figures/
β βββ logo.svg
βββ tests/testthat/
β βββ helper-fixtures.R # shared synthetic pedigree/twin/data fixtures
β βββ test-build_grm.R
β βββ test-build_household.R
β βββ test-int_transform.R
β βββ test-herit_vc.R
β βββ test-herit_batch.R
β βββ test-herit_ace.R
β βββ test-herit_bivar.R
βββ vignettes/
β βββ getting-started.Rmd
β βββ twin-cohorts.Rmd # MZ relatedness, household effects, bivariate correlation
βββ data-raw/
β βββ prepare_data.R
βββ DESCRIPTION
βββ NEWS.md
βββ R-itable.Rproj
| Package | Type | Purpose |
|---|---|---|
| kinship2 | Imports | Pedigree object and kinship matrix |
| rlang | Imports | Error/warning handling |
| cli | Imports | Progress bars and formatted messages |
| stats, utils | Imports | Base statistical/utility functions |
| ggplot2 | Suggests |
plot_forest() β checked at runtime, not required for non-plotting functions |
| scales | Suggests | Axis formatting in plot_forest()
|
| testthat, covr | Suggests | Test suite and coverage |
| knitr, rmarkdown, pkgdown | Suggests | Vignettes and documentation site |
| Role | Name | Affiliation |
|---|---|---|
| Author, maintainer | Lucas FranΓ§a | Northumbria University, Circadia Lab |
| Author | Mario Leocadio-Miguel | Northumbria University, Circadia Lab |
If you use R-itable in your research, please cite it:
@software{franca_ritable_2026,
author = {FranΓ§a, Lucas and Leocadio-Miguel, Mario},
title = {{R-itable}: Pedigree-Based Heritability Estimation for Family Cohort Studies},
year = {2026},
version = {0.2.1},
url = {https://github.com/circadia-bio/R-itable}
}
Released under the MIT License.
Copyright Β© Circadia Lab, 2026