One Reference Cannot Represent Everyone
A read spanning an insertion can be perfectly correct and still look broken against one linear genome. The mapper takes the blame for a reference that never contained the path.
pangraphmap creates a reference haplotype, an alternate structural-variant path, and reads that cross the bubble. Both mappers use the same mismatch rule; only the reference representation changes.
Add The Path, Remove The Bias
The linear mapper searches one string. The graph-aware mapper scores both valid haplotype paths and keeps the best alignment.
It is the smallest useful demonstration of why pangenomes matter: not because graphs are fashionable, but because missing variation turns into missing reads.
Update: "maps all 25" turned out to be a tautology — the reads are pristine substrings of the alternate haplotype, so a perfect score was mathematically guaranteed, not measured. Fixed by simulating real sequencing error. Full writeup below.
The Number
The linear reference maps 6 of 25 reads under the same edit threshold. The pangenome maps all 25, a 76-point gain.
This is a seeded structural-variant simulation, not a replacement for vg or Minigraph-Cactus. The benchmark and test run without third-party dependencies.
A Perfect Score Was Reading A String Against Itself
Every read is sliced verbatim from the alternate haplotype (alt[i:i+36]), so scanning alt for the best-matching window always finds the exact window the read was cut from — distance zero, always within threshold. graph_mapped equaling 25 of 25 wasn't demonstrating that the graph representation helps; it was confirming that a string matches itself. Checked directly across 40 tuning seeds and a disjoint 25-seed holdout, evaluated once: every single run hit 25/25, zero variance.
The fix adds independent per-base substitution error (8%, standing in for real sequencing error) before mapping, so an exact match is no longer guaranteed. The graph-versus-linear advantage survives as a real, varying number instead of a guaranteed one: a mean 58.4-point gain on both sweeps, ranging 36 to 80 points, never pinned to 100. The original module is untouched and the published 6/25/76.0 numbers still reproduce exactly.
Research Basis
Inspired by Nature Genetics' 2025 pangenome graph review. The portfolio number above comes from this repository's own controlled benchmark, not from the paper.