Skip to main content

Tests Coverage Status PyPI

Isovar

Isovar finds the mutant protein sequence that tumor RNA actually encodes around each somatic mutation. Given variant calls (VCF) and aligned tumor RNA-seq reads (BAM), it assembles the reads that carry each mutation into cDNA and translates that cDNA in the reading frames of annotated transcripts.

The protein comes from the reads, not from the reference plus one edit, so it can include nearby variants and splice junctions that the reads show. Where coverage runs out or no reading frame can be established, the result is shorter or empty: Isovar never fills gaps with reference sequence.

Isovar is one of three OpenVax libraries that share this work. Varcode generates transcript hypotheses and predicts coding consequences; Isovar reconstructs RNA-supported sequences and reconciles the evidence; Vaxrank evaluates protein and peptide candidates. See library responsibilities.

Install

pip install isovar

Isovar requires Python 3.11 or later. Reference annotation comes from PyEnsembl; install the Ensembl release that matches your alignments before the first run, for example:

pyensembl install --release 75 --species human

To choose a specific release or use your own GTF, see choosing the reference annotation. Figures and PDF reports are included in the standard installation.

Quick start

from isovar import run_isovar, isovar_results_to_dataframe

isovar_results = run_isovar(
    variants="cancer-mutations.vcf",
    alignment_file="tumor-rna.bam")

for isovar_result in isovar_results:
    # The protein preferred by the context/support policy, or None.
    protein = isovar_result.top_protein_sequence
    if protein is not None:
        # num_alt_fragments: distinct fragments supporting the variant allele.
        print(isovar_result.variant, isovar_result.num_alt_fragments, protein.amino_acids)

# One row per variant.
df = isovar_results_to_dataframe(isovar_results)

With this repository's B16 mouse melanoma test files (tests/data/b16.f10/b16.vcf and b16.combined.sorted.bam, after pyensembl install --release 102 --species mouse), it prints:

Variant(contig='9', start=82927102, ref='G', alt='T', reference_name='GRCm38') 15 GIEDKITKMKVTMVAWDRHDNTVIHAVNNMTLKVWNSYTGQLIHVLMGH
Variant(contig='X', start=8125624, ref='C', alt='A', reference_name='GRCm38') 21 FDVERAAKAAVNKLQGHSAPVLDVIVNCDESLLASSDASGMVIVWRREQ

The file's other two variants have no supporting RNA fragments and no protein. They are still in isovar_results and in df, where they fail the default filters.

Each result holds the RNA evidence at one variant's locus and the proteins assembled from it. Filters mark results but never remove them. See reading and filtering results for every property, table column and filter option.

Isovar logs through the standard logging module under the isovar logger and never configures logging itself; configure it in your application to see progress.

Command line

isovar run \
    --vcf somatic-variants.vcf \
    --bam rnaseq.bam \
    --output isovar-results.csv

The CSV has one row per variant, with the same columns as the DataFrame. isovar --help lists the other commands: table exports, RNA hypotheses, structural variants and fusions, viral and antigen-isoform evidence, proteomes, reports and figures, and audits. The command-line guide describes each one and its output.

Documentation

The documentation index lists every guide in reading order. Start with:

Development

./develop.sh   # editable install with the selected Python
./lint.sh      # ruff
./test.sh      # pytest

./test.sh needs the Ensembl releases that .github/scripts/install_ensembl_data.sh installs (human 75, 87 and 95, mouse 102). See RELEASING.md for version bumps and releases.

The development installer uses python from the active environment. Set PYTHON=/path/to/python ./develop.sh to select an interpreter explicitly; additional arguments are passed to pip.

Citation

Isovar is part of the OpenVax pipeline described in:

Rubinsteyn, A., Kodysh, J., Hodes, I., et al. Computational Pipeline for the PGV-001 Neoantigen Vaccine Trial. Frontiers in Immunology 8, 1807 (2018).

Kodysh, J. & Rubinsteyn, A. OpenVax: An Open-Source Computational Pipeline for Cancer Neoantigen Prediction. Methods Mol. Biol. 2120, 147–160 (2020).

License

Isovar is released under the Apache License 2.0.

Metadata

Release files for isovar 1.91.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for isovar 1.91.3
File Size Uploaded Provenance Actions
isovar-1.91.3.tar.gz 1.6 MB Without provenance Details for isovar-1.91.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for isovar 1.91.3
File Interpreter ABI Platform Actions
isovar-1.91.3-py3-none-any.whl Python 3 none any Details for isovar-1.91.3-py3-none-any.whl

Total release size: 2.2 MB

Release files / isovar-1.91.3.tar.gz

Download URL isovar-1.91.3.tar.gz
Size 1.6 MB
Tags Source
SHA-256 checksum
How to use checksums
9a2f2102c88498a24e2fc3ec1cecb5d8c887a2c7867ca9d4962791a4c446a3e6
BLAKE2b-256 checksum
How to use checksums
9ebce2ea40fc1c734216a26ab3ceeb20d1308beb8c63b0821049b0f36abc9b11
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.6

Release files / isovar-1.91.3-py3-none-any.whl

Download URL isovar-1.91.3-py3-none-any.whl
Size 671.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9e8dd16d8addc59dafce9b4afd252076da5a9896bfc4cedf41679ce6db96669e
BLAKE2b-256 checksum
How to use checksums
2fe07409de25876fd33c35ae44892f1798f8deb4783861250a7e8bedab3e7e9c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.6

Security for isovar 1.91.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.91.3 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page