Skip to contents

🧪 R-itable

Profile-likelihood heritability estimation for family cohort studies — no SOLAR required.

R License: MIT Lifecycle: experimental

📖 What is R-itable?

R-itable (library(itable)) 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

  • 🔬 Profile-likelihood VC estimator — eigendecomposition of the GRM, 1-D optimisation, exact LRT with one-sided χ²(1) boundary correction (matching SOLAR).
  • 📐 Profile-likelihood CIs — not Wald ±1.96 SE; proper asymmetric intervals via uniroot().
  • 🔄 INT transformation — inverse-normal transform applied internally; also exported as int_transform() for use in other pipelines.
  • 📦 Batch mode — herit_batch() iterates over traits × covariate models and returns a tidy data frame, ready for tables and figures.
  • 🌲 Forest plots — plot_forest() for immediate visualisation of batch output (requires ggplot2).
  • 🧩 Minimal dependencies — core functions require only base R, kinship2, rlang, and cli.

🗂️ Project Structure 

R-itable/
├── R/
│   ├── itable-package.R       # package-level docs
│   ├── build_grm.R            # build additive GRM from pedigree
│   ├── int_transform.R        # rank-based inverse-normal transform
│   ├── herit_vc.R             # single-trait VC estimator
│   ├── herit_batch.R          # batch wrapper
│   └── plot_forest.R          # ggplot2 forest plot
├── tests/testthat/
│   ├── helper-fixtures.R      # shared synthetic pedigree/data
│   ├── test-build_grm.R
│   ├── test-int_transform.R
│   ├── test-herit_vc.R
│   └── test-herit_batch.R
├── vignettes/
│   └── getting-started.Rmd
├── data-raw/
│   └── prepare_data.R
├── DESCRIPTION
├── NAMESPACE
└── NEWS.md

🚀 Getting Started

Prerequisites 

install.packages(c("kinship2", "rlang", "cli"))

# For plotting:
install.packages("ggplot2")

Installation 

# From GitHub (recommended while pre-CRAN)
remotes::install_github("circadia-bio/R-itable")

Basic usage 

library(itable)

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

For a full walkthrough see vignette("getting-started", package = "itable").

📦 Dependencies

Package Role
kinship2 Pedigree object and kinship matrix
rlang Error/warning handling, tidy eval
cli Progress bars and formatted messages
ggplot2 (Suggests) plot_forest()

👥 Authors

Role Name Affiliation
Author & maintainer Lucas Veras Northumbria University / Circadia Lab

📄 Licence

Released under the MIT License.

Copyright © Circadia Lab, 2026