Haplotype Inference¶
Pipeline step: compute_haploid_genotypes (Step 5)
Module: grid.utils.hi_inference
Diploid copy number estimates from Step 4 (denoted IRR — individual repeat ratio) cannot be decomposed into per-haplotype contributions without phase information. GRiD infers haplotype-specific copy numbers by identifying haplotype-matched neighbors and iteratively (or directly) partitioning each individual’s diploid total between their two haplotypes.
Two neighbor sources are supported via the method config parameter:
IBS (
method: "ibs") — neighbors fromcomputeIBSpbwtPBWT matching output.IBD (
method: "ibd") — neighbors from iLASH IBD segment output.
Five phasing algorithms are available via the phasing_method config parameter,
described in detail below.
For neighbor file formats and how to generate them, see Computing IBS/IBD Neighbors.
Note
This step is locus-agnostic — it operates on diploid copy number estimates and a haplotype neighbors file, with no assumptions about which locus produced those estimates. It was developed and validated on LPA KIV-2, but can be applied to any VNTR locus for which phased neighbor data are available.
Notation¶
For \(N\) individuals, define:
\(\mathrm{IRR}_i\) — diploid copy number estimate for individual \(i\)
\(h_{i,k}^{(t)}\) — haplotype copy number for individual \(i\), haplotype \(k \in \{0, 1\}\), at iteration \(t\)
\(\mathcal{H}_{i,k}\) — set of haplotype neighbors for haplotype \(k\) of individual \(i\), each entry \((j, k', w)\) giving neighbor individual \(j\), neighbor haplotype \(k'\), and weight \(w\)
\(\bar{h}^{(t)}_{i,k}\) — aggregated neighbor signal for haplotype \(k\) of individual \(i\) at iteration \(t\)
The diploid constraint \(h_{i,0} + h_{i,1} = \mathrm{IRR}_i\) is preserved at every iteration for all phasing methods.
Initialization¶
All methods initialize each haplotype to half the diploid estimate:
Only individuals with at least \(\mathrm{MIN\_NBR}\) neighbors on both haplotypes are phased; others receive mean-imputed values (see Mean Imputation for Unphased Samples).
Neighbor Aggregation Functions¶
All iterative methods compute a neighbor aggregate \(\bar{h}^{(t)}_{i,k}\)
from the current haplotype values of neighbors in \(\mathcal{H}_{i,k}\).
The aggregation function is controlled by the agg_fn config parameter:
|
Description |
|---|---|
|
Arithmetic mean of neighbor haplotype values, ignoring weights. |
|
Median of neighbor haplotype values; robust to copy-number outliers. |
|
Weighted mean using segment length (cM) as weight. For IBS neighbors,
all weights are 1 and this reduces to |
|
Weighted mean using iLASH match score as weight. |
|
Weighted mean using the product of segment length and match score as weight. |
|
10 % trimmed mean (trims the top and bottom decile before averaging). |
For IBS neighbors, all segment weights are 1 so mean, weighted_cM,
weighted_score, and weighted_cM_score are all equivalent.
Phasing Algorithms¶
iterative — Original Hujoel Algorithm¶
The default algorithm, ported directly from Hujoel et al. (2026). At each iteration the diploid total is partitioned in proportion to the ratio of each haplotype’s neighbor aggregate:
Config: phasing_method: iterative |
Tunes: agg_fn, n_iters
graph_prop — Graph Propagation (recommended)¶
A label-spreading variant that blends each individual’s own prior signal (diploid/2) with the neighbor aggregate at every iteration, controlled by a mixing parameter \(\alpha\):
The \(\alpha\) parameter controls how strongly each individual’s own diploid signal anchors the estimate. Higher \(\alpha\) (e.g. 0.7) trusts the individual’s own signal more and is more resistant to being pulled by noisy neighbors. Lower \(\alpha\) relies more heavily on the neighborhood.
Note
Empirically, graph_prop with alpha: 0.7, min_match: 0.95,
min_length: 2.0, and max_neighbors: 20 achieved the best
correlation with Bionano optical mapping ground truth on LPA KIV-2
(Pearson r = 0.83 short allele, 0.92 long allele).
Config: phasing_method: graph_prop |
Tunes: alpha, n_iters
graph_prop_weighted¶
Identical to graph_prop but uses the configured agg_fn (weighted
mean, median, etc.) for the neighbor aggregate instead of plain mean.
Useful when segment-length or match-score weighting is expected to improve
discrimination.
Config: phasing_method: graph_prop_weighted |
Tunes: alpha, agg_fn, n_iters
oneshot — Single-Pass¶
A non-iterative baseline. Neighbor values are fixed at the seed (\(\mathrm{IRR}_i / 2\)) and each sample’s estimate is computed independently in a single pass. Fast and useful as a lower bound on iterative performance.
Config: phasing_method: oneshot |
Tunes: agg_fn
rank_based — Rank-Normalised Iterative¶
Like iterative, but before each aggregation step all haplotype values
are rank-normalised to \([0, 1]\) across the cohort. This reduces the
influence of extreme copy-number outliers on the neighborhood signal.
Aggregation and partitioning proceed on the rank-normalised values; the diploid total is then used to recover the original scale.
Config: phasing_method: rank_based |
Tunes: agg_fn, n_iters
IBD Neighbor Loading and Quality Control¶
When method: ibd, neighbors are loaded from an iLASH .match file.
Two additional quality-control mechanisms beyond a flat match-score threshold
are available.
Two-Tier Neighbor Priority¶
When start_bp and end_bp are set in the top-level config (the VNTR
coordinates), IBD segments are assigned to one of two tiers before filling
each haplotype’s neighbor list:
Tier 1 (gold): segment physically overlaps the target VNTR region \([\mathrm{start\_bp},\, \mathrm{end\_bp}]\) and passes the quality gate. These neighbors share IBD directly at the locus of interest and are the most informative for haplotype-specific CN estimation.
Tier 2 (fill): segment passes the quality gate but does not overlap the VNTR region. Used only to fill any remaining slots in a haplotype’s neighbor list after Tier 1 neighbors are exhausted.
Within each tier, segments are ranked by \(\mathrm{cM} \times \mathrm{score}\)
descending. Set use_tiers: False to disable tiering and treat all qualifying
segments equally.
Length-Adaptive Match Threshold¶
Short IBD segments have a higher false-positive rate than long segments
and should require a stricter match score. Setting match_at_min_length
enables a length-dependent threshold that scales continuously from a
strict ceiling at min_length cM down to the lenient floor min_match
at long segments:
At \(L = \mathrm{min\_length}\), \(\theta = \mathrm{match\_at\_min\_length}\).
As \(L \to \infty\), \(\theta \to \mathrm{min\_match}\).
If match_at_min_length is not set, a flat threshold of min_match is
applied to all segments.
Mean Imputation for Unphased Samples¶
Individuals with fewer than min_neighbors neighbors on either haplotype
cannot be phased iteratively. For these individuals, haplotype copy numbers
are mean-imputed from whatever neighbors are available:
If no neighbors exist, the cohort mean \(\bar{\mathrm{IRR}} / 2\) is used.
Imputed values are written to hap1imp / hap2imp in the output file.
Output¶
The output file contains one row per individual with six columns:
Column |
Description |
|---|---|
|
Sample identifier |
|
Original diploid copy number estimate |
|
Inferred haplotype 0 copy number (iterative phasing); |
|
Inferred haplotype 1 copy number (iterative phasing); |
|
Mean-imputed haplotype 0 copy number (neighbor mean or cohort mean) |
|
Mean-imputed haplotype 1 copy number (neighbor mean or cohort mean) |
Configuration Reference¶
The full set of compute_haploid_genotypes config keys:
Key |
Default |
Description |
|---|---|---|
|
|
Neighbor source: |
|
|
Phasing algorithm: |
|
|
Neighbor aggregation: |
|
|
Mixing weight for |
|
|
Number of iterations. Ignored by |
|
|
Minimum neighbors required on both haplotypes to phase a sample. |
|
|
Maximum neighbors loaded per haplotype. |
|
— |
Path to IBS neighbors file. Required when |
|
— |
Path to iLASH |
|
|
Minimum IBD segment length in cM. |
|
|
Minimum iLASH match score (lenient floor for long segments when
|
|
|
Strict match score required at |
|
|
Apply \(\mathrm{match}^3 \times \mathrm{cM}\) weighting to IBD neighbor weights during loading. |
|
|
\(\lambda\) parameter (bp) for Lorentzian distance weighting
(only when |
Example config (IBD, recommended settings):
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
Example config (IBS, original algorithm):
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