Stratified heritability enrichment analysis

Overview

HDL.S is an R package for studying how SNP heritability is distributed across genomic annotations. It implements stratified high-definition likelihood (HDL-S), a likelihood-based framework for estimating the heritability enrichment of binary or continuous annotations from GWAS summary statistics.

HDL-S builds on the high-definition likelihood framework in HDL and extends it to functional enrichment analysis. Compared with stratified LD score regression (sLDSC), HDL-S provides 1.4- to 7.4-fold higher efficiency for estimating heritability enrichment parameters in the settings evaluated by Lan and Shen.

The HDL.S source is included in the HDL repository under HDL.S/.

Installation

Install HDL and HDL.S directly from the unified HDL repository:

# install.packages("remotes")
remotes::install_github("zhenin/HDL", subdir = "HDL")
remotes::install_github("zhenin/HDL", subdir = "HDL.S")

To update either package, rerun the corresponding command with force = TRUE.

Required data

An HDL-S analysis requires:

1. GWAS summary statistics in a data frame with the following columns:

   • SNP: SNP ID (typically an rsID)
   • A1: effect allele
   • A2: reference allele
   • N: sample size
   • Z: GWAS Z-score

   If Z is unavailable, b (effect estimate) and se (standard error) may be supplied instead.

2. A genomic annotation matrix (D) with one annotation column. Row names must be SNP IDs, and the column name is used as the annotation name in the output. Both binary and continuous annotation weights are supported. SNPs absent from D are assigned a weight of zero when the annotation is aligned to the LD reference panel.

3. An HDL-compatible LD reference panel containing the eigenvalues and eigenvectors of the LD matrices. Precomputed European-ancestry panels and instructions for building a custom panel are available on the Reference panels and Build a reference panel pages.

Quick example

The following example uses the birth-weight GWAS data distributed with HDL and a random binary annotation for demonstration.

1. Download an LD reference panel

This example uses the UK Biobank Axiom Array panel (307,519 SNPs):

wget -c -t 1 \
  'https://www.dropbox.com/s/fuvpwsf6r8tjd6c/UKB_array_SVD_eigen90_extraction.tar.gz?dl=0' \
  -O /path/to/UKB_array_SVD_eigen90_extraction.tar.gz

# Expected MD5: ff3fadd7ea08bd29759b6c652618cd1f
md5sum /path/to/UKB_array_SVD_eigen90_extraction.tar.gz

tar -xvf /path/to/UKB_array_SVD_eigen90_extraction.tar.gz \
  -C /path/to/reference-panels

2. Run HDL-S

library(HDL.S)

# Birth-weight GWAS summary statistics distributed with HDL.
data(gwas1.example, package = "HDL")

# Create a single random binary annotation for demonstration.
M <- nrow(gwas1.example)
set.seed(1234)
D <- matrix(
  rbinom(M, size = 1, prob = 0.01),
  ncol = 1,
  dimnames = list(gwas1.example$SNP, "random_annotation")
)

LD.path <- "/path/to/reference-panels/UKB_array_SVD_eigen90_extraction"

# A large lam.cut is used here only to make this demonstration faster.
res.HDL.S <- HDL.S::HDL.S(
  D = D,
  gwas.df = gwas1.example,
  LD.path = LD.path,
  mc.cores = 4,
  stepwise = TRUE,
  lam.cut = 10,
  Dr.path = NULL,
  mode = "memory"
)

print(as.data.frame(res.HDL.S))

For an analysis intended for publication, choose lam.cut according to the size of the analysis and the desired accuracy. A lower cutoff such as 0.1, or no cutoff, is recommended for a small number of traits and annotations; a larger cutoff such as 1 can accelerate large-scale analyses.

Main results

HDL.S() returns a data frame containing estimates, standard errors, p-values, and notes. The principal rows are:

Item	Interpretation
h2	Total SNP heritability
intercept	Model intercept
eta	Annotation-independent model parameter
fold.<annotation>	Heritability enrichment fold for the annotation
converged	Whether numerical optimization converged
message	Optimizer status message

For fold.<annotation>, the reported p-value tests whether the enrichment fold differs from 1; it is not a one-sided test of enrichment greater than 1.

Important considerations

• Use an LD reference panel that matches the ancestry and SNP coverage of the GWAS. Substantial LD mismatch or missingness can bias the estimates.
• HDL-S automatically aligns annotation SNP IDs to the LD reference panel and assigns zero weight to missing annotation SNPs.
• For continuous annotations, select a suitable norm.method: "minmax" (default), "scaled", or "none".
• Enrichment-fold estimates from annotations whose weights are on different scales should not be compared directly. In that setting, comparison of statistical evidence may be more appropriate.
• mc.cores controls parallel processing across LD blocks, while nthreads controls threads used for matrix operations. Avoid allocating more total threads than are available.

Additional tutorials

The package includes tutorials covering:

• a complete HDL-S example;
• binary and continuous genomic annotations;
• large-scale analyses across many traits;
• rebuilding an LD reference panel when GWAS SNP coverage is incomplete.

See the HDL-S documentation site and the source files under HDL.S/vignettes/.

Citation

If you use HDL-S, please cite:

Lan A. and Shen X. Modeling the genetic architecture of complex traits via stratified high-definition likelihood. Nature Communications (2026).

Please also cite the original HDL method:

Ning, Z., Pawitan, Y. & Shen, X. High-definition likelihood inference of genetic correlations across human complex traits. Nature Genetics (2020).

Help and reporting issues

Please report software bugs through the HDL issue tracker. For questions about HDL-S, contact Ao Lan or Xia Shen.