Computing IBS Neighbors¶
Step 7 of GRiD (haplotype inference) can use identity-by-state (IBS) haplotype
neighbors as input. These are produced by computeIBSpbwt.cpp, a C++ program
from Hujoel et al. (2026) that identifies the closest haplotype matches for each
individual using the Positional Burrows-Wheeler Transform (PBWT).
This page covers how to obtain the source, compile it, prepare the required inputs,
and run it to generate the IBS neighbors file used by hi_inference.
For IBD-based neighbors using iLASH, see Computing IBD Neighbors with iLASH.
Note
computeIBSpbwt.cpp is not included in the GRiD repository. It is part of the
supplementary code released with Hujoel et al. (2026) Nature
(doi:10.1038/s41586-025-09886-z).
The source is available directly at:
mhujoel/STRs — computeIBSpbwt.cpp.
Dependencies¶
computeIBSpbwt.cpp depends on:
Eagle v2.4.1 header files — specifically
Types.hpp,FileUtils.cpp,StringUtils.cpp,MemoryUtils.cpp,Timer.cpp, andMapInterpolater.cpp. Download Eagle from:wget https://alkesgroup.broadinstitute.org/Eagle/downloads/Eagle_v2.4.1.tar.gz tar -xzf Eagle_v2.4.1.tar.gz # headers are in Eagle_v2.4.1/src/
Boost iostreams (≥ 1.58.0):
# via conda conda install -c conda-forge boost # or download manually wget https://archives.boost.org/release/1.58.0/source/boost_1_58_0.tar.gz
zlib — usually available on HPC systems; install if missing:
conda install -c conda-forge zlib
OpenMP — included with GCC; no separate install needed.
Compilation¶
Replace /path/to/Eagle/src, /path/to/boost/include, and
/path/to/boost/lib with your actual paths.
Standard build:
g++ -O2 -fopenmp -Wall computeIBSpbwt.cpp -o computeIBSpbwt \
-I/path/to/Eagle_v2.4.1/src \
-I/path/to/boost/include \
-L/path/to/boost/lib \
-Wl,-Bstatic -lboost_iostreams -Wl,-Bdynamic -lz
Static build (recommended for HPC clusters):
g++ -O2 -fopenmp -Wall -static-libgcc -static-libstdc++ computeIBSpbwt.cpp -o computeIBSpbwt \
-I/path/to/Eagle_v2.4.1/src \
-I/path/to/boost/include \
-L/path/to/boost/lib \
-Wl,-Bstatic -lboost_iostreams -lz
Verify the build:
./computeIBSpbwt
# should print: Usage: - arg1 = chr (integer) ...
Required Input Files¶
The program takes 8 arguments in order:
Arg |
Name |
Description |
|---|---|---|
1 |
|
Chromosome number as integer (e.g. |
2 |
|
Focal base pair position in the same genome build as the BGEN file.
For LPA KIV-2 in hg38, use the center of the VNTR region
(\(\sim\) |
3 |
|
Phased genotype data in BGEN v1.2 format (layout 2, compressed, phased). See below. |
4 |
|
Oxford-format sample file corresponding to the BGEN file. See below. |
5 |
|
Genetic map in cM units, in the same genome build as the BGEN file. See below. |
6 |
|
Number of IBS neighbors to find per haplotype. Recommended: |
7 |
|
Number of CPU threads for parallel computation. |
8 |
|
Output file path. Use a |
Phased BGEN File¶
The BGEN file must contain phased SNP-array or WGS genotypes for the chromosome of interest. Requirements:
BGEN v1.2, layout 2, compressed (
CompressedSNPBlocks=1)Phased (
Phased=1)16-bit probability encoding (
bgenBits=16)Biallelic variants only (
K=2)
Sample File¶
Oxford-format .sample file with two header lines followed by one row per individual:
ID_1 ID_2 missing
0 0 0
SAMPLE001 SAMPLE001 0
SAMPLE002 SAMPLE002 0
...
The program uses column ID_1 as the sample identifier. The identifier must match
the IDs in the diploid CN file passed to hi_inference.
Genetic Map File¶
A tab-separated file with columns: position, COMBINED_rate, Genetic_Map(cM).
Download pre-built maps from Eagle’s website:
wget https://alkesgroup.broadinstitute.org/Eagle/downloads/tables/genetic_map_hg19.tar.gz
# or for hg38:
wget https://alkesgroup.broadinstitute.org/Eagle/downloads/tables/genetic_map_hg38.tar.gz
Running the Program¶
Example command for LPA KIV-2 (hg38, chr6):
./computeIBSpbwt \
6 \
160626000 \
phased_chr6.bgen \
phased_chr6.sample \
genetic_map_chr6_hg38.txt \
200 \
16 \
ibs_neighbors_chr6.tsv.gz
On a SLURM cluster:
#!/bin/bash
#SBATCH --job-name=computeIBS
#SBATCH --cpus-per-task=16
#SBATCH --mem=64G
#SBATCH --time=4:00:00
./computeIBSpbwt 6 160626000 \
phased_chr6.bgen phased_chr6.sample \
genetic_map_chr6_hg38.txt \
200 16 \
ibs_neighbors_chr6.tsv.gz
Output Format¶
The output is a tab-separated file with one row per haplotype-neighbor pair:
ID hap nbrInd cMlen cMedge IDnbr hapNbr
10001 1 1 8.45 4.22 20034 2
10001 1 2 7.13 3.56 30017 1
10001 2 1 9.01 5.10 20034 1
...
Column |
Description |
|---|---|
|
Sample identifier |
|
Haplotype index (1 or 2, 1-indexed) |
|
Neighbor rank (1 = closest) |
|
Total IBS match length in cM (weighted combination of left and right extents) |
|
Minimum of left and right IBS match edge lengths in cM |
|
Neighbor sample identifier |
|
Neighbor haplotype index (1 or 2, 1-indexed) |
Passing the Output to GRiD¶
Once the neighbors file is generated, point to it in your config:
compute_haploid_genotypes:
run: True
output_file_prefix: "haploid_genotypes"
method: "ibs"
phasing_method: "iterative"
ibs_output: "path/to/ibs_neighbors_chr6.tsv.gz"
min_neighbors: 1
max_neighbors: 10
n_iters: 20
See Haplotype Inference for full details on phasing algorithms and all available configuration options.