Repository navigation
fix: validate reference allele stated in HGVS expressions - #655
developer-rpai wants to merge 2 commits into
Conversation
6624c3d to
1d9ca7e
Compare
korikuzma
left a comment
There was a problem hiding this comment.
Please resolve the merge conflicts, address the HGVS validation compatibility issues, and add focused regression tests before merging.
| ref_allele = getattr(sv.posedit.edit, "ref", None) | ||
| if ref_allele: | ||
| self.data_proxy.validate_ref_seq( | ||
| sv.ac, | ||
| start, | ||
| end, | ||
| ref_allele.upper(), |
There was a problem hiding this comment.
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.
| # 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) |
There was a problem hiding this comment.
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.
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>
1d9ca7e to
5e5e394
Compare
larrybabb
left a comment
There was a problem hiding this comment.
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_1401insTon NM_006087.3) still raising, as they did before (see the inline note on the mapper) - c.
del/delins/dupgoing through_project_c_to_n: correct ref passes, wrong ref raises, anddel1is skipped - an
r.expression with a correct ref (containsu) not being rejected - a stated ref of
N/NNnot being rejected - mixed or lower-case stated refs in g. / c. expressions
require_validation=Falseon 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", |
There was a problem hiding this comment.
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(), |
There was a problem hiding this comment.
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)) |
There was a problem hiding this comment.
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
left a comment
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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: |
There was a problem hiding this comment.
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): |
There was a problem hiding this comment.
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", |
There was a problem hiding this comment.
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.
|
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. |
Summary
Closes #364.
HGVS-to-VRS translation silently accepted an incorrect reference allele:
NM_006087.3:c.900C>Aproduced 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), butHgvsTools.extract_allele_values()never inspected it, so a wrong reference flowed straight into the emitted Allele. The gnomAD translator path already validated reference alleles viaDataProxy.validate_ref_seq(); the HGVS path did not.Change
HgvsTools.extract_allele_values()acceptsrequire_validation: bool = True. After any c.->n. mapping, when the HGVS expression states a reference allele (e.g. theCinc.900C>A, or deleted bases ing.44908822delC), it is validated against the reference sequence, raisingDataProxyValidationErroron mismatch; withrequire_validation=Falsethe mismatch is only logged.AlleleTranslator._from_hgvs()passesrequire_validationthrough, so the existingtranslate_from(..., require_validation=False)escape hatch now applies to HGVS input too.Tests
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=Falsereturns the allele with a logged warning; edits without a stated ref skip validation.src/fix reverted, the two "raises" tests fail (pristine code emits the Allele); with the fix, all 5 pass.test_from_hgvsand thetest_hgvssubstitution cases. Ground truth for the added interactions was cross-checked against the repo's own previously recorded cassettes and NCBI RefSeq.checkandformat --checkpass on all touched files.Limitations
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.test_vrs_normalize.pyfailures (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).