varcode 9.2.6__tar.gz → 9.2.8__tar.gz

{varcode-9.2.6/varcode.egg-info → varcode-9.2.8}/PKG-INFO

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

{varcode-9.2.6 → varcode-9.2.8}/tests/test_documentation_examples.py

@@ -1,6 +1,7 @@
 """Keep the reader-facing examples executable, using their actual Markdown."""
 
 from pathlib import Path
+import ast
 import re
 import shutil
 
@@ -9,6 +10,7 @@ from pyensembl import cached_release
 
 import varcode
 from varcode import EffectCandidate, StructuralVariant, Variant
+from varcode.effects.effect_classes import HaplotypeEffect
 from varcode.effect_hypotheses import RealizedEffectCandidate
 
 
@@ -46,6 +48,7 @@ def input_directory(tmp_path, monkeypatch):
     ("docs/structural_variants.md", 1),
     ("docs/transforms.md", 1),
     ("docs/germline.md", 1),
+    ("docs/phasing.md", 1),
 ])
 def test_documentation_first_steps(path, count, input_directory):
     namespace = _run(_blocks(path)[:count])
@@ -59,29 +62,95 @@ def test_documentation_first_steps(path, count, input_directory):
         assert (input_directory / "effects.csv").is_file()
     if path == "docs/structural_variants.md":
         assert namespace["variants"][0].is_structural
+    if path == "docs/phasing.md":
+        variants = namespace["phased_variants"]
+        assert namespace["phaser"].in_cis(*variants) is True
+        assert any(isinstance(effect, HaplotypeEffect)
+                   for effect in namespace["effects"])
 
 
 def test_documentation_germline_scenarios():
     namespace = _run(_blocks(
-        "docs/germline.md", "## Concrete example: same codon, three scenarios")[:4])
+        "docs/phasing.md", "## Two variants in one codon")[:4])
     assert namespace["eff_cis"].short_description == "p.S159T"
     assert namespace["eff_trans"].short_description == "p.L159M"
     assert {c.effect.short_description for c in namespace["eff"].candidates} == {
         "p.S159T", "p.L159M"}
 
-    _run(_blocks("docs/germline.md", "## Loss of heterozygosity (LOH)")[:1],
-         namespace)
-    assert any(getattr(effect, "is_loh", False)
-               for effect in namespace["overlap"].effects(germline=namespace["ctx"]))
+    namespace["effects"] = varcode.VariantCollection(
+        [namespace["germline"]]).effects(germline=namespace["ctx"])
+    _run(_blocks("docs/germline.md", "## Loss of heterozygosity (LOH)")[:1], namespace)
+    assert any(getattr(effect, "is_loh", False) for effect in namespace["effects"])
 
     validation = _blocks("docs/germline.md", "## Cross-VCF build mismatch")[:1]
+    namespace["somatic_variants"] = varcode.VariantCollection([namespace["somatic"]])
+    namespace["germline_ctx"] = namespace["ctx"]
     _run(validation, namespace)
-    namespace["ctx"] = varcode.GermlineContext.from_variants(
+    namespace["germline_ctx"] = varcode.GermlineContext.from_variants(
         [namespace["germline"]], reference_name="GRCh37")
     with pytest.raises(varcode.GenomeBuildMismatchError):
         _run(validation, namespace)
 
 
+def test_documentation_germline_with_vcf_phase(input_directory):
+    namespace = _run(_blocks("docs/germline.md")[:1])
+    _run(_blocks("docs/phasing.md", "## Phased VCF")[:1], namespace)
+    namespace["rna"] = varcode.NullRNAEvidenceResolver()
+    _run(_blocks("docs/phasing.md", "## Combining evidence")[:1], namespace)
+    cftr = [effect for effect in namespace["effects"]
+            if effect.transcript_id == "ENST00000003084"]
+    assert len(cftr) == 1
+    assert cftr[0].short_description == "p.S159T"
+
+
+def test_documentation_fusion_protein_candidates(capsys):
+    genome = cached_release(95)
+    transcript = genome.transcript_by_id("ENST00000538197")
+    variant = StructuralVariant(
+        "4", 15012987, "BND", alt="N[4:2664478[",
+        mate_contig="4", mate_start=2664478, genome=genome)
+    namespace = {"effect": variant.effect_on_transcript(transcript)}
+    _run(_blocks("docs/structural_variants.md", "## Fusion protein candidates")[:1], namespace)
+    output = capsys.readouterr().out
+    assert "ENST00000324666" in output
+    assert "ENST00000637812" in output
+
+
+def test_documentation_effect_families_keep_all_classes():
+    source = ast.parse((ROOT / "varcode/effects/effect_classes.py").read_text())
+    classes = {node.name for node in source.body if isinstance(node, ast.ClassDef)}
+    guide = (ROOT / "docs/effect_types.md").read_text()
+    documented = re.findall(r"^::: varcode.effects.effect_classes\.(\w+)$", guide, re.M)
+    assert set(documented) == classes
+    assert len(documented) == len(classes)
+    assert "::: varcode.SpliceOutcomeSet" in guide
+
+
+@pytest.mark.parametrize("path,anchor,destination", [
+    ("structural_variants.md", "alleles-coordinates-and-exports", "sv_reference.md"),
+    ("structural_variants.md", "importing-observed-rna-structures", "rna_structures.md"),
+    ("germline.md", "concrete-example-same-codon-three-scenarios", "phasing.md"),
+    ("germline.md", "known-deletion-haplotypes-in-rna-alignments", "phasing.md"),
+    ("api.md", "varcode.Variant.effects", "api_variants.md"),
+    ("api.md", "varcode.MutantTranscript", "api_rna.md"),
+    ("api.md", "varcode.VCFPhaseResolver", "api_phasing.md"),
+])
+def test_documentation_topic_links_preserve_old_fragments(path, anchor, destination):
+    guide = (ROOT / "docs" / path).read_text()
+    row = next(line for line in guide.splitlines() if f'id="{anchor}"' in line)
+    assert f"]({destination}" in row
+    assert (ROOT / "docs" / destination).is_file()
+
+
+def test_documentation_api_objects_have_one_heading():
+    topics = list((ROOT / "docs").glob("api_*.md"))
+    assert len(topics) == 5
+    for topic in topics:
+        text = topic.read_text()
+        assert "::: varcode." in text
+        assert not re.search(r"^### `varcode\.", text, re.M)
+
+
 def test_documentation_splice_accessors():
     namespace = _run(_blocks("docs/splice_variants.md"))
     assert isinstance(namespace["splice_set"], varcode.SpliceOutcomeSet)

varcode-9.2.8/tests/test_fusion_partner_candidates.py

@@ -0,0 +1,184 @@
+"""Fusion proteins must not depend on discarding all but the first isoform."""
+
+from types import SimpleNamespace
+
+import pytest
+from pyensembl import cached_release
+
+from varcode import EffectCandidate, StructuralVariant
+from varcode.effects import GeneFusion, LargeDeletion, TranslocationToIntergenic
+from varcode.effects import structural
+
+
+@pytest.fixture
+def fusion_case(monkeypatch):
+    genome = cached_release(95)
+    transcript = genome.transcript_by_id("ENST00000538197")  # CPEB2, forward
+    variant = StructuralVariant(
+        "4", 15012987, "BND", alt="N[4:2664478[",
+        mate_contig="4", mate_start=2664478, genome=genome)
+    # These tests isolate junction/isoform enumeration. Dedicated existing
+    # tests cover the splice and cryptic layers added after it.
+    monkeypatch.setattr(structural, "_enumerate_and_attach_cryptics", lambda *args: None)
+    monkeypatch.setattr(structural, "_enumerate_and_attach_splice_outcomes", lambda *args: None)
+    return genome, transcript, variant
+
+
+def _fusions(effect):
+    return [candidate.effect for candidate in effect.candidates
+            if isinstance(candidate.effect, GeneFusion)]
+
+
+def test_audited_cpeb2_fam193a_proteins_are_both_candidates(fusion_case):
+    genome, transcript, variant = fusion_case
+    effect = variant.effect_on_transcript(transcript)
+    candidates = _fusions(effect)
+    expected = [t.id for t in genome.transcripts_at_locus("4", 2664478, 2664478)
+                if t.is_protein_coding and t.gene_name == "FAM193A" and t.strand == "+"]
+    assert [c.partner_transcript.id for c in candidates] == expected
+    assert len(candidates) == 7
+    assert candidates[0] is effect  # existing primary remains compatible
+    proteins = {c.partner_transcript.id: c.mutant_protein_sequence for c in candidates}
+    assert len(proteins["ENST00000324666"]) == 1541
+    assert len(proteins["ENST00000637812"]) == 1500
+    assert proteins["ENST00000324666"] != proteins["ENST00000637812"]
+    partner = genome.transcript_by_id("ENST00000637812")
+    assert proteins[partner.id] == transcript.protein_sequence[:678] + partner.protein_sequence[693:]
+    for candidate in candidates:
+        assert candidate.transcript is transcript
+        assert candidate.five_prime_transcript is transcript
+        assert candidate.three_prime_transcript is candidate.partner_transcript
+        model = candidate.mutant_transcript
+        assert model.cdna_sequence == "".join(
+            segment.source.sequence[segment.start:segment.end]
+            for segment in model.reference_segments)
+
+
+def test_same_transcript_pair_has_same_protein_from_either_end(fusion_case):
+    genome, transcript, variant = fusion_case
+    partner = genome.transcript_by_id("ENST00000637812")
+    mate = StructuralVariant(
+        "4", 2664478, "BND", alt="]4:15012987]N",
+        mate_contig="4", mate_start=15012987, genome=genome)
+    from_five = next(c for c in _fusions(variant.effect_on_transcript(transcript))
+                     if c.partner_transcript.id == partner.id)
+    from_three = next(c for c in _fusions(mate.effect_on_transcript(partner))
+                      if c.partner_transcript.id == transcript.id)
+    assert from_five.mutant_protein_sequence == from_three.mutant_protein_sequence
+    assert from_three.five_prime_transcript.id == transcript.id
+    assert from_three.three_prime_transcript.id == partner.id
+
+
+class _Isoform:
+    """Reuse a reference transcript while varying only ID or available sequence."""
+    def __init__(self, transcript, name, sequence):
+        self._transcript = transcript
+        self.id = name
+        self.sequence = sequence
+
+    def __getattr__(self, name):
+        return getattr(self._transcript, name)
+
+
+def test_large_isoform_set_is_not_capped_or_merged_by_protein(fusion_case, monkeypatch):
+    genome, transcript, variant = fusion_case
+    partner = genome.transcript_by_id("ENST00000637812")
+    partners = [_Isoform(partner, "isoform_%03d" % i, partner.sequence) for i in range(257)]
+    monkeypatch.setattr(structural, "_coding_transcripts_at", lambda *args: partners)
+    candidates = _fusions(variant.effect_on_transcript(transcript))
+    assert [c.partner_transcript.id for c in candidates] == [p.id for p in partners]
+    assert len({c.mutant_protein_sequence for c in candidates}) == 1
+
+
+def test_duplicate_junction_and_partner_records_are_not_repeated(fusion_case, monkeypatch):
+    genome, transcript, variant = fusion_case
+    partner = genome.transcript_by_id("ENST00000637812")
+    monkeypatch.setattr(structural, "_coding_transcripts_at", lambda *args: [partner, partner])
+    duplicate = SimpleNamespace(junctions=variant.junctions * 2)
+    effect = structural._fusion_across_junction(duplicate, transcript, None)
+    assert len(_fusions(effect)) == 1
+
+
+@pytest.mark.parametrize("sequence", [None, ""])
+def test_missing_partner_sequence_keeps_an_unresolved_candidate(fusion_case, monkeypatch, sequence):
+    genome, transcript, variant = fusion_case
+    partner = genome.transcript_by_id("ENST00000637812")
+    missing = _Isoform(partner, "missing_sequence", sequence)
+    monkeypatch.setattr(structural, "_coding_transcripts_at", lambda *args: [partner, missing])
+    candidates = _fusions(variant.effect_on_transcript(transcript))
+    assert len(candidates) == 2
+    assert candidates[0].mutant_protein_sequence is not None
+    assert candidates[1].partner_transcript is missing
+    assert candidates[1].mutant_transcript is None
+    assert candidates[1].mutant_protein_sequence is None
+
+
+def test_supplied_assembly_and_external_candidates_are_preserved(fusion_case):
+    genome, transcript, variant = fusion_case
+    variant.alt_assembly = "ATG" + "GCC" * 20 + "TAA"
+    effect = variant.effect_on_transcript(transcript)
+    candidates = _fusions(effect)
+    assert len(candidates) == 7
+    assert all(c.mutant_transcript.cdna_sequence == variant.alt_assembly for c in candidates)
+    assert all(c.mutant_transcript.evidence == {"source": "alt_assembly"} for c in candidates)
+    observed = EffectCandidate(candidates[-1], source="rna", evidence={"read_count": 4})
+    effect._extra_candidates = (observed,)
+    assert effect.candidates[-1] is observed
+    assert len(effect.candidates) == 8
+
+
+def test_opposite_strand_partner_isoforms_are_all_kept(monkeypatch):
+    genome = cached_release(81)
+    transcript = genome.transcript_by_id("ENST00000003084")  # CFTR, +
+    variant = StructuralVariant(
+        "7", 117485000, "BND", alt="N]17:43120000]",
+        mate_contig="17", mate_start=43120000, genome=genome)
+    monkeypatch.setattr(structural, "_enumerate_and_attach_cryptics", lambda *args: None)
+    effect = variant.effect_on_transcript(transcript)
+    expected = {t.id for t in genome.transcripts_at_locus("17", 43120000, 43120000)
+                if t.is_protein_coding and t.strand == "-"}
+    assert {c.partner_transcript.id for c in _fusions(effect)} == expected
+    assert len(expected) > 1
+
+
+def test_same_role_join_still_has_no_fusion_candidates(fusion_case):
+    genome, transcript, _ = fusion_case
+    variant = StructuralVariant(
+        "4", 15012987, "BND", alt="N]4:2664478]",
+        mate_contig="4", mate_start=2664478, genome=genome)
+    effect = variant.effect_on_transcript(transcript)
+    assert isinstance(effect, TranslocationToIntergenic)
+    assert not _fusions(effect)
+
+
+def test_span_effect_is_retained_after_all_fusion_partners(fusion_case):
+    genome, _, _ = fusion_case
+    tmprss2 = max((t for t in genome.genes_by_name("TMPRSS2")[0].transcripts if t.is_protein_coding),
+                 key=lambda t: len(t.sequence or ""))
+    erg = max((t for t in genome.genes_by_name("ERG")[0].transcripts if t.is_protein_coding),
+              key=lambda t: len(t.sequence or ""))
+    def midpoint(transcript, exon):
+        left, right = transcript.exons[exon - 1:exon + 1]
+        return (min(left.end, right.end) + max(left.start, right.start)) // 2
+    variant = StructuralVariant("21", midpoint(erg, 3), "DEL",
+                                end=midpoint(tmprss2, 2) - 1, genome=genome)
+    effect = variant.effect_on_transcript(tmprss2)
+    assert len(_fusions(effect)) > 1
+    assert isinstance(effect.candidates[-1].effect, LargeDeletion)
+    assert effect.candidates[-1].effect.affected_exons
+
+
+def test_inversion_keeps_both_junction_directions_with_local_five_prime_first(fusion_case):
+    genome, _, _ = fusion_case
+    transcript = genome.transcript_by_id("ENST00000003084")  # CFTR, +
+    partner_gene = genome.genes_by_name("CTTNBP2")[0]  # downstream, -
+    far = (max(partner_gene.start, transcript.gene.end + 1) + partner_gene.end) // 2
+    variant = StructuralVariant("7", 117485000, "INV", end=far, genome=genome)
+    effect = variant.effect_on_transcript(transcript)
+    candidates = _fusions(effect)
+    assert effect.five_prime_transcript.id == transcript.id
+    directions = {(c.five_prime_transcript.gene_name, c.three_prime_transcript.gene_name)
+                  for c in candidates}
+    assert directions == {("CFTR", "CTTNBP2"), ("CTTNBP2", "CFTR")}
+    keys = [(c.five_prime_transcript.id, c.three_prime_transcript.id) for c in candidates]
+    assert len(keys) == len(set(keys))

{varcode-9.2.6 → varcode-9.2.8}/tests/test_nonlocal_sv_transcripts.py

@@ -16,7 +16,7 @@ def transcript(request):
 @pytest.fixture(autouse=True)
 def no_optional_candidates(monkeypatch):
     # Isolate the span fallback; fusion preservation also has real esvee tests.
-    monkeypatch.setattr(structural, "_fusion_partner", lambda *args: None)
+    monkeypatch.setattr(structural, "_fusion_partners", lambda *args: ())
     monkeypatch.setattr(structural, "_enumerate_and_attach_cryptics", lambda *args: None)
     monkeypatch.setattr(structural, "_enumerate_and_attach_splice_outcomes", lambda *args: None)
 

{varcode-9.2.6 → varcode-9.2.8}/varcode/effects/effect_classes.py

@@ -1549,6 +1549,12 @@ class GeneFusion(StructuralVariantEffect):
     produce it, and so do deletions, duplications and inversions with
     one end in each gene.
 
+    The default annotator retains every compatible annotated partner isoform
+    and junction in :attr:`candidates`, with no count cap. The first is the
+    historical primary; producer order is not a probability ranking. Distinct
+    transcript pairs remain separate even when their proteins match. Missing
+    sequence leaves that candidate's transcript/protein unresolved.
+
     ``transcript`` is the transcript being annotated and
     ``partner_transcript`` the other one; ``five_prime_transcript``
     and ``three_prime_transcript`` say which is which (by default

{varcode-9.2.6 → varcode-9.2.8}/varcode/effects/structural.py

@@ -473,8 +473,14 @@ def _build_fusion_mutant_transcript(
     segments. The annotator assigns the 5' / 3' roles from breakend
     orientation and strand before calling this.
     """
-    five_prime_cdna = str(five_prime_transcript.sequence)
-    three_prime_cdna = str(three_prime_transcript.sequence)
+    five_prime_cdna = five_prime_transcript.sequence
+    three_prime_cdna = three_prime_transcript.sequence
+    if not five_prime_cdna or not three_prime_cdna:
+        # The partner is still a candidate when sequence is unavailable.
+        # In particular, str(None) is not an observed or predicted cDNA.
+        return None
+    five_prime_cdna = str(five_prime_cdna)
+    three_prime_cdna = str(three_prime_cdna)
     five_prime_end = _cdna_cut(
         five_prime_transcript, five_prime_position, True)
     three_prime_start = _cdna_cut(
@@ -798,8 +804,11 @@ def _intronic_or_intergenic(variant, transcript):
 
 
 def _fusion_across_junction(variant, transcript, assembly):
-    """The :class:`GeneFusion` ``transcript`` forms at one of
-    ``variant``'s junctions, or ``None``.
+    """Fusion candidates across all compatible junctions and partner isoforms.
+
+    Return the first :class:`GeneFusion`, carrying all other fusions in its
+    primary candidates, or ``None``. Annotation order is not a likelihood
+    ranking; no compatible partner is discarded by a candidate-count limit.
 
     A junction end belongs to this transcript when the transcript
     spans it and the transcript's *gene* doesn't span the other
@@ -827,34 +836,42 @@ def _fusion_across_junction(variant, transcript, assembly):
                 continue
             ends.append((near, far))
 
+    fusions = []
+    seen = set()
     for near, far in sorted(
             ends, key=lambda pair: not keeps_five_prime(pair[0])):
         five_prime = keeps_five_prime(near)
-        partner = _fusion_partner(
-            variant, transcript, near, far, five_prime)
-        if partner is None:
-            continue
-        if five_prime:
-            five, five_position = transcript, near.position
-            three, three_position = partner, far.position
-        else:
-            five, five_position = partner, far.position
-            three, three_position = transcript, near.position
-        return GeneFusion(
-            variant=variant,
-            transcript=transcript,
-            partner_transcript=partner,
-            five_prime_transcript=five,
-            three_prime_transcript=three,
-            mutant_transcript=assembly or _build_fusion_mutant_transcript(
-                transcript, five, five_position, three, three_position))
-    return None
+        for partner in _fusion_partners(
+                variant, transcript, near, far, five_prime):
+            key = (near, far, partner.id)
+            if key in seen:
+                continue
+            seen.add(key)
+            if five_prime:
+                five, five_position = transcript, near.position
+                three, three_position = partner, far.position
+            else:
+                five, five_position = partner, far.position
+                three, three_position = transcript, near.position
+            fusions.append(GeneFusion(
+                variant=variant,
+                transcript=transcript,
+                partner_transcript=partner,
+                five_prime_transcript=five,
+                three_prime_transcript=three,
+                mutant_transcript=assembly or _build_fusion_mutant_transcript(
+                    transcript, five, five_position, three, three_position)))
+    if not fusions:
+        return None
+    primary = fusions[0]
+    primary._attach_primary_effects(fusions[1:])
+    return primary
 
 
-def _fusion_partner(
+def _fusion_partners(
         variant, transcript, near, far, transcript_is_five_prime):
-    """The protein-coding transcript at ``far`` that fuses with
-    ``transcript``, or ``None``.
+    """Yield every protein-coding transcript at ``far`` that fuses with
+    ``transcript``, in annotation order.
 
     A partner is in another gene, keeps the end opposite to
     ``transcript``'s, and — like ``transcript`` — belongs to a gene
@@ -870,8 +887,7 @@ def _fusion_partner(
         if far.keeps is None or (
                 _retains_five_prime_end(candidate, far.keeps)
                 != transcript_is_five_prime):
-            return candidate
-    return None
+            yield candidate
 
 
 def _coding_transcripts_at(variant, contig, position):

varcode-9.2.8/varcode/version.py

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

{varcode-9.2.6 → varcode-9.2.8/varcode.egg-info}/PKG-INFO

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

{varcode-9.2.6 → varcode-9.2.8}/varcode.egg-info/SOURCES.txt

@@ -32,6 +32,7 @@ tests/test_exonic_splice_site.py
 tests/test_fast_path.py
 tests/test_frameshift_cterminus_regression.py
 tests/test_frameshift_helpers.py
+tests/test_fusion_partner_candidates.py
 tests/test_genome_contig_validation.py
 tests/test_genome_sequence.py
 tests/test_genomic_layout.py

varcode-9.2.6/varcode/version.py

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