varcode 2.2.0__tar.gz → 2.3.0__tar.gz

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

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

varcode-2.3.0/tests/test_genotype.py

@@ -0,0 +1,266 @@
+# 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.
+
+"""
+Unit tests for the Genotype dataclass and GT parsing (openvax/varcode#267).
+
+Tests that touch a real VCF end-to-end live in
+``tests/test_genotype_from_vcf.py``.
+"""
+
+import pytest
+
+from varcode import Genotype, Zygosity
+from varcode.genotype import parse_gt_string
+
+
+# ------------------------------------------------------------------
+# parse_gt_string: one low-level function, many cases
+# ------------------------------------------------------------------
+
+
+def test_parse_gt_diploid_unphased():
+    assert parse_gt_string("0/1") == ((0, 1), False)
+    assert parse_gt_string("1/0") == ((1, 0), False)
+    assert parse_gt_string("1/1") == ((1, 1), False)
+    assert parse_gt_string("0/0") == ((0, 0), False)
+
+
+def test_parse_gt_diploid_phased():
+    assert parse_gt_string("0|1") == ((0, 1), True)
+    assert parse_gt_string("1|0") == ((1, 0), True)
+
+
+def test_parse_gt_multiallelic():
+    # Multi-allelic: 1/2 means one copy of alt #1, one copy of alt #2.
+    assert parse_gt_string("1/2") == ((1, 2), False)
+    assert parse_gt_string("2|1") == ((2, 1), True)
+
+
+def test_parse_gt_haploid():
+    # Chromosomes X/Y in males, mitochondrial, etc. — single allele.
+    assert parse_gt_string("1") == ((1,), False)
+    assert parse_gt_string("0") == ((0,), False)
+
+
+def test_parse_gt_missing():
+    assert parse_gt_string("./.") == ((None, None), False)
+    assert parse_gt_string(".") == ((None,), False)
+    assert parse_gt_string("") == ((None,), False)
+    assert parse_gt_string(None) == ((None,), False)
+
+
+def test_parse_gt_partial_missing():
+    # Half-called genotypes — one haplotype missing.
+    assert parse_gt_string("./1") == ((None, 1), False)
+    assert parse_gt_string("0/.") == ((0, None), False)
+    assert parse_gt_string(".|1") == ((None, 1), True)
+
+
+def test_parse_gt_polyploid():
+    # Triploid (e.g. trisomy) or higher — tuple simply grows.
+    alleles, phased = parse_gt_string("0/1/1")
+    assert alleles == (0, 1, 1)
+    assert phased is False
+
+
+# ------------------------------------------------------------------
+# Genotype construction from pyvcf-style sample info dicts
+# ------------------------------------------------------------------
+
+
+def test_genotype_from_sample_info_full():
+    gt = Genotype.from_sample_info({
+        "GT": "0/1",
+        "AD": [10, 5],
+        "DP": 15,
+        "GQ": 99,
+    })
+    assert gt.raw_gt == "0/1"
+    assert gt.alleles == (0, 1)
+    assert gt.phased is False
+    assert gt.allele_depths == (10, 5)
+    assert gt.total_depth == 15
+    assert gt.genotype_quality == 99
+    assert gt.phase_set is None
+
+
+def test_genotype_from_sample_info_phased_with_ps():
+    gt = Genotype.from_sample_info({
+        "GT": "0|1",
+        "PS": 100,
+        "AD": [8, 7],
+        "DP": 15,
+        "GQ": 99,
+    })
+    assert gt.phased is True
+    assert gt.phase_set == 100
+
+
+def test_genotype_from_sample_info_nocall_handles_none_values():
+    # Pyvcf returns None for all fields when the call is ./.
+    gt = Genotype.from_sample_info({
+        "GT": "./.",
+        "AD": None,
+        "DP": None,
+        "GQ": None,
+    })
+    assert gt.alleles == (None, None)
+    assert gt.allele_depths is None
+    assert gt.is_missing
+    assert not gt.is_called
+
+
+def test_genotype_from_sample_info_none_input():
+    # Entirely missing sample_info dict (e.g. variant not constructed
+    # from a VCF).
+    gt = Genotype.from_sample_info(None)
+    assert gt.is_missing
+    assert gt.alleles == (None, None)
+
+
+# ------------------------------------------------------------------
+# General predicates (alt-agnostic)
+# ------------------------------------------------------------------
+
+
+def test_is_called_and_is_missing():
+    assert Genotype.from_sample_info({"GT": "0/1"}).is_called
+    assert not Genotype.from_sample_info({"GT": "./."}).is_called
+    assert Genotype.from_sample_info({"GT": "./."}).is_missing
+    # Partial-missing is still "called" because one allele is known.
+    assert Genotype.from_sample_info({"GT": "./1"}).is_called
+
+
+def test_ploidy():
+    assert Genotype.from_sample_info({"GT": "0/1"}).ploidy == 2
+    assert Genotype.from_sample_info({"GT": "1"}).ploidy == 1
+    assert Genotype.from_sample_info({"GT": "0/1/1"}).ploidy == 3
+
+
+def test_is_haploid():
+    assert Genotype.from_sample_info({"GT": "1"}).is_haploid
+    assert not Genotype.from_sample_info({"GT": "0/1"}).is_haploid
+
+
+# ------------------------------------------------------------------
+# Alt-relative zygosity (the business end of the API)
+# ------------------------------------------------------------------
+
+
+def test_zygosity_heterozygous_simple():
+    gt = Genotype.from_sample_info({"GT": "0/1"})
+    assert gt.zygosity_for_alt(1) is Zygosity.HETEROZYGOUS
+    assert gt.carries_alt(1)
+    assert gt.copies_of_alt(1) == 1
+
+
+def test_zygosity_homozygous_alt_simple():
+    gt = Genotype.from_sample_info({"GT": "1/1"})
+    assert gt.zygosity_for_alt(1) is Zygosity.HOMOZYGOUS
+    assert gt.carries_alt(1)
+    assert gt.copies_of_alt(1) == 2
+
+
+def test_zygosity_homozygous_ref_is_absent_for_any_alt():
+    gt = Genotype.from_sample_info({"GT": "0/0"})
+    # Relative to alt 1: sample doesn't have this alt.
+    assert gt.zygosity_for_alt(1) is Zygosity.ABSENT
+    assert not gt.carries_alt(1)
+    assert gt.copies_of_alt(1) == 0
+
+
+def test_zygosity_missing():
+    gt = Genotype.from_sample_info({"GT": "./."})
+    assert gt.zygosity_for_alt(1) is Zygosity.MISSING
+    assert not gt.carries_alt(1)
+    assert gt.copies_of_alt(1) == 0
+
+
+def test_zygosity_multiallelic_querying_different_alts():
+    # GT = 1/2 means one copy of alt #1, one copy of alt #2.
+    # Querying alt 1: het (one copy of this alt, one of a different alt).
+    # Querying alt 2: also het.
+    # Querying alt 3 (not carried): absent.
+    gt = Genotype.from_sample_info({"GT": "1/2"})
+    assert gt.zygosity_for_alt(1) is Zygosity.HETEROZYGOUS
+    assert gt.zygosity_for_alt(2) is Zygosity.HETEROZYGOUS
+    assert gt.zygosity_for_alt(3) is Zygosity.ABSENT
+
+
+def test_zygosity_multiallelic_homozygous_for_second_alt():
+    # GT = 2/2 means both copies are alt #2.
+    # Alt 2: hom. Alt 1: absent (sample doesn't have alt 1).
+    gt = Genotype.from_sample_info({"GT": "2/2"})
+    assert gt.zygosity_for_alt(2) is Zygosity.HOMOZYGOUS
+    assert gt.zygosity_for_alt(1) is Zygosity.ABSENT
+
+
+def test_zygosity_haploid_single_alt():
+    # chrY in a male with an alt call: GT = 1.
+    gt = Genotype.from_sample_info({"GT": "1"})
+    # Single-allele calls with that allele equal to alt: all copies
+    # are alt → classify as HOMOZYGOUS.
+    assert gt.zygosity_for_alt(1) is Zygosity.HOMOZYGOUS
+    assert gt.carries_alt(1)
+
+
+def test_zygosity_partial_call():
+    # GT = ./1: one allele missing, the other is alt #1.
+    # Out of the called alleles (just one), all are alt #1 → HOMOZYGOUS.
+    # This is the defensible read: we count called alleles only.
+    gt = Genotype.from_sample_info({"GT": "./1"})
+    assert gt.zygosity_for_alt(1) is Zygosity.HOMOZYGOUS
+
+
+# ------------------------------------------------------------------
+# Per-allele depth lookup
+# ------------------------------------------------------------------
+
+
+def test_depth_for_alt():
+    gt = Genotype.from_sample_info({"GT": "0/1", "AD": [10, 5]})
+    assert gt.depth_for_alt(0) == 10   # ref depth
+    assert gt.depth_for_alt(1) == 5    # first alt depth
+    assert gt.depth_for_alt(2) is None  # out of range
+
+
+def test_depth_for_alt_returns_none_when_ad_missing():
+    gt = Genotype.from_sample_info({"GT": "0/1"})
+    assert gt.depth_for_alt(1) is None
+
+
+def test_depth_for_alt_multiallelic():
+    # AD has one entry per allele (ref + each alt).
+    gt = Genotype.from_sample_info({"GT": "1/2", "AD": [3, 7, 5]})
+    assert gt.depth_for_alt(0) == 3
+    assert gt.depth_for_alt(1) == 7
+    assert gt.depth_for_alt(2) == 5
+
+
+# ------------------------------------------------------------------
+# Dataclass-y ergonomics: hashable, equatable, frozen
+# ------------------------------------------------------------------
+
+
+def test_genotype_is_frozen():
+    gt = Genotype.from_sample_info({"GT": "0/1"})
+    with pytest.raises((AttributeError, Exception)):
+        gt.alleles = (1, 1)  # type: ignore
+
+
+def test_genotype_equality():
+    a = Genotype.from_sample_info({"GT": "0/1", "AD": [10, 5], "DP": 15})
+    b = Genotype.from_sample_info({"GT": "0/1", "AD": [10, 5], "DP": 15})
+    assert a == b
+    c = Genotype.from_sample_info({"GT": "1/1", "AD": [0, 15], "DP": 15})
+    assert a != c

varcode-2.3.0/tests/test_genotype_from_vcf.py

@@ -0,0 +1,248 @@
+# 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.
+
+"""
+End-to-end tests for VariantCollection genotype/zygosity access —
+exercises the full path from VCF → Variant → Genotype (openvax/varcode#267).
+"""
+
+import os
+import tempfile
+
+import pytest
+
+from varcode import (
+    Genotype,
+    SampleNotFoundError,
+    Zygosity,
+    load_vcf,
+)
+
+
+VCF_BODY = """##fileformat=VCFv4.1
+##reference=GRCh38
+##FORMAT=<ID=GT,Number=1,Type=String,Description="Genotype">
+##FORMAT=<ID=AD,Number=R,Type=Integer,Description="Allele depths">
+##FORMAT=<ID=DP,Number=1,Type=Integer,Description="Read depth">
+##FORMAT=<ID=GQ,Number=1,Type=Integer,Description="Genotype quality">
+##FORMAT=<ID=PS,Number=1,Type=Integer,Description="Phase set">
+#CHROM	POS	ID	REF	ALT	QUAL	FILTER	INFO	FORMAT	tumor	normal
+17	43082575	.	C	T	100	PASS	.	GT:AD:DP:GQ	0/1:10,5:15:99	0/0:20,0:20:99
+7	117531114	.	G	T	100	PASS	.	GT:AD:DP:GQ	1/1:0,20:20:99	0/1:10,10:20:99
+1	100	.	A	T,G	100	PASS	.	GT:AD:DP:GQ	1/2:5,5,5:15:99	0/1:10,5,0:15:99
+17	43082576	.	C	A	100	PASS	.	GT:AD:DP:GQ:PS	0|1:8,7:15:99:100	./.:.:.:.:.
+"""
+
+
+@pytest.fixture
+def multi_sample_vcf():
+    fd, path = tempfile.mkstemp(suffix=".vcf")
+    with os.fdopen(fd, "w") as f:
+        f.write(VCF_BODY)
+    yield path
+    os.unlink(path)
+
+
+# -------------------------------------------------------------------
+# Sample discovery
+# -------------------------------------------------------------------
+
+
+def test_samples_property_lists_names(multi_sample_vcf):
+    vc = load_vcf(multi_sample_vcf, genome="GRCh38")
+    assert vc.samples == ["normal", "tumor"]
+
+
+def test_has_sample_data_true_for_vcf_with_samples(multi_sample_vcf):
+    vc = load_vcf(multi_sample_vcf, genome="GRCh38")
+    assert vc.has_sample_data() is True
+
+
+def test_has_sample_data_false_for_directly_constructed(multi_sample_vcf):
+    # Directly-constructed variants have no sample_info metadata.
+    from varcode import Variant, VariantCollection
+    vc = VariantCollection(variants=[
+        Variant("17", 43082575, "C", "T", "GRCh38"),
+    ])
+    assert vc.has_sample_data() is False
+    assert vc.samples == []
+
+
+# -------------------------------------------------------------------
+# Per-variant genotype access
+# -------------------------------------------------------------------
+
+
+def test_genotype_for_heterozygous_sample(multi_sample_vcf):
+    vc = load_vcf(multi_sample_vcf, genome="GRCh38")
+    # chr17:43082575 C>T — tumor 0/1, normal 0/0.
+    variant = next(
+        v for v in vc if v.start == 43082575 and v.alt == "T"
+    )
+    tumor_gt = vc.genotype(variant, "tumor")
+    assert tumor_gt.alleles == (0, 1)
+    assert tumor_gt.is_called
+    assert tumor_gt.zygosity_for_alt(1) is Zygosity.HETEROZYGOUS
+    assert tumor_gt.allele_depths == (10, 5)
+    assert tumor_gt.genotype_quality == 99
+
+    normal_gt = vc.genotype(variant, "normal")
+    assert normal_gt.alleles == (0, 0)
+    assert normal_gt.zygosity_for_alt(1) is Zygosity.ABSENT
+
+
+def test_genotype_for_homozygous_sample(multi_sample_vcf):
+    vc = load_vcf(multi_sample_vcf, genome="GRCh38")
+    variant = next(v for v in vc if v.start == 117531114)
+    tumor_gt = vc.genotype(variant, "tumor")
+    assert tumor_gt.alleles == (1, 1)
+    assert tumor_gt.zygosity_for_alt(1) is Zygosity.HOMOZYGOUS
+
+
+def test_genotype_phased_call_preserves_phase_info(multi_sample_vcf):
+    vc = load_vcf(multi_sample_vcf, genome="GRCh38")
+    variant = next(v for v in vc if v.start == 43082576)
+    tumor_gt = vc.genotype(variant, "tumor")
+    assert tumor_gt.phased is True
+    assert tumor_gt.phase_set == 100
+
+
+def test_genotype_nocall(multi_sample_vcf):
+    vc = load_vcf(multi_sample_vcf, genome="GRCh38")
+    variant = next(v for v in vc if v.start == 43082576)
+    normal_gt = vc.genotype(variant, "normal")
+    assert normal_gt.is_missing
+    assert normal_gt.zygosity_for_alt(1) is Zygosity.MISSING
+
+
+def test_genotype_unknown_sample_raises(multi_sample_vcf):
+    vc = load_vcf(multi_sample_vcf, genome="GRCh38")
+    variant = vc[0]
+    with pytest.raises(SampleNotFoundError):
+        vc.genotype(variant, "nonexistent_sample")
+
+
+def test_sample_not_found_is_key_error_subclass():
+    # Callers who only catch KeyError should still work.
+    assert issubclass(SampleNotFoundError, KeyError)
+
+
+def test_genotype_returns_none_for_variant_without_sample_info():
+    # A variant that wasn't loaded from a multi-sample VCF.
+    from varcode import Variant, VariantCollection
+    v = Variant("17", 43082575, "C", "T", "GRCh38")
+    vc = VariantCollection(variants=[v])
+    assert vc.genotype(v, "anyone") is None
+
+
+# -------------------------------------------------------------------
+# Multi-allelic sites
+# -------------------------------------------------------------------
+
+
+def test_multiallelic_row_splits_into_separate_variants_with_own_genotype(
+        multi_sample_vcf):
+    vc = load_vcf(multi_sample_vcf, genome="GRCh38")
+    # chr1:100 A>T,G — tumor has GT=1/2 (one T, one G).
+    at = next(v for v in vc if v.start == 100 and v.alt == "T")
+    ag = next(v for v in vc if v.start == 100 and v.alt == "G")
+
+    # Relative to each alt, the tumor is heterozygous (carries one
+    # copy of this alt and one copy of a different alt).
+    assert vc.zygosity(at, "tumor") is Zygosity.HETEROZYGOUS
+    assert vc.zygosity(ag, "tumor") is Zygosity.HETEROZYGOUS
+
+    # Normal has GT=0/1 (one ref, one T). Relative to T: het.
+    # Relative to G: absent (normal doesn't have the G alt).
+    assert vc.zygosity(at, "normal") is Zygosity.HETEROZYGOUS
+    assert vc.zygosity(ag, "normal") is Zygosity.ABSENT
+
+
+# -------------------------------------------------------------------
+# Convenience filters
+# -------------------------------------------------------------------
+
+
+def test_for_sample_filters_to_variants_carried_by_that_sample(
+        multi_sample_vcf):
+    vc = load_vcf(multi_sample_vcf, genome="GRCh38")
+
+    tumor_variants = vc.for_sample("tumor")
+    # Tumor carries all 4 variant-derived alts except normal-only ones.
+    # Check concretely:
+    # - 17:43082575 C>T: tumor 0/1 -> het, carried
+    # - 7:117531114 G>T: tumor 1/1 -> hom, carried
+    # - 1:100 A>T: tumor 1/2 -> carries T (alt #1)
+    # - 1:100 A>G: tumor 1/2 -> carries G (alt #2)
+    # - 17:43082576 C>A: tumor 0|1 -> het, carried
+    assert len(tumor_variants) == 5
+
+    normal_variants = vc.for_sample("normal")
+    # - 17:43082575 C>T: normal 0/0 -> absent
+    # - 7:117531114 G>T: normal 0/1 -> het, carried
+    # - 1:100 A>T: normal 0/1 -> carries T
+    # - 1:100 A>G: normal 0/1 -> absent (normal doesn't have G)
+    # - 17:43082576 C>A: normal ./. -> missing, not carried
+    assert len(normal_variants) == 2
+
+
+def test_heterozygous_in_excludes_homozygous_calls(multi_sample_vcf):
+    vc = load_vcf(multi_sample_vcf, genome="GRCh38")
+    het_in_tumor = vc.heterozygous_in("tumor")
+    starts = sorted(v.start for v in het_in_tumor)
+    # Tumor is het at:
+    # - 17:43082575 (0/1)
+    # - 1:100 (1/2 — het for both T and G)
+    # - 17:43082576 (0|1)
+    # NOT at 7:117531114 (1/1 is hom, not het)
+    assert starts == [100, 100, 43082575, 43082576]
+
+
+def test_homozygous_alt_in(multi_sample_vcf):
+    vc = load_vcf(multi_sample_vcf, genome="GRCh38")
+    hom_in_tumor = vc.homozygous_alt_in("tumor")
+    assert len(hom_in_tumor) == 1
+    assert hom_in_tumor[0].start == 117531114
+
+
+def test_for_sample_with_unknown_sample_raises(multi_sample_vcf):
+    vc = load_vcf(multi_sample_vcf, genome="GRCh38")
+    # Fail fast on typos rather than silently returning empty.
+    with pytest.raises(SampleNotFoundError):
+        vc.for_sample("nonexistent")
+
+
+def test_filter_chain_composes(multi_sample_vcf):
+    # Cross-sample queries fall out of set operations on the primitives.
+    vc = load_vcf(multi_sample_vcf, genome="GRCh38")
+    # "In tumor but not in normal" — somatic candidates.
+    tumor_set = set(vc.for_sample("tumor"))
+    normal_set = set(vc.for_sample("normal"))
+    somatic = tumor_set - normal_set
+    # Tumor carries: 17:43082575, 7:117531114, 1:100(T), 1:100(G), 17:43082576.
+    # Normal carries: 7:117531114, 1:100(T).
+    # Somatic = 17:43082575, 1:100(G), 17:43082576.
+    assert len(somatic) == 3
+    starts = sorted(v.start for v in somatic)
+    assert starts == [100, 43082575, 43082576]
+
+
+# -------------------------------------------------------------------
+# Package-level exports
+# -------------------------------------------------------------------
+
+
+def test_package_level_exports():
+    import varcode
+    assert varcode.Genotype is Genotype
+    assert varcode.Zygosity is Zygosity
+    assert varcode.SampleNotFoundError is SampleNotFoundError

varcode-2.3.0/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.3.0}/varcode/__init__.py

@@ -11,6 +11,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from .errors import ReferenceMismatchError, SampleNotFoundError
+from .genotype import Genotype, Zygosity
 from .variant import Variant
 from .variant_collection import VariantCollection
 from .maf import load_maf, load_maf_dataframe
@@ -22,22 +24,30 @@ from .effects import (
     MutationEffect,
     NonsilentCodingMutation,
 )
-from .version import __version__ 
+from .version import __version__
 
 __all__ = [
-    "__version__", 
+    "__version__",
 
     # basic classes
     "Variant",
     "EffectCollection",
     "VariantCollection",
 
+    # genotype / zygosity
+    "Genotype",
+    "Zygosity",
+
     # effects
     "effect_priority",
     "top_priority_effect",
     "MutationEffect",
     "NonsilentCodingMutation",
 
+    # exceptions
+    "ReferenceMismatchError",
+    "SampleNotFoundError",
+
     # file loading
     "load_maf",
     "load_maf_dataframe",