varcode 2.2.1__tar.gz → 2.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: varcode
-Version: 2.2.1
+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.2.1 → varcode-2.3.0}/varcode/__init__.py

@@ -11,7 +11,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from .errors import ReferenceMismatchError
+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
@@ -33,6 +34,10 @@ __all__ = [
     "EffectCollection",
     "VariantCollection",
 
+    # genotype / zygosity
+    "Genotype",
+    "Zygosity",
+
     # effects
     "effect_priority",
     "top_priority_effect",
@@ -41,6 +46,7 @@ __all__ = [
 
     # exceptions
     "ReferenceMismatchError",
+    "SampleNotFoundError",
 
     # file loading
     "load_maf",

{varcode-2.2.1 → varcode-2.3.0}/varcode/errors.py

@@ -18,6 +18,11 @@ Exception types raised by varcode. ``ReferenceMismatchError`` subclasses
 """
 
 
+class SampleNotFoundError(KeyError):
+    """Raised when genotype info is requested for a sample that isn't
+    present in the VariantCollection's source VCF(s)."""
+
+
 class ReferenceMismatchError(ValueError):
     """Raised when a variant's reported ref allele does not match the
     reference genome at the variant's position.

varcode-2.3.0/varcode/genotype.py

@@ -0,0 +1,200 @@
+# 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.
+
+"""
+Per-sample genotype representation — see openvax/varcode#267.
+
+A ``Genotype`` captures one sample's call at one variant locus: the
+alleles observed, whether the call was phased, and any supporting
+FORMAT fields (AD, DP, GQ, PS) that were present in the VCF. Zygosity
+is computed relative to a specific alt allele index, which matters for
+multi-allelic sites where a sample may carry a different alt from the
+one being queried.
+
+This module is intentionally free of circular imports so it can be
+used anywhere in varcode without pulling in the rest of the package.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional, Tuple
+
+
+class Zygosity(Enum):
+    """Zygosity of a sample's genotype relative to a specific alt allele.
+
+    ``ABSENT`` is distinct from ``MISSING``: ABSENT means the call
+    exists but doesn't include the alt in question (e.g. the sample
+    is ref-ref, or carries a *different* alt at a multi-allelic
+    site). MISSING means the call itself is ``./.`` or the sample
+    wasn't called.
+    """
+    ABSENT = "absent"
+    HETEROZYGOUS = "het"
+    HOMOZYGOUS = "hom"
+    MISSING = "missing"
+
+
+def parse_gt_string(gt_str):
+    """Parse a VCF ``GT`` string into ``(alleles, phased)``.
+
+    Handles:
+    * Standard diploid: ``"0/1"``, ``"1/1"``, ``"1/2"``
+    * Phased diploid: ``"0|1"``, ``"1|0"``
+    * Haploid (chrY, chrM): ``"1"``, ``"0"``
+    * Polyploid: ``"0/1/1"`` → alleles = (0, 1, 1)
+    * Missing: ``"./."``, ``"."``, ``""``, ``None``
+    * Partial missing: ``"./1"`` → alleles = (None, 1)
+
+    Returns a tuple ``(alleles, phased)`` where ``alleles`` is a tuple
+    of ``Optional[int]`` (``None`` for missing) and ``phased`` is
+    ``True`` iff the string used the ``|`` delimiter.
+    """
+    if not gt_str or gt_str == ".":
+        return ((None,), False)
+    if "|" in gt_str:
+        phased = True
+        parts = gt_str.split("|")
+    else:
+        phased = False
+        parts = gt_str.split("/")
+    alleles = tuple(
+        None if p == "." else int(p)
+        for p in parts
+    )
+    return alleles, phased
+
+
+@dataclass(frozen=True)
+class Genotype:
+    """One sample's genotype at one variant locus.
+
+    The ``alleles`` tuple encodes the observed alleles using VCF GT
+    semantics: ``0`` is the reference allele, ``1`` is the first ALT
+    listed on the VCF row, ``2`` is the second, and so on. ``None``
+    indicates a no-call on that haplotype.
+
+    For varcode's variant-level API, note that ``Variant.alt`` is a
+    *specific* alt (a multi-allelic VCF row is split into one Variant
+    per alt). When querying zygosity relative to a Variant, use the
+    variant's ``alt_allele_index`` from the collection's metadata and
+    add 1 to get the GT-encoded index, then call
+    :meth:`zygosity_for_alt` or :meth:`carries_alt`.
+    """
+
+    raw_gt: str
+    alleles: Tuple[Optional[int], ...]
+    phased: bool = False
+    phase_set: Optional[int] = None
+    allele_depths: Optional[Tuple[int, ...]] = None
+    total_depth: Optional[int] = None
+    genotype_quality: Optional[int] = None
+
+    # ---- construction ------------------------------------------------
+
+    @classmethod
+    def from_sample_info(cls, sample_info):
+        """Build a Genotype from pyvcf's ``call.data._asdict()`` output.
+
+        Handles the keys varcode normally sees: ``GT``, ``AD``, ``DP``,
+        ``GQ``, ``PS``. Missing keys default to ``None``.
+        """
+        if sample_info is None:
+            return cls(raw_gt="./.", alleles=(None, None), phased=False)
+        gt_str = sample_info.get("GT")
+        if gt_str is None:
+            gt_str = "./."
+        alleles, phased = parse_gt_string(gt_str)
+        ad = sample_info.get("AD")
+        return cls(
+            raw_gt=gt_str,
+            alleles=alleles,
+            phased=phased,
+            phase_set=sample_info.get("PS"),
+            allele_depths=tuple(ad) if ad is not None else None,
+            total_depth=sample_info.get("DP"),
+            genotype_quality=sample_info.get("GQ"),
+        )
+
+    # ---- general predicates (alt-agnostic) --------------------------
+
+    @property
+    def is_called(self) -> bool:
+        """True if at least one allele is non-None."""
+        return any(a is not None for a in self.alleles)
+
+    @property
+    def is_missing(self) -> bool:
+        return not self.is_called
+
+    @property
+    def ploidy(self) -> int:
+        """Number of alleles in the call (including missing)."""
+        return len(self.alleles)
+
+    @property
+    def is_haploid(self) -> bool:
+        return self.ploidy == 1
+
+    # ---- alt-relative predicates ------------------------------------
+
+    def carries_alt(self, alt_index: int) -> bool:
+        """True if this sample's genotype contains the given alt.
+
+        ``alt_index`` uses VCF GT encoding: ``1`` is the first alt on
+        the row, ``2`` is the second, etc. (i.e. one more than
+        ``alt_allele_index`` from the VariantCollection metadata).
+        """
+        return any(
+            a == alt_index
+            for a in self.alleles
+            if a is not None
+        )
+
+    def copies_of_alt(self, alt_index: int) -> int:
+        """Number of haplotypes carrying the given alt."""
+        return sum(
+            1 for a in self.alleles
+            if a is not None and a == alt_index
+        )
+
+    def zygosity_for_alt(self, alt_index: int) -> Zygosity:
+        """Classify the sample's zygosity relative to one alt allele.
+
+        Multi-allelic aware: ``GT=1/2`` queried for alt ``1`` returns
+        ``HETEROZYGOUS`` (one copy of this alt, one of a different
+        alt); queried for alt ``3`` it returns ``ABSENT``.
+        """
+        called = [a for a in self.alleles if a is not None]
+        if len(called) == 0:
+            return Zygosity.MISSING
+        n_copies = sum(1 for a in called if a == alt_index)
+        if n_copies == 0:
+            return Zygosity.ABSENT
+        if n_copies == len(called):
+            return Zygosity.HOMOZYGOUS
+        return Zygosity.HETEROZYGOUS
+
+    # ---- depth helpers ----------------------------------------------
+
+    def depth_for_alt(self, alt_index: int) -> Optional[int]:
+        """Per-allele read depth for a given alt, from the ``AD`` field.
+
+        ``AD`` is indexed with ref at position 0 and alt #1 at
+        position 1, etc., so ``alt_index`` should use GT encoding
+        (``1`` = first alt).
+        """
+        if self.allele_depths is None:
+            return None
+        if alt_index >= len(self.allele_depths):
+            return None
+        return self.allele_depths[alt_index]

{varcode-2.2.1 → varcode-2.3.0}/varcode/variant_collection.py

@@ -24,6 +24,8 @@ from .csv_helpers import (
     warn_on_version_drift,
     write_metadata_header,
 )
+from .errors import SampleNotFoundError
+from .genotype import Genotype, Zygosity
 from .variant import Variant, variant_ascending_position_sort_key
 from .version import __version__ as _varcode_version
 
@@ -485,6 +487,142 @@ class VariantCollection(Collection):
             sort_key=sort_key,
         )
 
+    # ------------------------------------------------------------------
+    # Genotype / zygosity access (openvax/varcode#267).
+    #
+    # The VCF loader already captures per-sample FORMAT fields in
+    # self.source_to_metadata_dict[path][variant]['sample_info']. These
+    # methods surface that data as structured Genotype objects and
+    # provide sample-aware filtering helpers.
+    # ------------------------------------------------------------------
+
+    def _metadata_for(self, variant):
+        """Find the metadata dict for a variant across all sources.
+
+        Returns None if the variant isn't tracked in any of this
+        collection's source-keyed metadata maps.
+        """
+        for variant_map in self.source_to_metadata_dict.values():
+            if variant in variant_map:
+                return variant_map[variant]
+        return None
+
+    @property
+    def samples(self):
+        """Sorted list of sample names present in the collection's
+        ``sample_info`` metadata (empty if no VCFs with sample columns
+        were loaded)."""
+        sample_set = set()
+        for variant_map in self.source_to_metadata_dict.values():
+            for meta in variant_map.values():
+                sample_info = meta.get("sample_info") if meta else None
+                if sample_info:
+                    sample_set.update(sample_info.keys())
+        return sorted(sample_set)
+
+    def has_sample_data(self):
+        """True if the collection has any per-sample genotype info."""
+        return len(self.samples) > 0
+
+    def genotype(self, variant, sample):
+        """Return the ``Genotype`` for ``sample`` at ``variant``.
+
+        Parameters
+        ----------
+        variant : Variant
+        sample : str
+
+        Returns
+        -------
+        Genotype or None
+            ``None`` if the variant has no sample_info metadata at all
+            (e.g. it was constructed directly rather than loaded from
+            a multi-sample VCF).
+
+        Raises
+        ------
+        SampleNotFoundError
+            If the variant's metadata exists but doesn't include the
+            requested sample. Subclass of ``KeyError``.
+        """
+        meta = self._metadata_for(variant)
+        if meta is None:
+            return None
+        sample_info = meta.get("sample_info")
+        if sample_info is None:
+            return None
+        if sample not in sample_info:
+            raise SampleNotFoundError(
+                "Sample %r not found in %s. Available samples: %s" % (
+                    sample, variant, sorted(sample_info.keys())))
+        return Genotype.from_sample_info(sample_info[sample])
+
+    def _alt_index_for(self, variant):
+        """VCF GT-encoded index (1-based) of the variant's alt on the
+        original VCF row, or ``None`` if unknown.
+
+        Single-alt rows and variants not loaded from VCF effectively
+        have alt_allele_index == 0, which encodes to GT index 1.
+        """
+        meta = self._metadata_for(variant)
+        if meta is None:
+            return 1
+        idx = meta.get("alt_allele_index")
+        if idx is None:
+            return 1
+        return idx + 1
+
+    def zygosity(self, variant, sample):
+        """Zygosity of the given sample at the given variant.
+
+        Multi-allelic aware: at a site split into multiple Variants,
+        each asks "does this sample carry *this* alt?".
+        """
+        gt = self.genotype(variant, sample)
+        if gt is None:
+            return Zygosity.MISSING
+        return gt.zygosity_for_alt(self._alt_index_for(variant))
+
+    def for_sample(self, sample):
+        """Return a VariantCollection restricted to variants where
+        ``sample`` carries the alt (heterozygous or homozygous). Useful
+        for multi-sample VCFs where not every row is called in every
+        sample.
+        """
+        return self._filter_by_zygosity(
+            sample,
+            keep=lambda z: z in (Zygosity.HETEROZYGOUS, Zygosity.HOMOZYGOUS),
+        )
+
+    def heterozygous_in(self, sample):
+        """Variants where ``sample`` is heterozygous for this variant's alt."""
+        return self._filter_by_zygosity(
+            sample,
+            keep=lambda z: z is Zygosity.HETEROZYGOUS,
+        )
+
+    def homozygous_alt_in(self, sample):
+        """Variants where ``sample`` is homozygous for this variant's alt."""
+        return self._filter_by_zygosity(
+            sample,
+            keep=lambda z: z is Zygosity.HOMOZYGOUS,
+        )
+
+    def _filter_by_zygosity(self, sample, keep):
+        # Pre-validate the sample once so a typo fails loudly rather
+        # than silently returning an empty collection.
+        if self.has_sample_data() and sample not in self.samples:
+            raise SampleNotFoundError(
+                "Sample %r not found. Available samples: %s" % (
+                    sample, self.samples))
+        return self.filter(
+            lambda v: keep(self.zygosity(v, sample))
+        )
+
+    # ------------------------------------------------------------------
+    # (end genotype methods)
+    # ------------------------------------------------------------------
+
     def clone_without_ucsc_data(self):
         variants = [v.clone_without_ucsc_data() for v in self]
         return self.clone_with_new_elements(variants)

varcode-2.3.0/varcode/version.py

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: varcode
-Version: 2.2.1
+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.2.1 → varcode-2.3.0}/varcode.egg-info/SOURCES.txt

@@ -23,6 +23,8 @@ tests/test_effect_collection_sort_order.py
 tests/test_effects_from_mutagenix_variants.py
 tests/test_exonic_splice_site.py
 tests/test_frameshift_helpers.py
+tests/test_genotype.py
+tests/test_genotype_from_vcf.py
 tests/test_maf.py
 tests/test_mm10_klf6_frameshift.py
 tests/test_mouse.py
@@ -47,6 +49,7 @@ varcode/__init__.py
 varcode/common.py
 varcode/csv_helpers.py
 varcode/errors.py
+varcode/genotype.py
 varcode/maf.py
 varcode/nucleotides.py
 varcode/reference.py

varcode-2.2.1/varcode/version.py

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