Computing IBD Neighbors with iLASH

Step 7 of GRiD (haplotype inference) can use identity-by-descent (IBD) haplotype neighbors computed by iLASH, a scalable local alignment-based IBD detection tool. IBD segments represent true identity-by-descent rather than identity-by-state, making them more specific haplotype neighbors for phasing — particularly for individuals who lack long IBS matches.

For IBS-based neighbors using computeIBSpbwt, see Computing IBS Neighbors.

Note

iLASH is not included in the GRiD repository and must be available on your PATH (e.g. via module load ilash on supported HPC clusters).


Overview

The iLASH workflow for GRiD requires three stages before running iLASH itself:

  1. Phase your VCF — phased genotypes are required (e.g. from GnoMix or a reference panel).

  2. Convert VCF → PED/MAP — iLASH takes PLINK text-format (.ped/.map) input, not VCF or BGEN. Use vcf2ped_zc.py to preserve phase information.

  3. Add genetic map coordinates — iLASH needs cM positions. Use add_gen_map.py to annotate the MAP file with a genetic map.


Input Requirements

Phased VCF — iLASH requires phased genotypes. If your VCF is unphased, phase it first with a tool such as GnoMix, Eagle, or SHAPEIT. The phased VCF must be indexed and cover the chromosome of interest.

Genetic map — a tab-separated file with physical and cM positions for the target chromosome. Download pre-built hg38 maps:

wget https://alkesgroup.broadinstitute.org/Eagle/downloads/tables/genetic_map_hg38.tar.gz
tar -xzf genetic_map_hg38.tar.gz

Stage 1 — Convert VCF to PED/MAP

iLASH reads PLINK text format (.ped/.map). The vcf2ped_zc.py helper converts a phased VCF while preserving haplotype phase. It lives in grid/utils/helper_dir/:

# Count variants in the VCF
SNP_COUNT=$(bcftools view -H phased_chr6.vcf.gz | wc -l)

python grid/utils/helper_dir/vcf2ped_zc.py \
    --vcf       phased_chr6.vcf.gz \
    --out       gnomix_phased_chr6 \
    --snp-count $SNP_COUNT

This produces gnomix_phased_chr6.ped and gnomix_phased_chr6.map.

Note

Use vcf2ped_zc.py rather than standard PLINK conversion tools — standard converters do not guarantee phase order is preserved in the PED file, which is required for iLASH to assign haplotypes correctly.


Stage 2 — Add Genetic Map Coordinates

iLASH uses cM positions from the MAP file to compute segment lengths. Annotate the MAP file produced in Stage 1 using add_gen_map.py from grid/utils/helper_dir/:

python grid/utils/helper_dir/add_gen_map.py \
    --map         gnomix_phased_chr6.map \
    --genetic-map genetic_map_hg38_chr6.txt.gz \
    --out         gnomix_phased_chr6_mapped

This produces gnomix_phased_chr6_mapped.map with cM coordinates filled in.


Stage 3 — iLASH Configuration File

iLASH is configured via a plain-text parameter file. Key parameters for GRiD use:

# iLASH parameter file for LPA KIV-2 (chr6)
map  /path/to/gnomix_phased_chr6_mapped.map
ped  /path/to/gnomix_phased_chr6.ped
output /path/to/output.match

# SNP-based slicing
auto_slice 1
slice_size 350
step_size 350
min_length 0.5
slice_length 0.5
cm_overlap 1

# LSH parameters
shingle_size 15
shingle_overlap 0
perm_count 50
bucket_count 10
interest_threshold 0.50
match_threshold 0.70
minhash_threshold 55

# Threading
max_thread 3

Parameter

Description

map / ped

Paths to the genetic-map-annotated MAP file and phased PED file.

output

Path for the output .match file.

auto_slice

Set 1 to use SNP-count-based window slicing (recommended).

slice_size / step_size

Window size and step in number of SNPs.

min_length / slice_length

Minimum IBD segment length (cM) and slice length (cM).

shingle_size / perm_count / bucket_count

LSH parameters controlling sensitivity vs. speed. Increasing perm_count improves recall at the cost of runtime.

interest_threshold / match_threshold

Candidate and final match score thresholds written to the output file. Set permissively here (e.g. 0.70) and let GRiD filter at load time.

minhash_threshold

Minimum number of MinHash collisions to consider a pair. Lower values increase sensitivity but also false-positive rate.

max_thread

Number of CPU threads. Match to your SLURM --cpus-per-task.

Tip

Run iLASH with a permissive match_threshold (e.g. 0.70) and let GRiD filter at load time via min_match and match_at_min_length. This avoids re-running iLASH when experimenting with different quality thresholds during phasing.


Running iLASH

Once the config file is written, run iLASH:

ilash /path/to/config

Full SLURM submission script:

#!/bin/bash
#SBATCH --job-name=ilash
#SBATCH --output=slurm/%x.out
#SBATCH --error=slurm/%x.err
#SBATCH --time=4:00:00
#SBATCH --mem=300G
#SBATCH --cpus-per-task=3

set -euo pipefail

module load bcftools ilash anaconda
conda activate gnomix

OUTDIR="path/to/output"
STUDY="my_cohort"
SCRIPTS="path/to/grid/scripts"

mkdir -p "$OUTDIR/$STUDY/data"

# Decompress phased VCF if needed
PHASED_VCF="$OUTDIR/$STUDY/data/gnomix_output/query_file_phased.vcf.gz"
gunzip -c "$PHASED_VCF" > "${PHASED_VCF%.gz}"
PHASED_VCF="${PHASED_VCF%.gz}"

SNP_COUNT=$(bcftools view -H "$PHASED_VCF" | wc -l)

# Stage 1: VCF → PED/MAP
python "$SCRIPTS/grid/utils/helper_dir/vcf2ped_zc.py" \
    --vcf "$PHASED_VCF" \
    --out "$OUTDIR/$STUDY/data/gnomix_phased_${STUDY}" \
    --snp-count "$SNP_COUNT"

# Stage 2: add genetic map coordinates
python "$SCRIPTS/grid/utils/helper_dir/add_gen_map.py" \
    --map         "$OUTDIR/$STUDY/data/gnomix_phased_${STUDY}.map" \
    --genetic-map "$SCRIPTS/files/genetic_map_hg38_chr6.txt.gz" \
    --out         "$OUTDIR/$STUDY/data/gnomix_phased_${STUDY}_mapped"

# Stage 3: write iLASH config and run
cat > "$OUTDIR/$STUDY/config" << EOT
map    $OUTDIR/$STUDY/data/gnomix_phased_${STUDY}_mapped.map
ped    $OUTDIR/$STUDY/data/gnomix_phased_${STUDY}.ped
output $OUTDIR/$STUDY/data/output.match
auto_slice 1
slice_size 350
step_size 350
min_length 0.5
slice_length 0.5
cm_overlap 1
shingle_size 15
shingle_overlap 0
perm_count 50
bucket_count 10
interest_threshold 0.50
match_threshold 0.70
minhash_threshold 55
max_thread $SLURM_CPUS_PER_TASK
EOT

ilash "$OUTDIR/$STUDY/config"

# Clean up intermediate files
rm "$OUTDIR/$STUDY/data/gnomix_phased_${STUDY}.map" \
   "$OUTDIR/$STUDY/data/gnomix_phased_${STUDY}.ped" \
   "$OUTDIR/$STUDY/data/gnomix_phased_${STUDY}_mapped.map"

Note

Memory usage scales with cohort size and chromosome length. For a 2,500-sample cohort on chr6, expect 200–300 GB RAM and 2–4 hours at 3 threads.


Output Format

iLASH writes a tab-separated .match file with one IBD segment per row and no header line:

NA19919  NA19919_1  NA21144  NA21144_1  chr6  166290821  166437824  6:166290821:C:A  6:166437824:T:C  0.541199  0.926214
HG03563  HG03563_0  NA21144  NA21144_0  chr6  160157539  160706689  6:160157539:G:T  6:160706689:T:C  0.515263  0.798077

Col

Name

Description

1

ID1

Sample identifier for individual 1

2

HAP_ID1

Haplotype identifier: {ID1}_{hap} where hap is 0 or 1 (0-indexed)

3

ID2

Sample identifier for individual 2

4

HAP_ID2

Haplotype identifier: {ID2}_{hap} where hap is 0 or 1 (0-indexed)

5

chrom

Chromosome (e.g. chr6)

6

bp_start

Start position of the IBD segment (bp, same build as input)

7

bp_end

End position of the IBD segment (bp)

8

snp_start

Variant ID at the start of the segment

9

snp_end

Variant ID at the end of the segment

10

length_cM

Segment length in centiMorgans

11

match_score

iLASH match score in [0, 1]. The default IBD calling threshold in iLASH is ≥ 0.99, but lower values are retained when match_threshold / interest_threshold are relaxed.

Note

iLASH haplotype indices are 0-indexed (_0 and _1), whereas computeIBSpbwt uses 1-indexed haplotypes (hap=1 or hap=2). GRiD’s hi_inference handles both formats automatically.


Passing the Output to GRiD

Point to the .match file in your config under ibd_output:

compute_haploid_genotypes:
  run: True
  output_file_prefix: "haploid_genotypes"
  method: "ibd"
  phasing_method: "graph_prop"
  ibd_output: "path/to/output.match"
  alpha: 0.7
  n_iters: 20
  max_neighbors: 20
  min_length: 2.0
  min_match: 0.95

The top-level start_bp and end_bp config keys (the VNTR coordinates) are used to assign IBD segments to Tier-1 (overlapping the VNTR) or Tier-2 (elsewhere on the chromosome) priority buckets when loading neighbors. See Two-Tier Neighbor Priority for details on the two-tier system and Length-Adaptive Match Threshold for the length-adaptive match threshold.

For a full description of all IBD-related config parameters and phasing algorithms, see Haplotype Inference.