gnomAD Local Ancestry Inference (LAI) Pipeline

This repository provides a streamlined pipeline for performing Local Ancestry Inference (LAI) using gnomAD samples. Due to the large scale of gnomAD, we implemented this pipeline using the Hail Batch Python module which is still in beta testing and exclusive to the Broad however the tools used within the pipeline are all publicly available.

The pipeline leverages Eagle for phasing, RFMix v2 for ancestry painting, Tractor for extracting ancestry-specific allele frequencies, and generate_output_vcf.py for generating a joint VCF with ancestry-specific allele count (AC), allele number (AN), and allele frequency (AF) annotations. Below, we outline the steps to run this pipeline on your dataset using Hail/Python scripts.

---

Getting Started

To run the LAI pipeline, set up your environment and install the required dependencies. Follow the step-by-step instructions below.

---

1. Pipeline Overview

This pipeline processes genomic data by:

• Phasing haplotypes using Eagle
• Inferring local ancestry using RFMix v2
• Extracting ancestry-specific allele frequencies from phased and painted data using Tractor
• Generating a joint VCF with ancestry-specific calls using generate_output_vcf.py

---

2. Installation & Setup

Step 1: Clone the Repository

git clone https://github.com/broadinstitute/gnomad_local_ancestry.git

Step 2: Install Dependencies

The pipeline requires Python 3, Hail, and several additional tools. Install the necessary dependencies using:

pip install hail
pip install numpy pandas

Make sure you have Eagle and RFMix v2 installed. You can find installation instructions and a toy dataset in the Tractor Tutorial.

---

3. Running the LAI Pipeline

Step 1: Phasing

To phase your genotype data using Eagle, run:

eagle --vcf input_data.vcf.gz --out phased_data.vcf.gz

Refer to the Tractor wiki for a detailed guide on phasing.

Step 2: Local Ancestry Inference using RFMix

After phasing, run RFMix v2 to infer local ancestry:

rfmix \
  -f phased_data.vcf.gz \
  -r reference_panel.vcf.gz \
  -m samplemap.txt \
  -g geneticmap.txt \
  -o painted_lai \
  --chromosome=22

See the Tractor wiki for additional instructions on reference panels and sample maps.

Step 3: Extracting Ancestry-Specific Allele Frequencies

Once local ancestry inference is complete, extract ancestry-specific allele frequencies using Tractor:

python3 extract_tracts.py \
  --vcf phased_data.vcf.gz \
  --msp painted_lai.msp.tsv \
  --num-ancs 2

Step 4: Generating a Joint VCF with Ancestry-Specific Annotations

The generate_lai_vcf function calls generate_output_vcf.py, a standalone Python/Hail script. This script outputs an annotated VCF containing ancestry-specific allele frequency data:

python3 generate_output_vcf.py \
  --msp-file painted_lai.msp.tsv \
  --tractor-output tractor_output_path \
  --output-path output_lai \
  --is-zipped \
  --mt-path-for-adj pipeline_input.mt \
  --add-gnomad-af

---

4. Additional Resources

For detailed explanations of phasing, local ancestry painting, and extracting tracts, refer to:

• Tractor Tutorial

For our Hail Batch Python pipeline, refer to:

• gnomAD Local Ancestry Pipeline

---

5. Citation

If you use this pipeline in your research, please cite:

Kore, P., Wilson, M.W., Tiao, G. et al. Improved allele frequencies in gnomAD through local ancestry inference. Nat Commun 16, 8734 (2025). https://doi.org/10.1038/s41467-025-63340-2.

Please direct questions to pragati.kore@bcm.edu or mwilson@broadinstitute.org.