varcode 7.1.2__tar.gz → 7.2.0__tar.gz

{varcode-7.1.2/varcode.egg-info → varcode-7.2.0}/PKG-INFO

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

varcode-7.2.0/tests/test_effect_hypotheses.py

@@ -0,0 +1,183 @@
+"""Tests for graph-valid hypotheses and baseline-aware merging."""
+
+from types import SimpleNamespace
+
+import pytest
+
+from varcode.effect_hypotheses import (
+    ClassifiedOutcome,
+    EffectHypothesis,
+    RealizedTranscriptProduct,
+    SpliceAxis,
+    SpliceOption,
+    SpliceSiteKey,
+    enumerate_splice_plans,
+    merge_classified_outcomes,
+    order_realized_candidates,
+)
+
+
+def effect(name="Deletion", priority=5):
+    cls = type(name, (), {})
+    value = cls()
+    value.aa_mutation_start_offset = 3
+    value.aa_ref = "D"
+    value.aa_alt = ""
+    value.priority = priority
+    return value
+
+
+def product(protein, cdna="AAACCC", junctions=()):
+    return RealizedTranscriptProduct(
+        transcript=None,
+        cdna_sequence=cdna,
+        protein_sequence=protein,
+        junction_signature=junctions)
+
+
+def test_splice_enumeration_omits_site_removed_by_another_choice():
+    exon4 = (4, 1)
+    acceptor = SpliceAxis(
+        key=SpliceSiteKey("acceptor", 4),
+        anchor_runs=(exon4,),
+        options=(
+            SpliceOption("normal", 0, required_runs=(exon4,)),
+            SpliceOption("exon_skip", 1, skipped_runs=(exon4,)),
+        ))
+    donor = SpliceAxis(
+        key=SpliceSiteKey("donor", 4),
+        anchor_runs=(exon4,),
+        options=(
+            SpliceOption("normal", 0, required_runs=(exon4,)),
+            SpliceOption("exon_skip", 1, skipped_runs=(exon4,)),
+        ))
+
+    plans = enumerate_splice_plans((acceptor, donor), (exon4,))
+    mechanisms = [
+        tuple(option.mechanism for _, option in plan.choices)
+        for plan in plans]
+
+    assert mechanisms == [("normal", "normal"), ("exon_skip",),
+                          ("exon_skip",)]
+    assert all(len(plan.choices) != 2 or plan.kept_runs for plan in plans)
+
+
+def test_splice_rule_rank_is_not_reported_as_probability():
+    axis = SpliceAxis(
+        key=SpliceSiteKey("donor", 4),
+        anchor_runs=(4,),
+        options=(SpliceOption("exon_skip", 0, skipped_runs=(4,)),))
+
+    (plan,) = enumerate_splice_plans((axis,), (4,))
+
+    assert plan.ordinal_key == (0,)
+    assert plan.probability is None
+
+
+def test_calibrated_splice_probabilities_are_multiplied():
+    axes = tuple(
+        SpliceAxis(
+            key=SpliceSiteKey("donor", exon),
+            anchor_runs=(exon,),
+            options=(SpliceOption(
+                "normal", 0, required_runs=(exon,), probability=p),))
+        for exon, p in ((4, 0.8), (5, 0.5)))
+
+    (plan,) = enumerate_splice_plans(axes, (4, 5))
+
+    assert plan.probability == pytest.approx(0.4)
+
+
+def test_same_mutant_different_patient_baseline_does_not_merge():
+    mutant = product("ABCDE")
+    outcome_a = ClassifiedOutcome(
+        hypothesis=EffectHypothesis(phase=(("g", "trans"),)),
+        effect=effect(),
+        baseline=product("ABCDEFG"),
+        mutant=mutant,
+        change_aa_offset=3)
+    outcome_b = ClassifiedOutcome(
+        hypothesis=EffectHypothesis(phase=(("g", "cis"),)),
+        effect=effect(),
+        baseline=product("ABCXEFG"),
+        mutant=mutant,
+        change_aa_offset=3)
+
+    candidates = merge_classified_outcomes((outcome_a, outcome_b))
+
+    assert len(candidates) == 2
+
+
+def test_identical_comparisons_merge_and_preserve_hypotheses():
+    baseline = product("ABCDEFG")
+    mutant = product("ABCDE")
+    outcomes = tuple(
+        ClassifiedOutcome(
+            hypothesis=EffectHypothesis(
+                phase=(("g", phase),), phase_probability=0.5,
+                enumeration_index=index),
+            effect=effect(),
+            baseline=baseline,
+            mutant=mutant,
+            change_aa_offset=3)
+        for index, phase in enumerate(("trans", "cis")))
+
+    (candidate,) = merge_classified_outcomes(outcomes)
+
+    assert len(candidate.hypotheses) == 2
+    assert candidate.phase_mass == 1.0
+
+
+def test_candidate_probability_combines_calibrated_splice_and_phase():
+    baseline = product("ABCDEFG")
+    mutant = product("ABCDE")
+    plan = SimpleNamespace(ordinal_key=(0,), probability=0.4)
+    outcomes = tuple(
+        ClassifiedOutcome(
+            EffectHypothesis(
+                phase=(("g", phase),), phase_probability=0.5,
+                splice_plan=plan),
+            effect(), baseline, mutant, 3)
+        for phase in ("trans", "cis"))
+
+    (candidate,) = merge_classified_outcomes(outcomes)
+
+    assert candidate.probability == pytest.approx(0.4)
+
+
+def test_junction_signature_is_part_of_product_identity():
+    baseline = product("ABCDEFG")
+    outcomes = (
+        ClassifiedOutcome(
+            EffectHypothesis(), effect(), baseline,
+            product("ABCDE", junctions=((4, 6),)), 3),
+        ClassifiedOutcome(
+            EffectHypothesis(), effect(), baseline,
+            product("ABCDE", junctions=((4, 7),)), 3),
+    )
+
+    assert len(merge_classified_outcomes(outcomes)) == 2
+
+
+def test_ordering_uses_ordinal_rank_when_scores_are_uncalibrated():
+    baseline = product("ABCDEFG")
+    mutant = product("ABCDE")
+    low_priority = effect("Deletion", priority=5)
+    high_priority = effect("FrameShift", priority=10)
+    plans = [
+        SimpleNamespace(ordinal_key=(0,), probability=None),
+        SimpleNamespace(ordinal_key=(1,), probability=None),
+    ]
+    outcomes = tuple(
+        ClassifiedOutcome(
+            EffectHypothesis(splice_plan=plan, enumeration_index=index),
+            current_effect, baseline, mutant, 3)
+        for index, (plan, current_effect) in enumerate(
+            zip(plans, (low_priority, high_priority))))
+    candidates = merge_classified_outcomes(outcomes)
+
+    ordered = order_realized_candidates(
+        candidates, lambda value: value.priority)
+
+    assert ordered[0].effect is low_priority
+    assert ordered[0].probability is None

varcode-7.2.0/tests/test_genomic_layout.py

@@ -0,0 +1,160 @@
+"""Tests for the coordinate-aware realized-genome layout."""
+
+from types import SimpleNamespace
+
+import pytest
+
+from varcode.genomic_layout import (
+    GenomicLayout,
+    LayoutSegment,
+    SequenceUnavailable,
+    join_breakends,
+    project_intervals,
+)
+from varcode.structural_variant import Breakend
+
+
+SEQUENCES = {
+    "a": "AACCGGTTAACC",
+    "b": "TTGGCCAATTGG",
+}
+
+
+def provider(contig, start, end):
+    return SEQUENCES[contig][start - 1:end]
+
+
+def point(contig, start, ref, alt):
+    return SimpleNamespace(
+        contig=contig,
+        trimmed_base1_start=start,
+        trimmed_base1_end=start + len(ref) - 1 if ref else start,
+        trimmed_ref=ref,
+        trimmed_alt=alt,
+        is_structural=False)
+
+
+def structural(kind, start, end, affected_start=None, affected_end=None,
+               alt_assembly=None):
+    return SimpleNamespace(
+        contig="a",
+        start=start,
+        end=end,
+        affected_start=(start if affected_start is None else affected_start),
+        affected_end=(end if affected_end is None else affected_end),
+        sv_type=kind,
+        alt_assembly=alt_assembly,
+        is_structural=True)
+
+
+def test_layout_is_lazy_until_materialized():
+    layout = GenomicLayout.from_interval("a", 1, 12)
+    assert layout.length == 12
+    with pytest.raises(SequenceUnavailable):
+        layout.materialize()
+
+
+def test_point_variants_preserve_origins_on_both_strands():
+    forward = GenomicLayout.from_interval(
+        "a", 1, 12, sequence_provider=provider)
+    reverse = GenomicLayout.from_interval(
+        "a", 1, 12, strand="-", sequence_provider=provider)
+    variant = point("a", 3, "C", "T")
+
+    forward_mutant = forward.apply_point_variant(variant)
+    reverse_mutant = reverse.apply_point_variant(variant)
+
+    assert forward_mutant.materialize() == "AATCGGTTAACC"
+    assert reverse_mutant.materialize() == "GGTTAACCGATT"
+    assert forward_mutant.origins()[2] == ("a", 3, "alternate")
+    assert reverse_mutant.origins()[-3] == ("a", 3, "alternate")
+
+
+def test_indels_have_explicit_inserted_and_deleted_origins():
+    layout = GenomicLayout.from_interval(
+        "a", 1, 12, sequence_provider=provider)
+    inserted = layout.apply_point_variant(point("a", 4, "", "TA"))
+    deleted = layout.apply_point_variant(point("a", 3, "CC", ""))
+
+    assert inserted.materialize() == "AACCTA GGTTAACC".replace(" ", "")
+    assert [origin[1] for origin in inserted.origins()][4:6] == [None, None]
+    assert deleted.materialize() == "AAGGTTAACC"
+    assert 3 not in [origin[1] for origin in deleted.origins()]
+    assert 4 not in [origin[1] for origin in deleted.origins()]
+
+
+def test_typed_deletion_does_not_remove_retained_padding_anchor():
+    layout = GenomicLayout.from_interval(
+        "a", 1, 12, sequence_provider=provider)
+    deletion = structural(
+        "DEL", start=2, end=6, affected_start=3, affected_end=6)
+
+    mutant = layout.apply_structural_variant(deletion)
+
+    assert mutant.materialize() == "AATTAACC"
+    assert [origin[1] for origin in mutant.origins()][:3] == [1, 2, 7]
+
+
+def test_duplication_and_inversion_work_in_transcript_order():
+    forward = GenomicLayout.from_interval(
+        "a", 1, 12, sequence_provider=provider)
+    reverse = GenomicLayout.from_interval(
+        "a", 1, 12, strand="-", sequence_provider=provider)
+
+    forward_dup = forward.apply_structural_variant(structural("DUP", 3, 6))
+    reverse_dup = reverse.apply_structural_variant(structural("DUP", 3, 6))
+    inverted = forward.apply_structural_variant(structural("INV", 2, 5))
+
+    assert forward_dup.materialize() == "AACCGGCCGGTTAACC"
+    assert reverse_dup.materialize() == "GGTTAACCGGCCGGTT"
+    assert inverted.materialize() == "ACGGTGTTAACC"
+    assert {kind for _, _, kind in inverted.origins()[1:5]} == {"inverted"}
+
+
+def test_apply_variants_deletes_an_earlier_point_edit_on_same_haplotype():
+    layout = GenomicLayout.from_interval(
+        "a", 1, 12, sequence_provider=provider)
+    variants = [
+        structural("DEL", 2, 6, affected_start=3, affected_end=6),
+        point("a", 4, "C", "T"),
+    ]
+
+    mutant = layout.apply_variants(variants)
+
+    assert mutant.materialize() == "AATTAACC"
+    assert all(kind != "alternate" for _, _, kind in mutant.origins())
+
+
+def test_cross_contig_breakend_join_orients_retained_sides():
+    left = GenomicLayout.from_interval(
+        "a", 1, 12, sequence_provider=provider)
+    right = GenomicLayout.from_interval(
+        "b", 1, 12, strand="-", sequence_provider=provider)
+
+    fusion = join_breakends(
+        left,
+        Breakend("a", 3, "left"),
+        right,
+        Breakend("b", 8, "right"))
+
+    assert fusion.materialize() == "AACATTGG"
+    assert fusion.endpoint_origin(first=False) == ("b", 12)
+    assert fusion.origins()[2][:2] == ("a", 3)
+    assert fusion.origins()[3][:2] == ("b", 8)
+
+
+def test_project_intervals_keeps_duplicate_exon_occurrences():
+    layout = GenomicLayout.from_interval(
+        "a", 1, 12, sequence_provider=provider)
+    duplicated = layout.apply_structural_variant(structural("DUP", 3, 6))
+
+    runs = project_intervals(duplicated, (("a", 3, 6),))
+
+    assert [run.materialize() for run in runs] == ["CCGG", "CCGG"]
+    assert runs[0].segments[0].origin_kind == "reference"
+    assert runs[1].segments[0].origin_kind == "duplicated"
+
+
+def test_inserted_segment_requires_sequence():
+    with pytest.raises(ValueError):
+        LayoutSegment(None, None, None)

varcode-7.2.0/varcode/effect_hypotheses.py

@@ -0,0 +1,319 @@
+# 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.
+
+"""Composable hypothesis and realized-product data types.
+
+These types deliberately keep three concepts separate:
+
+* a hypothesis records uncertain biological choices;
+* a transcript product records what sequence those choices produce;
+* a classified outcome compares a mutant product with the patient's own
+  baseline product.
+
+Keeping the baseline in the merge identity is load-bearing.  Two phase
+hypotheses can produce the same mutant protein while deleting different
+patient-specific residues; those are different effects even though the
+mutant molecule alone is identical.
+"""
+
+import itertools
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Optional, Tuple
+
+
+@dataclass(frozen=True, order=True)
+class SpliceSiteKey:
+    """Stable identity of a splice site in a rearranged layout."""
+
+    side: str
+    exon_number: int
+    occurrence: int = 1
+
+    def __post_init__(self):
+        if self.side not in ("donor", "acceptor"):
+            raise ValueError("side must be 'donor' or 'acceptor'")
+        if self.exon_number < 1 or self.occurrence < 1:
+            raise ValueError("exon_number and occurrence must be positive")
+
+
+@dataclass(frozen=True)
+class SpliceOption:
+    """One graph rewrite offered at a disrupted splice site.
+
+    ``ordinal_rank`` expresses preference only.  It is not a probability.
+    A calibrated scorer can independently populate ``probability``.
+    """
+
+    mechanism: str
+    ordinal_rank: int
+    skipped_runs: Tuple[Any, ...] = field(default_factory=tuple)
+    required_runs: Tuple[Any, ...] = field(default_factory=tuple)
+    probability: Optional[float] = None
+    evidence: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        if self.ordinal_rank < 0:
+            raise ValueError("ordinal_rank must be non-negative")
+        if self.probability is not None and not 0.0 <= self.probability <= 1.0:
+            raise ValueError("probability must be between zero and one")
+
+
+@dataclass(frozen=True)
+class SpliceAxis:
+    """Choices attached to one splice-graph site."""
+
+    key: SpliceSiteKey
+    anchor_runs: Tuple[Any, ...]
+    options: Tuple[SpliceOption, ...]
+
+    def __post_init__(self):
+        if not self.anchor_runs:
+            raise ValueError("A splice axis requires at least one anchor run")
+        if not self.options:
+            raise ValueError("A splice axis requires at least one option")
+
+
+@dataclass(frozen=True)
+class SplicePlan:
+    """A graph-valid set of splice choices."""
+
+    choices: Tuple[Tuple[SpliceSiteKey, SpliceOption], ...]
+    kept_runs: Tuple[Any, ...]
+
+    @property
+    def ordinal_key(self):
+        """Lexicographic mechanism preference; lower is preferred."""
+        return tuple(option.ordinal_rank for _, option in self.choices)
+
+    @property
+    def probability(self):
+        """Joint probability only when every selected option is calibrated."""
+        probabilities = [option.probability for _, option in self.choices]
+        if any(value is None for value in probabilities):
+            return None
+        result = 1.0
+        for value in probabilities:
+            result *= value
+        return result
+
+
+def enumerate_splice_plans(axes, run_keys, max_plans=64):
+    """Enumerate graph-valid plans without multiplying dead splice sites.
+
+    A Cartesian product treats every initially disrupted site as independent.
+    That produces impossible combinations when one choice skips the exon that
+    another choice needs.  Here every axis also has an implicit inactive
+    choice.  It may be inactive only when another selected rewrite removes
+    all of its anchor runs.  Conversely, a selected option is rejected when
+    another rewrite removes one of its required runs.
+    """
+    axes = tuple(sorted(axes, key=lambda axis: axis.key))
+    run_keys = tuple(run_keys)
+    plans = []
+    # Put real choices before the inactive sentinel so enumeration order
+    # follows each axis's declared biological preference.
+    selections = [(axis.options + (None,)) for axis in axes]
+    for combination in itertools.product(*selections):
+        skipped_by = {}
+        for axis, option in zip(axes, combination):
+            if option is None:
+                continue
+            for run in option.skipped_runs:
+                skipped_by.setdefault(run, set()).add(axis.key)
+        kept = tuple(run for run in run_keys if run not in skipped_by)
+        kept_set = set(kept)
+        valid = True
+        choices = []
+        for axis, option in zip(axes, combination):
+            removed_by_other = any(
+                any(owner != axis.key for owner in skipped_by.get(run, ()))
+                for run in axis.anchor_runs)
+            if option is None:
+                if not all(run not in kept_set for run in axis.anchor_runs):
+                    valid = False
+                    break
+                continue
+            if removed_by_other:
+                valid = False
+                break
+            if any(run not in kept_set for run in option.required_runs):
+                valid = False
+                break
+            choices.append((axis.key, option))
+        if not valid:
+            continue
+        plans.append(SplicePlan(tuple(choices), kept))
+        if len(plans) > max_plans:
+            raise ValueError(
+                "Splice hypothesis count exceeds max_plans=%d" % max_plans)
+    return tuple(plans)
+
+
+@dataclass(frozen=True)
+class EffectHypothesis:
+    """One assignment of phase, splicing and structural resolution."""
+
+    phase: Tuple[Tuple[Any, str], ...] = field(default_factory=tuple)
+    splice_plan: Optional[SplicePlan] = None
+    phase_probability: Optional[float] = 1.0
+    evidence: Mapping[str, Any] = field(default_factory=dict)
+    enumeration_index: int = 0
+
+
+@dataclass(frozen=True)
+class RealizedTranscriptProduct:
+    """A materialized mRNA/protein plus its non-reference junctions."""
+
+    transcript: Optional[Any]
+    cdna_sequence: Optional[str]
+    protein_sequence: Optional[str]
+    junction_signature: Tuple[Tuple[Any, ...], ...] = field(
+        default_factory=tuple)
+    start_codon_present: Optional[bool] = None
+    evidence: Mapping[str, Any] = field(default_factory=dict)
+
+    def local_protein(self, offset, flank=30):
+        """Protein window around a change, or the full product if unknown."""
+        if self.protein_sequence is None:
+            return None
+        if offset is None:
+            return self.protein_sequence
+        start = max(0, offset - flank)
+        end = min(len(self.protein_sequence), offset + flank + 1)
+        return self.protein_sequence[start:end]
+
+    def local_cdna(self, offset, flank=90):
+        """cDNA window for products with no translated difference."""
+        if self.cdna_sequence is None:
+            return None
+        if offset is None:
+            return self.cdna_sequence
+        start = max(0, offset - flank)
+        end = min(len(self.cdna_sequence), offset + flank + 1)
+        return self.cdna_sequence[start:end]
+
+
+def _effect_identity(effect):
+    """Stable semantic fields used in candidate merge identity."""
+    return (
+        type(effect).__name__,
+        getattr(effect, "aa_mutation_start_offset", None),
+        getattr(effect, "aa_ref", None),
+        getattr(effect, "aa_alt", None),
+        getattr(effect, "splice_signal", None),
+    )
+
+
+@dataclass(frozen=True)
+class ClassifiedOutcome:
+    """An effect classified between a baseline and mutant product."""
+
+    hypothesis: EffectHypothesis
+    effect: Any
+    baseline: RealizedTranscriptProduct
+    mutant: RealizedTranscriptProduct
+    change_aa_offset: Optional[int] = None
+    change_cdna_offset: Optional[int] = None
+
+    def merge_key(self, protein_flank=30, cdna_flank=90):
+        """Identity of the comparison, not merely the mutant product."""
+        return (
+            _effect_identity(self.effect),
+            self.baseline.local_protein(self.change_aa_offset, protein_flank),
+            self.mutant.local_protein(self.change_aa_offset, protein_flank),
+            self.baseline.local_cdna(self.change_cdna_offset, cdna_flank),
+            self.mutant.local_cdna(self.change_cdna_offset, cdna_flank),
+            self.baseline.junction_signature,
+            self.mutant.junction_signature,
+        )
+
+
+@dataclass(frozen=True)
+class RealizedEffectCandidate:
+    """Merged equivalent outcomes with all hypothesis provenance retained."""
+
+    effect: Any
+    outcomes: Tuple[ClassifiedOutcome, ...]
+    ordinal_key: Tuple[int, ...]
+    probability: Optional[float]
+    phase_mass: Optional[float]
+    first_enumeration_index: int
+
+    @property
+    def hypotheses(self):
+        return tuple(outcome.hypothesis for outcome in self.outcomes)
+
+
+def merge_classified_outcomes(outcomes, protein_flank=30, cdna_flank=90):
+    """Merge only outcomes with identical baseline→mutant comparisons."""
+    groups = {}
+    order = []
+    for outcome in outcomes:
+        key = outcome.merge_key(protein_flank, cdna_flank)
+        if key not in groups:
+            groups[key] = []
+            order.append(key)
+        groups[key].append(outcome)
+
+    candidates = []
+    for key in order:
+        group = tuple(groups[key])
+        plans = [outcome.hypothesis.splice_plan for outcome in group]
+        ordinal_keys = [
+            plan.ordinal_key if plan is not None else () for plan in plans]
+        probabilities = []
+        for outcome, plan in zip(group, plans):
+            splice_probability = (
+                plan.probability if plan is not None else 1.0)
+            phase_probability = outcome.hypothesis.phase_probability
+            probabilities.append(
+                splice_probability * phase_probability
+                if splice_probability is not None
+                and phase_probability is not None
+                else None)
+        probability = (
+            sum(probabilities)
+            if all(value is not None for value in probabilities) else None)
+        phase_probabilities = [
+            outcome.hypothesis.phase_probability for outcome in group]
+        phase_mass = (
+            sum(phase_probabilities)
+            if all(value is not None for value in phase_probabilities)
+            else None)
+        candidates.append(RealizedEffectCandidate(
+            effect=group[0].effect,
+            outcomes=group,
+            ordinal_key=min(ordinal_keys),
+            probability=probability,
+            phase_mass=phase_mass,
+            first_enumeration_index=min(
+                outcome.hypothesis.enumeration_index for outcome in group)))
+    return tuple(candidates)
+
+
+def order_realized_candidates(candidates, effect_priority_fn):
+    """Order candidates without pretending ordinal rules are probabilities."""
+    candidates = tuple(candidates)
+    all_calibrated = bool(candidates) and all(
+        candidate.probability is not None for candidate in candidates)
+
+    def key(candidate):
+        probability_key = (
+            -candidate.probability if all_calibrated else 0.0)
+        return (
+            probability_key,
+            candidate.ordinal_key,
+            -effect_priority_fn(candidate.effect),
+            candidate.first_enumeration_index,
+        )
+
+    return tuple(sorted(candidates, key=key))