Model reference_assembly for pangenome-graph files (multi-reference; single value is ill-posed)

[NoopDog]

Found while preparing the project-overview deck (2026-08-18), via the 4 HPRC reference "mismatches" in output/hprc/hprc_validation_current.json.

The observation

All 4 reference disagreements against the HPRC Catalog are on Minigraph-Cactus pangenome-graph index artifacts (hprc-v1.0-mc-{chm13,grch38}-minaf.0.1.{min,dist}.old). A pangenome graph embeds multiple references as paths — GRCh38, CHM13, and the haplotype assemblies — so a single-valued reference_assembly is ill-posed for graph-family files:

• Our tier-2 filename rules answer the construction backbone (mc-grch38 → GRCh38) — consistent, but it silently picks one of several embedded references.
• The HPRC Catalog's referenceCoordinates is internally inconsistent on these very files: hprc-v1.0-mc-grch38-minaf.0.1.dist.old appears in two rows, once grch38 and once chm13; the chm13-named graph's row says grch38 (verifiable in data/hprc/alignments.json). So the "truth" side cannot decide either.

The question to settle

What should reference_assembly mean for graph-family files (data_type: pangenome / pangenome.reference, #144)?

Options to weigh:

1. not_applicable — the graph is its own coordinate system (consistent with how de novo assemblies are treated); the backbone, if wanted, becomes a separate fact.
2. Backbone value (current de facto behavior via filename rules) — informative but overloads the field's meaning ("the reference this data is on" vs "the backbone this graph was built around").
3. Multi-valued — schema change; out of scope for now per Roadmap: study-anchored external metadata (phsid → dbGaP record + methods paper → justify metadata picks) #323 (no schema work until Epics 1–2 land), but recordable as the eventual right answer if evidence supports it.

Whatever is chosen: the HPRC validator should stop counting these as mismatches once the semantics are settled, and the consistency linter (#314) could enforce the chosen rule for graph-family files.

Related: #144 (pangenome data_type), #329 (validator NA-scoring policy), #312 (companion-file resolution).

🤖 Generated with Claude Code