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:
Phase your VCF — phased genotypes are required (e.g. from GnoMix or a reference panel).
Convert VCF → PED/MAP — iLASH takes PLINK text-format (
.ped/.map) input, not VCF or BGEN. Usevcf2ped_zc.pyto preserve phase information.Add genetic map coordinates — iLASH needs cM positions. Use
add_gen_map.pyto 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 |
|---|---|
|
Paths to the genetic-map-annotated MAP file and phased PED file. |
|
Path for the output |
|
Set |
|
Window size and step in number of SNPs. |
|
Minimum IBD segment length (cM) and slice length (cM). |
|
LSH parameters controlling sensitivity vs. speed.
Increasing |
|
Candidate and final match score thresholds written to the output file.
Set permissively here (e.g. |
|
Minimum number of MinHash collisions to consider a pair. Lower values increase sensitivity but also false-positive rate. |
|
Number of CPU threads. Match to your SLURM |
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 |
|
Sample identifier for individual 1 |
2 |
|
Haplotype identifier: |
3 |
|
Sample identifier for individual 2 |
4 |
|
Haplotype identifier: |
5 |
|
Chromosome (e.g. |
6 |
|
Start position of the IBD segment (bp, same build as input) |
7 |
|
End position of the IBD segment (bp) |
8 |
|
Variant ID at the start of the segment |
9 |
|
Variant ID at the end of the segment |
10 |
|
Segment length in centiMorgans |
11 |
|
iLASH match score in [0, 1]. The default IBD calling threshold in iLASH
is ≥ 0.99, but lower values are retained when |
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.