Repository navigation
feat: haplotype (personalized) variant flanks via flank_source - #431
Merged
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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-alongFlatVariants.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
.svarand.svar2; the outputs are byte-identical between them, including.svar2empty-ALT deletions, which are re-anchored.Limits:
flank_source="haplotype"withunphased_union=Trueraises aValueError, because union rows mix haplotypes.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.
Haplotype flanks are faster than reference flanks in every case: they skip the strided reference window read and the extra interleave pass.
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.svarand.svar2. Also covers.svar==.svar2, the default, rejection of bad values, and rejection ofunphased_union.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_sourceround-trips through the buffered-dataloader producer schema.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.Docs
skills/genvarloader/SKILL.md:flank_sourceon the ride-along andVarWindowOpt, plus a gotcha.docs/source/faq.md: new "Can variant flanks show the sample's haplotype…" section.🤖 Generated with Claude Code