v0.1.0-alpha.17

Decoding-Us Navigator — v0.1.0-alpha.17 (prerelease)

🧬 Realign a genome to the complete reference

Almost every whole genome arrives aligned to GRCh38 or GRCh37. Neither of those was ever finished, and neither was any human reference before them:

Every human reference genome prior to the Telomere-to-Telomere project left whole stretches blank — the Y chromosome worst of all. Reads that came from those regions had nowhere to map, so they were discarded, mismapped, or piled on top of one another. That is a property of the reference, not a defect in anyone's sequencing.

T2T closed those gaps. CHM13v2 (hs1) is the first complete human genome: a full autosomal sequence end to end, and — added in 2023 — the first complete Y chromosome. Two facts about it are worth stating plainly, because a "complete" genome is still somebody's genome. The assembly comes from a donor of European ancestry, so it represents Western European DNA most fully today. And the complete Y in it belongs to the J1a paternal lineage.

Navigator can now rebuild a GRCh38 or GRCh37 genome against that reference, from the reads in the file you already have. Open a subject's Sources tab and find the Reference build card, or in Simple mode look under Your test.

The benefit is genome-wide; what Navigator puts it to work on today is Y-chromosome discovery, where the old gaps were worst. On the 30× genome used to validate it, the share of the Y receiving any coverage at all went from 41% to 98%.

The check that matters, though, is not coverage but whether the result is right. The donor already had CHM13 alignments produced independently — including a PacBio HiFi one — so the realigned genome could be compared against the same person, aligned by someone else, by different software:

	Realigned	Their native CHM13
Y haplogroup	R-FGC29071 (1798 markers)	R-FGC29071 (1811 markers)
mtDNA haplogroup	U5a1b1g	U5a1b1g — identical score and marker count
Mean coverage	26.67×	26.95×

This is the way out of the private-variant problem alpha.16 described. That release found GRCh38/GRCh37 private-Y counts badly inflated, fixed 27% of it, and said plainly that the rest needed a rebuilt reference rather than a code change — so treat those counts as an upper bound. Realigning to CHM13 is that rebuild, one sample at a time.

The same genome, the same reads, counted before and after:

Private Y variants	On GRCh38	Realigned to CHM13
Reported	438	11
Of those, in structurally difficult regions	216	3
Passing the publication threshold	71	4
Sitting off the expected branch	4	0

Four hundred and thirty-eight against eleven, for one man who has one Y chromosome. The realigned figure is where an independent de-novo tree expects a sample like this to land; the GRCh38 figure was very largely the reference's difficulty being read as personal variation. Part of the reason is visible in the run itself: the masks that exclude the Y's known trouble spots are built on CHM13, and translating them back to GRCh38 loses intervals that have nowhere to go — 2 of 21 palindromic regions, 4 of 11 ampliconic, 1 of 3 in the AZF/DYZ area. Those unmasked stretches keep producing variants that are not yours.

What it costs. About four hours on a sixteen-core machine, and it peaks at 276 GB of working space. Navigator checks you have the room before starting and refuses with a number rather than filling your disk in hour three; the working files are removed when it finishes.

It never touches your original file. The realigned genome is added as a second alignment, recorded as derived from the first, so you keep both and can compare them.

It survives interruption. Cancel it, restart the machine, force-quit the app — the next run picks up from the last completed stage instead of starting over.

When not to bother: ancestry, IBD matching, and autosomal work already handle GRCh37 and GRCh38 directly and give the same answer either way. Realign if you are hunting private or novel Y-SNPs, or preparing evidence for a haplotree submission.

💾 Windows: the disk check that wasn't there

Navigator estimates the working space a long job needs and refuses to start one that cannot finish, rather than filling the disk partway through. On Windows that check was never implemented — it always answered "I don't know", and a job was allowed to start on the assumption that unknown meant fine.

That mattered little until this release, which adds a feature reserving hundreds of gigabytes. Windows now measures free space like the other platforms, and applies the same refusal.

Under the hood

• 47 commits, 977 tests. The realignment module's design, its measurements, and the questions it leaves open are in documents/design/realignment-module.md.
• The sort was the pipeline's real bottleneck, and not for the reason it looked. Coordinate-sorting a whole genome was taking 4 h 44 m of a 10 h run; the merge step was giving every one of its 688 temporary files an independent worker pool, putting 4,843 threads into one process and saturating the disk to no purpose. Sorting now takes 29 minutes, and a whole realignment about four hours instead of nearly eleven.
• macOS builds are Developer ID signed and notarized (verified against this release's own .dmg), so they open without a Gatekeeper detour. Windows installers are still unsigned — SmartScreen will warn about an unknown publisher until code signing lands before beta.
• Realignment is opt-in and never runs automatically, in the same way SV calling is: it is hours of work, and nothing should start that on your behalf.

---