Resolving Variant Identity With GA4GH VRS Computed Identifiers

I spend most of my time on the operations and commercial side of UNMIRI, not in the codebase. But every few months a piece of engineering work comes across my desk that's worth writing up myself, because it goes straight at the question every buyer eventually asks us: how do you know two variants are actually the same variant. This is one of those.

The problem: the same variant, two different strings

A pathogenic EGFR variant can show up in one vendor's report as NM_005228.5:c.2573T>G and in another's as p.L858R, and a third might just print EGFR L858R in a table with no formal notation at all. All three describe the same change. UNMIRI's cross-vendor parsing already normalizes these to HGVS, using MANE Select transcripts as the default reference, which is what makes our NGS Interpretation API able to read Foundation Medicine, Tempus, Caris, Guardant, and Natera reports the same way.

Normalized HGVS gets you most of the way to a stable variant identity. It doesn't get you all the way. HGVS strings are still text, anchored to a specific transcript, and text comparison has edge cases: legacy transcript versions, genomic-versus-coding representation, insertion notation that different vendors write with different shorthand. A pipeline that keys its knowledge graph purely on the HGVS string can end up creating two separate nodes for what is, at the sequence level, one real variant. That's a quiet failure mode. Nothing errors out. The system just silently under-counts evidence for a variant because half of it landed under a different key.

What GA4GH VRS does differently

The Global Alliance for Genomics and Health publishes the Variation Representation Specification (VRS) for exactly this problem: a computed identifier derived directly from the reference sequence itself, not from a text string describing it. Two inputs that resolve to the same underlying change on the same reference sequence get the same VRS identifier, no matter which transcript or notation produced the original text. Identity becomes a property of the sequence, not a property of how someone happened to write it down.

VRS covers single-nucleotide variants, small insertions and deletions, and multi-nucleotide variants. It doesn't yet cover fusions, copy-number variants, or exon-skipping events, so it's a layer on top of HGVS normalization for the variant types it's scoped to, not a replacement for it.

What we actually built and tested

We built a variant-identity resolver on top of the existing normalization pipeline: real reference-sequence data (a local SeqRepo snapshot, not a mocked stand-in), the open-source hgvs and VRS-Python libraries, and MANE Select transcripts as the disambiguation table when an input is ambiguous or transcript-agnostic. Every resolution carries a status, not just a yes-or-no: resolved cleanly, ambiguous across candidate transcripts, unresolved with a specific reason, or outside VRS's supported variant types entirely. A confident wrong answer is worse than an honest "we couldn't resolve this one," so the resolver is built to say which of those four things happened rather than forcing every input through as a success.

We tested it against a real corpus pulled from actual manufacturer-published sample reports, not synthetic test cases invented to make the numbers look good. The majority of variant inputs in that corpus resolved cleanly to a computed VRS identifier on the first pass. The remainder split across a small number of concrete, identifiable reasons: intronic positions VRS doesn't cover, vendor shorthand that under-specifies an insertion, and a handful of genuinely ambiguous transcript calls. Every one of those categories is now a named, countable failure mode instead of an unexplained miss.

The resolver is wired into UNMIRI's Neo4j knowledge graph behind a switchable mode, so the existing HGVS-keyed path and the new VRS-resolved path can run side by side on the same data. That's deliberate. We want to measure where VRS resolution changes an outcome for the better before it becomes the only path, not assume it and find out later that we were wrong on some slice of real reports.

Where this stands today

This is real, tested software running against a real corpus, and it is not yet the default identity path in production. We're treating this the same way we treat every architecture claim on this site: describe what's built and tested honestly, and don't claim something is live before it actually is. Right now that means the ablation mode stays on, we keep characterizing the gap between the two paths, and the VRS-resolved path becomes the default once that characterization gives us confidence it's a strict improvement across the variant types it covers.

If you're building on top of vendor-reported genomics and you've ever had two reports on the same patient disagree about whether they're describing the same mutation, this is the layer that problem lives in. It's a narrow, unglamorous piece of infrastructure. It's also exactly the kind of thing that's invisible when it works and expensive when it doesn't.

Nida Uddin

Founder and CEO, UNMIRI

Building UNMIRI, a precision oncology infrastructure company with four product surfaces: cross-vendor NGS interpretation, genomics-aware decision support, oncology literature intelligence, and a free cross-vendor unification tool for clinicians. Writing here on architecture, clinical data, and HIPAA-ready AI.

See the NGS Interpretation API →

Advisors: Somdutta Saha, PhD, advises on technical architecture and bioinformatics methods as Technical and Scientific Advisor. On the clinical side, UNMIRI is in ongoing conversations with multiple board-certified pathologists about advisory roles. Public introductions land on the About page once each engagement is formalized and the advisor approves being named.