Skip to content

feat: haplotype (personalized) variant flanks via flank_source - #431

Merged
d-laub merged 1 commit into
mainfrom
feat/personal-flanks
Nov 20, 2026
Merged

d-laub merged 1 commit into
mainfrom
feat/personal-flanks

Conversation

@d-laub

@d-laub d-laub commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #430

What

New flank_source: "reference" | "haplotype" option (default "reference", so nothing changes unless you set it):

  • Dataset.with_settings(flank_source=...) controls the ride-along FlatVariants.flank_tokens.
  • VarWindowOpt(flank_source=...) controls "variant-windows" ref_window / alt_window.

With "haplotype", flanks come from the haplotype that carries each variant, so neighbouring SNPs/indels on the same haplotype show up in them:

  • alt_window = the haplotype around the variant (flank5 · ALT · flank3).
  • ref_window = the same haplotype context with only the focal variant reverted to REF.

It follows reconstruction semantics: greedy left-to-right, and a variant that overlaps an earlier applied one is not on the haplotype. Such a variant gets the haplotype around its reference position. Works for .svar and .svar2; the outputs are byte-identical between them, including .svar2 empty-ALT deletions, which are re-anchored.

Limits:

  • flank_source="haplotype" with unphased_union=True raises a ValueError, because union rows mix haplotypes.
  • Flanks only see the query region's variants. Bases past the region come from the reference.

How (throughput)

The Rust kernel (src/variants/windows.rs) builds one gap-compressed haplotype buffer per row. Each ALT is laid down, and any reference gap longer than 2L between ALTs is cut to its first and last L bases. Every flank is then one contiguous slice, so the work is O(variants · L) and doesn't depend on region length. Shadowed variants fall back to a short local walk.

In windows mode the reference window fetch is skipped entirely. Windows are assembled straight from the flank buffer plus the REF span, and tokenized while copying.

Microbenchmark of the kernel, 524k variants, best of 5. Ratio = haplotype time ÷ reference time; lower is better.

Variant density L flank_tokens windows
~1 var / 300 bp 16 0.42x 0.73x
64 0.61x 0.85x
256 0.52x 0.68x
~1 var / 8 bp 16 0.60x 0.86x
64 0.55x 0.67x
256 0.56x 0.71x

Haplotype flanks are faster than reference flanks in every case: they skip the strided reference window read and the extra interleave pass.

Update: this compares against the unfused reference path. #432 (stacked on this PR) applies the same single-pass fusion to the reference path, making it 2.8–4.1x faster. After #432, haplotype flanks are 0.94–1.7x the time of reference flanks, and both are faster than main.

Tests

  • tests/dataset/test_hap_flanks.py (new). A dense synthetic VCF with SNPs, insertions, and deletions a few bp apart, checked against gvl's own reconstructed haplotypes for flank_tokens, alt_window, and ref_window on both .svar and .svar2. Also covers .svar == .svar2, the default, rejection of bad values, and rejection of unphased_union.
  • 7 new Rust unit tests for haplotype_flanks: SNPs, row isolation, deletion plus edge padding, empty-ALT re-anchor, insertion, shadowed overlap, and long-allele truncation.
  • tests/unit/test_producer_schema.py: flank_source round-trips through the buffered-dataloader producer schema.
  • Results:
    • Full pytest tests: 1356 passed. The 1 failure was an exact-dict schema assertion missing the new key; after the fix that file passes 12/12.
    • cargo test --lib: 142 passed.
    • ruff, pyrefly, the docstring check, and clippy (no new warnings) are clean.

Docs

  • skills/genvarloader/SKILL.md: flank_source on the ride-along and VarWindowOpt, plus a gotcha.
  • docs/source/faq.md: new "Can variant flanks show the sample's haplotype…" section.

🤖 Generated with Claude Code

Add flank_source: "reference" | "haplotype" (default "reference") to
Dataset.with_settings (ride-along FlatVariants.flank_tokens) and
VarWindowOpt (variant-windows). With "haplotype", flanks are taken from
the haplotype carrying each variant, so neighbouring ALTs appear in them;
alt_window is exactly the haplotype around the variant and ref_window is
the same context with the focal variant reverted.

The Rust kernel builds one gap-compressed haplotype buffer per row (ref
gaps > 2L cut to their outer L bases), so each flank is a single slice.
Variants shadowed by an earlier overlapping ALT fall back to a local
walk. Windows are assembled and tokenized in one pass without the
reference window fetch, which makes haplotype flanks 0.42-0.86x the time
of reference flanks.

Rejected with unphased_union. flank_source is carried through the
buffered dataloader producer schema.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@d-laub
d-laub merged commit 96b1e91 into main Nov 20, 2026
7 of 8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

enh: personalized (haplotype) variant flanks instead of reference sequence

1 participant