🧬 R-itable

Profile-likelihood heritability estimation for family cohort studies β€” no SOLAR required.

r-universe License: MIT R R CMD CHECK Coverage Status pkgdown


⚠️ 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 -- see NEWS.md for 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.


πŸ“– What is R-itable?

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.


✨ Features


πŸš€ Getting Started

Installation

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

Basic usage

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

Twin cohorts: MZ relatedness, household effects, bivariate correlations

# 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.


πŸ—‚οΈ Project Structure

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

πŸ“¦ Dependencies

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

πŸ‘₯ Authors

Role Name Affiliation
Author, maintainer Lucas FranΓ§a Northumbria University, Circadia Lab
Author Mario Leocadio-Miguel Northumbria University, Circadia Lab

πŸ“„ Citation

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}
}

🀝 Related Tools


πŸ“„ Licence

Released under the MIT License.

Copyright Β© Circadia Lab, 2026