Skip to content

fix: validate reference allele stated in HGVS expressions - #655

Open
developer-rpai wants to merge 2 commits into
ga4gh:mainfrom
developer-rpai:fix-364-hgvs-ref-validation
Open

developer-rpai wants to merge 2 commits into
ga4gh:mainfrom
developer-rpai:fix-364-hgvs-ref-validation

Conversation

@developer-rpai

Copy link
Copy Markdown
Contributor

Summary

Closes #364.

HGVS-to-VRS translation silently accepted an incorrect reference allele: NM_006087.3:c.900C>A produced a plausible-looking VRS Allele even though the true reference base is G (per the ClinGen Allele Registry: "IncorrectReferenceAllele ... given=C, found=G", independently confirmed against NCBI RefSeq: with the CDS annotated at 373..1707, c.900 maps to n.1272, and NM_006087.3 n.1272 is G).

Root cause

The HGVS parser preserves the stated reference allele (sv.posedit.edit.ref), but HgvsTools.extract_allele_values() never inspected it, so a wrong reference flowed straight into the emitted Allele. The gnomAD translator path already validated reference alleles via DataProxy.validate_ref_seq(); the HGVS path did not.

Change

  • HgvsTools.extract_allele_values() accepts require_validation: bool = True. After any c.->n. mapping, when the HGVS expression states a reference allele (e.g. the C in c.900C>A, or deleted bases in g.44908822delC), it is validated against the reference sequence, raising DataProxyValidationError on mismatch; with require_validation=False the mismatch is only logged.
  • AlleleTranslator._from_hgvs() passes require_validation through, so the existing translate_from(..., require_validation=False) escape hatch now applies to HGVS input too.
  • Default behavior: refuse to emit an invalid Allele. Edits that state no reference allele (insertions, duplications, bare deletions) skip validation entirely.

Tests

  • New hermetic regression tests in tests/extras/test_allele_translator.py (no UTA/seqrepo network needed): the exact issue variant raises by default; a del-with-ref mismatch raises; correct-reference controls (substitution and deletion-with-ref) still translate; require_validation=False returns the allele with a logged warning; edits without a stated ref skip validation.
  • Negative control: with the src/ fix reverted, the two "raises" tests fail (pristine code emits the Allele); with the fix, all 5 pass.
  • Added the VCR cassette interactions required by the new reference lookups in test_from_hgvs and the test_hgvs substitution cases. Ground truth for the added interactions was cross-checked against the repo's own previously recorded cassettes and NCBI RefSeq.
  • Ruff check and format --check pass on all touched files.

Limitations

  • The UTA-backed VCR tests (test_from_hgvs, test_hgvs) could not be executed in this environment (no UTA or seqrepo access). Cassette completeness was verified by replaying the fixed code path against the recorded cassettes with the session-scoped cache shared, but CI is the authoritative check.
  • 3 pre-existing test_vrs_normalize.py failures (VCR cassette mismatches) occur identically with and without this change.

Related: #151 (maintainer discussion supports validating supplied reference alleles and raising rather than emitting invalid objects).

@developer-rpai
developer-rpai requested review from a team as code owners September 24, 2026 05:15
@developer-rpai
developer-rpai force-pushed the fix-364-hgvs-ref-validation branch from 6624c3d to 1d9ca7e Compare October 7, 2026 07:19

@korikuzma korikuzma left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please resolve the merge conflicts, address the HGVS validation compatibility issues, and add focused regression tests before merging.

Comment thread src/ga4gh/vrs/utils/hgvs_tools.py Outdated
Comment on lines +208 to +214
ref_allele = getattr(sv.posedit.edit, "ref", None)
if ref_allele:
self.data_proxy.validate_ref_seq(
sv.ac,
start,
end,
ref_allele.upper(),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Codex finding: Severity - Moderate (incorrect behavior under specific, realistic conditions); Blocking: Skip sequence comparison for length-only references

The HGVS parser stores the deletion length in edit.ref for expressions such as NC_000019.10:g.44908822del1. This code compares "1" against the reference base and raises DataProxyValidationError, rejecting a previously supported deletion that supplies no reference bases. Distinguish numeric lengths from literal sequences before validating, and add regression cases for length-only deletion and delins inputs.

Comment thread src/ga4gh/vrs/utils/hgvs_tools.py Outdated
# Allele would produce a plausible-but-wrong variant object
# (ga4gh/vrs-python#364), so validate it against the reference
# sequence just like the gnomAD translator does.
ref_allele = getattr(sv.posedit.edit, "ref", None)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Codex finding: Severity - Moderate (incorrect behavior under specific, realistic conditions); Blocking: Honor validation settings through coding-coordinate mapping

For the issue’s NM_006087.3:c.900C>A example, the real VariantMapper.c_to_n() performs extrinsic validation by default and raises HGVSInvalidVariantError before this check. Consequently, require_validation=False still raises, and the default path does not produce the documented DataProxyValidationError. The new tests hide this behavior by replacing HgvsTools.c_to_n() with a coordinate-only stub. Preserve the supplied reference through mapping and ensure validation follows require_validation; cover this with the real mapper behavior.

developer-rpai and others added 2 commits November 13, 2026 16:52
Rebased onto upstream main (resolves the test_allele_translator.py
conflict with the ga4gh#489 from-VRS regression test); change unchanged:

- HgvsTools.extract_allele_values gains require_validation: when the HGVS
  expression states a reference allele (e.g. the C in c.900C>A), it is
  validated against the reference sequence via DataProxy.validate_ref_seq
  (ga4gh#364); mismatch raises DataProxyValidationError unless
  require_validation=False
- AlleleTranslator._from_hgvs threads require_validation through
- Hermetic regression tests with a canned data proxy (no seqrepo/UTA)
Skip sequence comparison when edit.ref is a deletion length, as in del1
and del1ins. Project c. coordinates to n. without the default mapper's
extrinsic reference check or reference replacement, then apply
require_validation to the allele the expression stated.

Co-authored-by: Rakesh Pai <developer-rpai@users.noreply.github.com>
@cursor
cursor Bot force-pushed the fix-364-hgvs-ref-validation branch from 1d9ca7e to 5e5e394 Compare November 13, 2026 16:59

@larrybabb larrybabb left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for picking this up. Validating the stated reference allele is exactly what #364 and #151 call for, and the require_validation passthrough matches how the gnomAD translator already behaves. The tests for the original NM_006087.3:c.900C>A case are clear and well documented.

A few things I think are worth addressing before merge. Most are inline; one is outside the diff:

Beacon and SPDI still accept a wrong stated ref (translator.py, _from_beacon / _from_spdi). #364 (see the comment there) and #151 ask for ref validation across all input formats. With this PR, gnomAD and HGVS validate, but beacon never checks g["ref"], and SPDI with an explicit deleted sequence only uses its length. So translate_from("19 : 44908822 G > T", fmt="beacon") and translate_from("NC_000019.10:44908821:G:T", fmt="spdi") (true ref C) still return an Allele. One option: accept an optional stated ref in the values passed to _create_allele and call validate_ref_seq there once, which would cover beacon, SPDI and HGVS on a single path. If you'd rather keep this PR focused on HGVS, a follow-up issue linked from here would work too.

Test coverage. To make sure each behavior in this change is pinned down, I'd suggest adding tests for:

  • c. positions outside the CDS or transcript (c.1400dup, c.1400_1401insT on NM_006087.3) still raising, as they did before (see the inline note on the mapper)
  • c. del / delins / dup going through _project_c_to_n: correct ref passes, wrong ref raises, and del1 is skipped
  • an r. expression with a correct ref (contains u) not being rejected
  • a stated ref of N / NN not being rejected
  • mixed or lower-case stated refs in g. / c. expressions
  • require_validation=False on a deletion mismatch (not only on substitutions)
  • beacon and SPDI wrong-ref cases, if those get covered here

self._c_to_n_mapper = hgvs.variantmapper.VariantMapper(
self.uta_conn,
replace_reference=False,
prevalidation_level="INTRINSIC",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think prevalidation_level="INTRINSIC" turns off more than the ref check. In hgvs 1.5.x the extrinsic Validator is also where _c_within_cds_bound and _n_within_transcript_bounds live, so with this mapper a c. position past the CDS end (which should be written c.*N) is no longer rejected and maps into the 3′ UTR.

For example, on NM_006087.3 (CDS length 1335), c.1400dup or c.1400_1401insT (no stated ref, so the new check doesn't run either) used to raise HGVSInvalidVariantError ("Variant is outside CDS bounds") and would now produce an Allele. c.1400A>G would pass whenever the UTR base happens to be A.

Since the goal is to stop emitting Alleles from invalid HGVS, could we keep those bounds checks? For example: read the stated ref before projecting and keep using the default (validating) mapper, or call the extrinsic bounds checks explicitly. A test with an out-of-CDS c. position would lock this in.

sv.ac,
start,
end,
ref_allele.upper(),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hgvs_re accepts r. expressions, whose stated refs are lowercase RNA with u. After .upper(), a u becomes U, which never equals the T in the reference sequence, so valid input like NM_xxx:r.100u>c or r.100_101delua will now raise DataProxyValidationError even when the ref is correct. Those inputs translated before this PR.

Mapping U→T before the comparison, or skipping the check for r. variants, would avoid the false rejection. A small test with a correct r. ref would be good to have.

# (ga4gh/vrs-python#364), so validate it against the reference
# sequence just like the gnomAD translator does. A length-only ref
# (`del1`) is not a sequence and is left alone.
ref_allele = _reference_bases(getattr(sv.posedit.edit, "ref", None))

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A stated ref using the ambiguity code N (e.g. NC_000019.10:g.44908822delN) gets compared literally against the reference and will always mismatch, so valid HGVS that doesn't name the bases is now rejected. Inputs like this appear in ClinVar-derived data. Could N (any position, or an all-N ref) be treated as a wildcard or skipped, with a test for delN / delNN?

@larrybabb larrybabb left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some additional optional notes. These don't block the PR, but they may be useful to fold in, especially if the mapper approach changes in response to the bounds-check comment above.

mapped = self._c_to_n_mapper.c_to_n(sv)
edit = mapped.posedit.edit
if hasattr(edit, "ref"):
edit.ref = stated_ref

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Optional simplification: rather than a second VariantMapper plus writing edit.ref = stated_ref back after fill_ref, the stated ref could be read from the parsed variant (sv.posedit.edit) before projecting, and the existing c_to_n used as-is. That avoids depending on hgvs internals (whether fill_ref mutates the edit, whether c_to_n copies it), keeps the bounds checks, and leaves one c.→n. path instead of two that behave differently (the public HgvsTools.c_to_n still uses the validating mapper).

_logger = logging.getLogger(__name__)


def _reference_bases(ref: object) -> str | None:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Optional: hgvs already has edit.ref_s ("returns ref if it smells like a sequence"), which treats digit-only refs the same way. Reusing it (with whatever U/N handling we settle on) would keep a single definition of "stated reference" and less code to maintain. As it stands, _reference_bases and ref_s disagree on lowercase and RNA refs, which is part of what causes the r. mismatch noted above.

assert allele.state.sequence.root == "AT"


def test_from_hgvs_no_ref_allele_skips_validation(tlr_canned):

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docstring mentions "ins/dup/bare del", but this test (and the length-only test above) only covers g. expressions, where _project_c_to_n and its ref restore never run. Adding c. cases (e.g. NM_006087.3:c.900del1, c.900delG / c.900delC, c.900dup, and a c. delins with a wrong ref) would cover the restore logic, so a regression there gets caught.

{
"func": "get_seq",
"args": [
"NM_006087.3",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor: I don't think this get_seq(NM_006087.3, 1271, 1272) entry is read by the new code path. With replace_reference=False and INTRINSIC prevalidation, hgvs doesn't fetch the sequence for a sub, and the tests get reference bases from _CannedDataProxy. Dropping it, or noting why it's there, would avoid confusion about which source the check uses.

@developer-rpai

Copy link
Copy Markdown
Contributor Author

Thanks for the thorough review, Larry. I will extend the stated-ref check to Beacon and SPDI, or open a follow-up issue if we keep this PR HGVS-focused, restore the CDS and transcript bounds checks, handle the r. (U to T) and ambiguity-N cases, and add tests for the out-of-CDS, c. del/delins/dup, r., and delN cases.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

hgvs to vrs is returning valid results when hgvs has IncorrectReferenceAllele

4 participants