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 (method key)

ibs — computeIBSpbwt output (ibs_output required) ibd — iLASH output (ibd_output required)

Phasing algorithm (phasing_method key, 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-normalised

Aggregation function (agg_fn key, 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