varcode 2.2.0__tar.gz → 2.2.1__tar.gz

{varcode-2.2.0/varcode.egg-info → varcode-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: varcode
-Version: 2.2.0
+Version: 2.2.1
 Summary: Variant annotation in Python
 Author-email: Alex Rubinsteyn <alex.rubinsteyn@unc.edu>
 Project-URL: Homepage, https://github.com/openvax/varcode

varcode-2.2.1/tests/test_reference_mismatch_error.py

@@ -0,0 +1,103 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Regression tests for https://github.com/openvax/varcode/issues/215
+(and the duplicate symptom in #246).
+
+When a variant's ref allele doesn't match the reference genome at the
+variant's position — typically because the variant was called against
+a different build, the ref field was populated with the patient's
+germline allele, or there's strand confusion — varcode should raise a
+dedicated ``ReferenceMismatchError`` with an actionable message, not
+a generic ``ValueError`` or ``AssertionError``.
+"""
+
+import pytest
+
+import varcode
+from varcode import Variant, ReferenceMismatchError
+
+
+def _construct_mismatching_variant():
+    """Construct a variant whose ref doesn't match the GRCh38 genome.
+
+    Uses CFTR exon 4 (chr7:117530899-117531114 on GRCh38, + strand)
+    where the real genome has specific bases. We claim ref='Z'... well,
+    varcode rejects unknown nucleotides, so instead we use a valid
+    base that doesn't match the genome at that position.
+    """
+    # chr7:117531114 on GRCh38 is G (last base of CFTR exon 4). Claim
+    # the variant has ref='T' (which is wrong). This will fail the
+    # transcript-vs-variant ref check.
+    return Variant("7", 117531114, "T", "A", "GRCh38")
+
+
+def test_ref_mismatch_raises_reference_mismatch_error():
+    variant = _construct_mismatching_variant()
+    with pytest.raises(ReferenceMismatchError):
+        variant.effects()
+
+
+def test_reference_mismatch_error_is_value_error_subclass():
+    # Keep the existing contract: callers that catch ValueError still
+    # see this. (predict_variant_effect_on_transcript_or_failure relies
+    # on this for the Failure-effect fallback path.)
+    assert issubclass(ReferenceMismatchError, ValueError)
+
+
+def test_reference_mismatch_error_message_is_actionable():
+    variant = _construct_mismatching_variant()
+    try:
+        variant.effects()
+    except ReferenceMismatchError as e:
+        msg = str(e)
+        # Names the variant so the user can find it.
+        assert "117531114" in msg
+        # Shows both the expected (genome) and observed (variant) bases.
+        assert "'T'" in msg   # variant's claimed ref
+        assert "'G'" in msg   # actual genome base
+        # Suggests the most common causes.
+        assert "genome build" in msg or "germline" in msg or "strand" in msg
+        # Points at the escape hatch.
+        assert "raise_on_error=False" in msg
+    else:
+        raise AssertionError("Expected ReferenceMismatchError")
+
+
+def test_reference_mismatch_error_carries_structured_fields():
+    variant = _construct_mismatching_variant()
+    try:
+        variant.effects()
+    except ReferenceMismatchError as e:
+        assert e.variant == variant
+        assert e.transcript is not None
+        assert e.expected_ref == "G"
+        assert e.observed_ref == "T"
+    else:
+        raise AssertionError("Expected ReferenceMismatchError")
+
+
+def test_ref_mismatch_with_raise_on_error_false_returns_failure():
+    # When the user opts into error suppression, the mismatch should
+    # collapse into a Failure effect (the existing contract).
+    from varcode.effects import Failure
+    variant = _construct_mismatching_variant()
+    effects = variant.effects(raise_on_error=False)
+    assert any(isinstance(e, Failure) for e in effects), \
+        "Expected at least one Failure effect when raise_on_error=False"
+
+
+def test_reference_mismatch_error_exposed_at_package_level():
+    # Users should be able to catch varcode.ReferenceMismatchError
+    # without importing from a submodule.
+    assert varcode.ReferenceMismatchError is ReferenceMismatchError

{varcode-2.2.0 → varcode-2.2.1}/varcode/__init__.py

@@ -11,6 +11,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from .errors import ReferenceMismatchError
 from .variant import Variant
 from .variant_collection import VariantCollection
 from .maf import load_maf, load_maf_dataframe
@@ -22,10 +23,10 @@ from .effects import (
     MutationEffect,
     NonsilentCodingMutation,
 )
-from .version import __version__ 
+from .version import __version__
 
 __all__ = [
-    "__version__", 
+    "__version__",
 
     # basic classes
     "Variant",
@@ -38,6 +39,9 @@ __all__ = [
     "MutationEffect",
     "NonsilentCodingMutation",
 
+    # exceptions
+    "ReferenceMismatchError",
+
     # file loading
     "load_maf",
     "load_maf_dataframe",

{varcode-2.2.0 → varcode-2.2.1}/varcode/effects/effect_prediction.py

@@ -16,6 +16,7 @@ from Bio.Seq import reverse_complement
 from pyensembl import Transcript
 
 from ..common import groupby_field
+from ..errors import ReferenceMismatchError
 
 from .transcript_helpers import interval_offset_on_transcript
 from .effect_helpers import changes_exonic_splice_site
@@ -399,17 +400,15 @@ def exonic_transcript_effect(variant, exon, exon_number, transcript):
         transcript.sequence[transcript_offset:transcript_offset + n_ref])
 
     if cdna_ref != expected_ref:
-        raise ValueError(
-            ("Found ref nucleotides '%s' in sequence"
-             " of %s at offset %d (chromosome positions %d:%d)"
-             " but variant %s has '%s'") % (
-                 expected_ref,
-                 transcript,
-                 transcript_offset,
-                 genome_start,
-                 genome_end,
-                 variant,
-                 cdna_ref))
+        raise ReferenceMismatchError(
+            variant=variant,
+            transcript=transcript,
+            expected_ref=expected_ref,
+            observed_ref=cdna_ref,
+            transcript_offset=transcript_offset,
+            genome_start=genome_start,
+            genome_end=genome_end,
+        )
 
     utr5_length = min(transcript.start_codon_spliced_offsets)
 

{varcode-2.2.0 → varcode-2.2.1}/varcode/effects/effect_prediction_coding.py

@@ -10,6 +10,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from ..errors import ReferenceMismatchError
 from .effect_prediction_coding_frameshift import predict_frameshift_coding_effect
 from .effect_prediction_coding_in_frame import predict_in_frame_coding_effect
 
@@ -57,13 +58,14 @@ def predict_variant_coding_effect_on_transcript(
 
     # Make sure that the reference sequence agrees with what we expected
     # from the VCF
-    assert ref_nucleotides_from_transcript == trimmed_cdna_ref, \
-        "%s: expected ref '%s' at offset %d of %s, transcript has '%s'" % (
-            variant,
-            trimmed_cdna_ref,
-            transcript_offset,
-            transcript,
-            ref_nucleotides_from_transcript)
+    if ref_nucleotides_from_transcript != trimmed_cdna_ref:
+        raise ReferenceMismatchError(
+            variant=variant,
+            transcript=transcript,
+            expected_ref=ref_nucleotides_from_transcript,
+            observed_ref=trimmed_cdna_ref,
+            transcript_offset=transcript_offset,
+        )
 
     start_codon_offset = transcript.first_start_codon_spliced_offset
     stop_codon_offset = transcript.last_stop_codon_spliced_offset

varcode-2.2.1/varcode/errors.py

@@ -0,0 +1,69 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Exception types raised by varcode. ``ReferenceMismatchError`` subclasses
+``ValueError`` for backwards compatibility with callers that catch
+``ValueError`` already (including the internal
+``predict_variant_effect_on_transcript_or_failure`` fallback).
+"""
+
+
+class ReferenceMismatchError(ValueError):
+    """Raised when a variant's reported ref allele does not match the
+    reference genome at the variant's position.
+
+    This most often means one of:
+
+    * The variant was called against a different reference build than
+      the one being used for annotation (e.g. GRCh37 vs GRCh38).
+    * The variant's ref field was populated with the patient's germline
+      allele rather than the canonical reference. VCF requires the
+      ref field to match the reference genome; germline variants at
+      the same position should be encoded as separate variants.
+    * Strand confusion: the variant is specified on the negative
+      strand but varcode expects positive-strand coordinates.
+
+    Callers who would rather continue past this error can pass
+    ``raise_on_error=False`` to :meth:`Variant.effects` to receive
+    ``Failure`` effects instead.
+    """
+
+    def __init__(self, variant, transcript, expected_ref, observed_ref,
+                 transcript_offset=None, genome_start=None, genome_end=None):
+        self.variant = variant
+        self.transcript = transcript
+        self.expected_ref = expected_ref
+        self.observed_ref = observed_ref
+        self.transcript_offset = transcript_offset
+        self.genome_start = genome_start
+        self.genome_end = genome_end
+
+        location = ""
+        if transcript_offset is not None:
+            location = " at transcript offset %d" % transcript_offset
+        if genome_start is not None and genome_end is not None:
+            location += " (chromosome positions %d:%d)" % (
+                genome_start, genome_end)
+
+        message = (
+            "Reference allele mismatch for %s on %s%s: variant reports "
+            "ref=%r but the reference genome has %r at this position.\n"
+            "This usually means the variant was called against a "
+            "different genome build, the ref field was filled in with "
+            "the patient's germline allele rather than the reference, "
+            "or the variant is on the wrong strand. Pass "
+            "raise_on_error=False to .effects() to receive a Failure "
+            "effect instead of raising." % (
+                variant, transcript, location, observed_ref, expected_ref)
+        )
+        super().__init__(message)

varcode-2.2.1/varcode/version.py

@@ -0,0 +1 @@
+__version__ = "2.2.1"

{varcode-2.2.0 → varcode-2.2.1/varcode.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: varcode
-Version: 2.2.0
+Version: 2.2.1
 Summary: Variant annotation in Python
 Author-email: Alex Rubinsteyn <alex.rubinsteyn@unc.edu>
 Project-URL: Homepage, https://github.com/openvax/varcode

{varcode-2.2.0 → varcode-2.2.1}/varcode.egg-info/SOURCES.txt

@@ -31,6 +31,7 @@ tests/test_no_duplicate_variants.py
 tests/test_premature_stop_short_description.py
 tests/test_problematic_variants.py
 tests/test_reference.py
+tests/test_reference_mismatch_error.py
 tests/test_silent_aa_pos.py
 tests/test_silent_hgvs_description.py
 tests/test_splice_site_effects.py
@@ -45,6 +46,7 @@ tests/test_vcf_output.py
 varcode/__init__.py
 varcode/common.py
 varcode/csv_helpers.py
+varcode/errors.py
 varcode/maf.py
 varcode/nucleotides.py
 varcode/reference.py

varcode-2.2.0/varcode/version.py

@@ -1 +0,0 @@
-__version__ = "2.2.0"