Haplotype Inference¶
Decomposes diploid copy number estimates into haplotype-specific values using
neighbor-based phasing. Supports two neighbor sources (IBS via computeIBSpbwt,
or IBD via iLASH) and five phasing algorithms selectable via config.
This step is locus-agnostic — it requires only diploid CN estimates and a phased
neighbors file.
For a full description of the algorithms, neighbor quality-control options, and configuration reference, see Haplotype Inference.
- grid.utils.hi_inference.PHASING_METHODS = ('iterative', 'graph_prop', 'oneshot', 'rank_based', 'oneshot_rank')¶
All valid values for phasing_method and agg_fn (for validation / help text)
- grid.utils.hi_inference._adaptive_match_threshold(length_cM, min_length, min_match, match_at_min_length)¶
Length-dependent match score threshold.
Short segments near min_length require a high match score (match_at_min_length). Long segments asymptote down to min_match.
- Uses a hyperbolic curve fitted to two anchor points:
(min_length, match_at_min_length) (inf, min_match)
- Derivation:
- threshold(L) = min_match + (match_at_min_length - min_match)
min_length / L
At L = min_length → match_at_min_length (strict) At L → ∞ → min_match (lenient floor)
If match_at_min_length == min_match the function is flat (disabled).
- grid.utils.hi_inference._aggregate(vals, weights, agg_fn, fallback)¶
Aggregate a list of neighbor values using the chosen function.
agg_fn options¶
mean — simple arithmetic mean (ignores weights) median — median (ignores weights) weighted_cM — weights proportional to segment cM (stored in weights) weighted_score — weights proportional to match score (stored in weights) weighted_cM_score — combined cM × score weight (stored in weights) trimmed_mean — 10 % trimmed mean
- grid.utils.hi_inference._collect_neighbor_vals(h_idx, hap_IRRs, hap_nbrs)¶
Return (vals, weights) for all non-NaN neighbors of haplotype h_idx. vals and weights are plain Python lists.
- grid.utils.hi_inference._compute_imp(i, hap_IRRs, hap_nbrs, mean_IRRs)¶
Compute imputed haplotype neighbour means for sample i.
- grid.utils.hi_inference._init_candidates(IRRs, hap_nbrs, MIN_NBR)¶
Identify samples with >= MIN_NBR neighbors on BOTH haplotypes. Returns (candidate_set, hap_IRRs initialised to diploid/2, mean_IRRs).
- grid.utils.hi_inference._load_ibd_neighbors(ilash_file, IDtoInd, MAX_NBR, min_length=0.5, min_match=0.7, match_at_min_length=None, region_start=None, region_end=None, weighted=False, weight_scale=1000000)¶
Load IBD neighbors from iLASH output using a two-tier priority system.
- Tier 1 (gold): segment overlaps the VNTR region [region_start, region_end]
AND passes the quality gate.
- Tier 2 (fill): passes quality gate but does not overlap the VNTR region.
Used to fill remaining neighbor slots after Tier 1.
If region_start/region_end are None, all segments are Tier 1.
- Quality gate — length-adaptive match threshold:
If match_at_min_length is set (and > min_match), the required match score scales with segment length:
- threshold(L) = min_match
(match_at_min_length - min_match) * min_length / L
Short segments (L ≈ min_length) must clear match_at_min_length. Long segments asymptote to min_match. If match_at_min_length is None or == min_match, a flat threshold (min_match) is used for all lengths.
Within each tier, segments are ranked by length * match descending. HAP_ID format: {FID}_{hap} where hap is 0 or 1 (0-indexed). Returns hap_nbrs: list of lists of (neighbor_hap_idx, weight).
- grid.utils.hi_inference._load_ibs_neighbors(neighbors_file, IDtoInd, MAX_NBR)¶
Load IBS neighbors from computeIBSpbwt output. Haplotypes are 1-indexed (1 or 2). Returns hap_nbrs: list of lists of (neighbor_hap_idx, weight=1.0).
- grid.utils.hi_inference._phase_graph_prop(IRRs, hap_nbrs, MIN_NBR, N_ITERS, alpha, console)¶
- Label-spreading:
each iter: mixed_h = alpha*(diploid/2) + (1-alpha)*neighbor_mean then partition diploid by ratio of mixed values.
alpha=0.7 (trust own signal 70 %) gave best empirical results.
- grid.utils.hi_inference._phase_iterative(IRRs, hap_nbrs, MIN_NBR, N_ITERS, agg_fn, console)¶
- Original Hujoel algorithm:
initialise hap = diploid/2 each iter: partition diploid by ratio of neighbor aggregate means
- grid.utils.hi_inference._phase_oneshot(IRRs, hap_nbrs, MIN_NBR, agg_fn, console)¶
Single-pass, non-iterative. Neighbours’ values are always diploid/2 (the seed), so each sample’s estimate is independent of all others.
- grid.utils.hi_inference._phase_oneshot_rank(IRRs, hap_nbrs, MIN_NBR, agg_fn, console)¶
Single-pass rank-normalised variant. Seeds are rank-normalised diploid/2 values; no iteration.
- grid.utils.hi_inference._phase_rank_based(IRRs, hap_nbrs, MIN_NBR, N_ITERS, agg_fn, console)¶
Iterative, but ranks hap IRRs to [0,1] before aggregating neighbours. Reduces influence of extreme copy-number outliers on the mean signal.
- grid.utils.hi_inference._read_dip_cn_file(dip_cn_file)¶
Read diploid CN file with string IDs, skipping non-data rows.
- grid.utils.hi_inference.hi_inference(config, console)¶
Impute haplotype-specific IRRs from diploid IRRs and haplotype neighbours.
Neighbour source (
methodkey)¶ibs — computeIBSpbwt output (
ibs_outputrequired) ibd — iLASH output (ibd_outputrequired)Phasing algorithm (
phasing_methodkey, default:graph_prop)¶iterative — Hujoel C++ port (original GRID default) graph_prop — Label-spreading; tune with
alpha(default 0.7) oneshot — Single-pass, no iteration rank_based — Iterative on rank-normalised values oneshot_rank — Single-pass rank-normalisedAggregation function (
agg_fnkey, default:mean)¶Used by iterative, oneshot, rank_based, oneshot_rank. Ignored by graph_prop (always uses plain mean for neighbour signal).
mean | median | weighted_cM | weighted_score | weighted_cM_score | trimmed_mean
Output columns: ID IRRs hap1phased hap2phased hap1imp hap2imp