varcode 9.2.4__tar.gz → 9.2.6__tar.gz

varcode-9.2.6/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: varcode
+Version: 9.2.6
+Summary: Variant annotation in Python
+Author-email: Alex Rubinsteyn <alex.rubinsteyn@unc.edu>
+Project-URL: Homepage, https://github.com/openvax/varcode
+Project-URL: Bug Tracker, https://github.com/openvax/varcode/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3.0.0,>=2.0.0
+Requires-Dist: pandas<3.0.0,>=2.0.0
+Requires-Dist: pyensembl>=2.6.4
+Requires-Dist: memoized_property>=1.0.2
+Requires-Dist: serializable>=1.1.0
+Requires-Dist: sercol>=0.1.4
+Provides-Extra: rna
+Requires-Dist: pysam>=0.21; extra == "rna"
+Dynamic: license-file
+
+[![Tests](https://github.com/openvax/varcode/actions/workflows/tests.yml/badge.svg)](https://github.com/openvax/varcode/actions/workflows/tests.yml)
+[![Coverage Status](https://coveralls.io/repos/openvax/varcode/badge.svg?branch=main&service=github)](https://coveralls.io/github/openvax/varcode?branch=main)
+[![PyPI](https://img.shields.io/pypi/v/varcode.svg?maxAge=1000)](https://pypi.python.org/pypi/varcode/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/varcode.svg)](https://pypistats.org/packages/varcode)
+
+# Varcode
+
+Varcode helps you work with genomic variants in Python and predict their effects
+on genes, transcripts, and protein sequences.
+
+Load variants from VCF or MAF files, annotate them, and inspect the results.
+The same interface handles small variants and structural variants; optional
+germline, phasing, and RNA evidence can refine predictions.
+
+## Installation
+
+Requires Python 3.9 or later:
+
+```bash
+pip install varcode
+pyensembl install --release 81 --species human
+```
+
+The second command downloads the annotation and transcript sequences for the
+GRCh38 example below. Release 81 is pinned for reproducibility, not a requirement
+to use that release for your own data. Choose an annotation matching your
+input's genome build; see [reference setup](https://openvax.github.io/varcode/getting_started/#reference-data).
+
+<a id="example"></a>
+
+## Quick start
+
+Predict the effect of a single GRCh38 variant on a CFTR transcript:
+
+```python
+from varcode import Variant
+
+variant = Variant("7", 117_531_100, "T", "A", genome=81)
+transcript = variant.genome.transcript_by_id("ENST00000003084")
+effect = variant.effect_on_transcript(transcript)
+
+print(effect.short_description)  # p.L159M
+protein = effect.mutant_protein_sequence
+```
+
+For a VCF called against the same genome build:
+
+```python
+from varcode import load_vcf
+
+variants = load_vcf("variants.vcf", genome=81)
+effects = variants.effects()
+for variant, effect in effects.top_priority_effect_per_variant().items():
+    print(variant.short_description, effect.short_description)
+```
+
+A variant can affect several transcripts. Priority is a summary of predicted
+consequence, not proof of expression or pathogenicity. A protein sequence may be
+unavailable for unresolved effects.
+
+<a id="further-reading"></a>
+
+## Learn more
+
+Start with the [getting-started guide](https://openvax.github.io/varcode/getting_started/)
+for file loading, result access, and saving a table. Then follow the
+[task guides](https://openvax.github.io/varcode/#find-your-next-task) for sample
+filtering, structural variants, phasing, and RNA evidence.
+
+<a id="effect-types"></a>
+<a id="coordinate-system"></a>
+
+Detailed [effect types](https://openvax.github.io/varcode/effect_types/),
+[coordinate conventions](https://openvax.github.io/varcode/getting_started/#coordinate-conventions),
+and the [API reference](https://openvax.github.io/varcode/api/) live in the docs.
+
+For bugs or questions, [open an issue](https://github.com/openvax/varcode/issues).
+Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md) and the
+[changelog](CHANGELOG.md).

varcode-9.2.6/README.md

@@ -0,0 +1,79 @@
+[![Tests](https://github.com/openvax/varcode/actions/workflows/tests.yml/badge.svg)](https://github.com/openvax/varcode/actions/workflows/tests.yml)
+[![Coverage Status](https://coveralls.io/repos/openvax/varcode/badge.svg?branch=main&service=github)](https://coveralls.io/github/openvax/varcode?branch=main)
+[![PyPI](https://img.shields.io/pypi/v/varcode.svg?maxAge=1000)](https://pypi.python.org/pypi/varcode/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/varcode.svg)](https://pypistats.org/packages/varcode)
+
+# Varcode
+
+Varcode helps you work with genomic variants in Python and predict their effects
+on genes, transcripts, and protein sequences.
+
+Load variants from VCF or MAF files, annotate them, and inspect the results.
+The same interface handles small variants and structural variants; optional
+germline, phasing, and RNA evidence can refine predictions.
+
+## Installation
+
+Requires Python 3.9 or later:
+
+```bash
+pip install varcode
+pyensembl install --release 81 --species human
+```
+
+The second command downloads the annotation and transcript sequences for the
+GRCh38 example below. Release 81 is pinned for reproducibility, not a requirement
+to use that release for your own data. Choose an annotation matching your
+input's genome build; see [reference setup](https://openvax.github.io/varcode/getting_started/#reference-data).
+
+<a id="example"></a>
+
+## Quick start
+
+Predict the effect of a single GRCh38 variant on a CFTR transcript:
+
+```python
+from varcode import Variant
+
+variant = Variant("7", 117_531_100, "T", "A", genome=81)
+transcript = variant.genome.transcript_by_id("ENST00000003084")
+effect = variant.effect_on_transcript(transcript)
+
+print(effect.short_description)  # p.L159M
+protein = effect.mutant_protein_sequence
+```
+
+For a VCF called against the same genome build:
+
+```python
+from varcode import load_vcf
+
+variants = load_vcf("variants.vcf", genome=81)
+effects = variants.effects()
+for variant, effect in effects.top_priority_effect_per_variant().items():
+    print(variant.short_description, effect.short_description)
+```
+
+A variant can affect several transcripts. Priority is a summary of predicted
+consequence, not proof of expression or pathogenicity. A protein sequence may be
+unavailable for unresolved effects.
+
+<a id="further-reading"></a>
+
+## Learn more
+
+Start with the [getting-started guide](https://openvax.github.io/varcode/getting_started/)
+for file loading, result access, and saving a table. Then follow the
+[task guides](https://openvax.github.io/varcode/#find-your-next-task) for sample
+filtering, structural variants, phasing, and RNA evidence.
+
+<a id="effect-types"></a>
+<a id="coordinate-system"></a>
+
+Detailed [effect types](https://openvax.github.io/varcode/effect_types/),
+[coordinate conventions](https://openvax.github.io/varcode/getting_started/#coordinate-conventions),
+and the [API reference](https://openvax.github.io/varcode/api/) live in the docs.
+
+For bugs or questions, [open an issue](https://github.com/openvax/varcode/issues).
+Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md) and the
+[changelog](CHANGELOG.md).

varcode-9.2.6/tests/test_documentation_examples.py

@@ -0,0 +1,149 @@
+"""Keep the reader-facing examples executable, using their actual Markdown."""
+
+from pathlib import Path
+import re
+import shutil
+
+import pytest
+from pyensembl import cached_release
+
+import varcode
+from varcode import EffectCandidate, StructuralVariant, Variant
+from varcode.effect_hypotheses import RealizedEffectCandidate
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def _blocks(path, heading=None):
+    text = (ROOT / path).read_text()
+    if heading is not None:
+        text = text.split(heading + "\n", 1)[1]
+    return re.findall(r"```python\n(.*?)```", text, re.S)
+
+
+def _run(blocks, namespace=None):
+    namespace = {} if namespace is None else namespace
+    for block in blocks:
+        exec(compile(block, "documentation example", "exec"), namespace)
+    return namespace
+
+
+@pytest.fixture
+def input_directory(tmp_path, monkeypatch):
+    for fixture in (ROOT / "tests/data/documentation").glob("*.vcf"):
+        shutil.copy(fixture, tmp_path / fixture.name)
+    shutil.copy(tmp_path / "variants.vcf", tmp_path / "tumor.vcf")
+    monkeypatch.chdir(tmp_path)
+    return tmp_path
+
+
+@pytest.mark.parametrize("path,count", [
+    ("README.md", 2),
+    ("docs/getting_started.md", 4),
+    ("docs/index.md", 1),
+    ("docs/effect_annotation.md", 3),
+    ("docs/structural_variants.md", 1),
+    ("docs/transforms.md", 1),
+    ("docs/germline.md", 1),
+])
+def test_documentation_first_steps(path, count, input_directory):
+    namespace = _run(_blocks(path)[:count])
+    if path == "docs/transforms.md":
+        assert len(namespace["paired"]) == len(namespace["normalized"]) == 1
+    else:
+        assert len(namespace["effects"]) > 0
+    if path in ("README.md", "docs/getting_started.md"):
+        assert namespace["protein"][158] == "M"
+    if path == "docs/getting_started.md":
+        assert (input_directory / "effects.csv").is_file()
+    if path == "docs/structural_variants.md":
+        assert namespace["variants"][0].is_structural
+
+
+def test_documentation_germline_scenarios():
+    namespace = _run(_blocks(
+        "docs/germline.md", "## Concrete example: same codon, three scenarios")[: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"]))
+
+    validation = _blocks("docs/germline.md", "## Cross-VCF build mismatch")[:1]
+    _run(validation, namespace)
+    namespace["ctx"] = varcode.GermlineContext.from_variants(
+        [namespace["germline"]], reference_name="GRCh37")
+    with pytest.raises(varcode.GenomeBuildMismatchError):
+        _run(validation, namespace)
+
+
+def test_documentation_splice_accessors():
+    namespace = _run(_blocks("docs/splice_variants.md"))
+    assert isinstance(namespace["splice_set"], varcode.SpliceOutcomeSet)
+    assert namespace["coding"] is not None
+    assert namespace["preferred"] is not None
+
+
+def test_documentation_moved_sections_keep_incoming_links():
+    guide = (ROOT / "docs/effect_annotation.md").read_text()
+    destinations = {
+        "splice-disrupting-variants": "splice_variants.md",
+        "how-it-composes": "transcript_models.md",
+        "annotator-selection": "experimental_annotators.md",
+        "writing-an-annotator": "annotator_contract.md",
+        "provenance": "csv.md#annotation-provenance",
+    }
+    for anchor, destination in destinations.items():
+        # Old fragment URLs land beside a link to the relocated content.
+        row = next(line for line in guide.splitlines() if f'id="{anchor}"' in line)
+        assert f"]({destination})" in row
+        assert (ROOT / "docs" / destination.split("#")[0]).is_file()
+
+
+def test_documentation_custom_annotator_adapter():
+    namespace = _run(_blocks("docs/annotator_contract.md")[:1])
+    adapter = namespace["MyAnnotator"]
+    variant = Variant("7", 117531100, "T", "A", genome=81)
+    transcript = variant.genome.transcript_by_id("ENST00000003084")
+    effect = variant.effect_on_transcript(transcript)
+    supported = adapter(lambda variant, transcript: effect)
+    unsupported = adapter(lambda variant, transcript: None)
+    assert supported.annotate_on_transcript(variant, transcript) is effect
+    assert unsupported.annotate_on_transcript(variant, transcript) is NotImplemented
+
+
+@pytest.mark.parametrize("kind", ["point", "BND", "CNV"])
+def test_documentation_experimental_result_access(kind):
+    genome = cached_release(81)
+    transcript = genome.transcript_by_id("ENST00000003084")
+    if kind == "point":
+        variant = Variant("7", 117531100, "T", "A", genome)
+    elif kind == "BND":
+        variant = StructuralVariant(
+            "7", transcript.start + 50, "BND", alt="N]22:15500000]",
+            mate_contig="22", mate_start=15500000, genome=genome)
+    else:
+        variant = StructuralVariant(
+            "7", transcript.start + 50, "CNV", end=transcript.start + 100,
+            genome=genome)
+    namespace = dict(varcode=varcode, variant=variant, transcript=transcript)
+    advanced_blocks = _blocks("docs/experimental_annotators.md")
+    assert "comparison =" in advanced_blocks[0]
+    assert "candidate.outcomes" in advanced_blocks[1]
+    _run(advanced_blocks[:2], namespace)
+    _run(_blocks("docs/transcript_models.md"), namespace)
+    candidates = getattr(namespace["experimental"], "candidates", ())
+    if kind == "point":
+        assert candidates and all(isinstance(c, RealizedEffectCandidate)
+                                  for c in candidates)
+        assert namespace["protein"][158] == "M"
+    elif kind == "BND":
+        assert candidates and all(isinstance(c, EffectCandidate) for c in candidates)
+    else:
+        assert not candidates
+        assert isinstance(namespace["experimental"], varcode.Unresolved)

{varcode-9.2.4 → varcode-9.2.6}/varcode/variant.py

@@ -464,7 +464,7 @@ class Variant(Serializable):
             :func:`varcode.use_annotator`). String names are resolved
             against the registry. See openvax/varcode#271.
 
-        phase_resolver : PhaseResolver or None
+        phase_resolver : resolver object or None
             Optional phase-evidence source (typically a
             :class:`~varcode.phasing.MolecularPhaseResolver` wrapping an
             upstream RNA-phasing tool, or

{varcode-9.2.4 → varcode-9.2.6}/varcode/variant_collection.py

@@ -140,7 +140,7 @@ class VariantCollection(Collection):
             the collection. See :meth:`Variant.effects` and
             openvax/varcode#271.
 
-        phase_resolver : PhaseResolver or None
+        phase_resolver : resolver object or None
             Optional phase-evidence source (e.g. a
             :class:`~varcode.phasing.MolecularPhaseResolver` wrapping an
             upstream RNA-phasing tool, or

varcode-9.2.6/varcode/version.py

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

varcode-9.2.6/varcode.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: varcode
+Version: 9.2.6
+Summary: Variant annotation in Python
+Author-email: Alex Rubinsteyn <alex.rubinsteyn@unc.edu>
+Project-URL: Homepage, https://github.com/openvax/varcode
+Project-URL: Bug Tracker, https://github.com/openvax/varcode/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3.0.0,>=2.0.0
+Requires-Dist: pandas<3.0.0,>=2.0.0
+Requires-Dist: pyensembl>=2.6.4
+Requires-Dist: memoized_property>=1.0.2
+Requires-Dist: serializable>=1.1.0
+Requires-Dist: sercol>=0.1.4
+Provides-Extra: rna
+Requires-Dist: pysam>=0.21; extra == "rna"
+Dynamic: license-file
+
+[![Tests](https://github.com/openvax/varcode/actions/workflows/tests.yml/badge.svg)](https://github.com/openvax/varcode/actions/workflows/tests.yml)
+[![Coverage Status](https://coveralls.io/repos/openvax/varcode/badge.svg?branch=main&service=github)](https://coveralls.io/github/openvax/varcode?branch=main)
+[![PyPI](https://img.shields.io/pypi/v/varcode.svg?maxAge=1000)](https://pypi.python.org/pypi/varcode/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/varcode.svg)](https://pypistats.org/packages/varcode)
+
+# Varcode
+
+Varcode helps you work with genomic variants in Python and predict their effects
+on genes, transcripts, and protein sequences.
+
+Load variants from VCF or MAF files, annotate them, and inspect the results.
+The same interface handles small variants and structural variants; optional
+germline, phasing, and RNA evidence can refine predictions.
+
+## Installation
+
+Requires Python 3.9 or later:
+
+```bash
+pip install varcode
+pyensembl install --release 81 --species human
+```
+
+The second command downloads the annotation and transcript sequences for the
+GRCh38 example below. Release 81 is pinned for reproducibility, not a requirement
+to use that release for your own data. Choose an annotation matching your
+input's genome build; see [reference setup](https://openvax.github.io/varcode/getting_started/#reference-data).
+
+<a id="example"></a>
+
+## Quick start
+
+Predict the effect of a single GRCh38 variant on a CFTR transcript:
+
+```python
+from varcode import Variant
+
+variant = Variant("7", 117_531_100, "T", "A", genome=81)
+transcript = variant.genome.transcript_by_id("ENST00000003084")
+effect = variant.effect_on_transcript(transcript)
+
+print(effect.short_description)  # p.L159M
+protein = effect.mutant_protein_sequence
+```
+
+For a VCF called against the same genome build:
+
+```python
+from varcode import load_vcf
+
+variants = load_vcf("variants.vcf", genome=81)
+effects = variants.effects()
+for variant, effect in effects.top_priority_effect_per_variant().items():
+    print(variant.short_description, effect.short_description)
+```
+
+A variant can affect several transcripts. Priority is a summary of predicted
+consequence, not proof of expression or pathogenicity. A protein sequence may be
+unavailable for unresolved effects.
+
+<a id="further-reading"></a>
+
+## Learn more
+
+Start with the [getting-started guide](https://openvax.github.io/varcode/getting_started/)
+for file loading, result access, and saving a table. Then follow the
+[task guides](https://openvax.github.io/varcode/#find-your-next-task) for sample
+filtering, structural variants, phasing, and RNA evidence.
+
+<a id="effect-types"></a>
+<a id="coordinate-system"></a>
+
+Detailed [effect types](https://openvax.github.io/varcode/effect_types/),
+[coordinate conventions](https://openvax.github.io/varcode/getting_started/#coordinate-conventions),
+and the [API reference](https://openvax.github.io/varcode/api/) live in the docs.
+
+For bugs or questions, [open an issue](https://github.com/openvax/varcode/issues).
+Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md) and the
+[changelog](CHANGELOG.md).

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

@@ -18,6 +18,7 @@ tests/test_cryptic_exons.py
 tests/test_csv_roundtrip.py
 tests/test_dbnsfp_validation.py
 tests/test_default_structural_helpers.py
+tests/test_documentation_examples.py
 tests/test_effect_annotation_errors.py
 tests/test_effect_candidates.py
 tests/test_effect_classes.py