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 uv
./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.

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.88.0

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.88.0
File Size Uploaded Provenance Actions
isovar-1.88.0.tar.gz 12.8 MB Without provenance Details for isovar-1.88.0.tar.gz

Built distribution (wheel)

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

Total release size: 24.6 MB

Release files / isovar-1.88.0.tar.gz

Download URL isovar-1.88.0.tar.gz
Size 12.8 MB
Tags Source
SHA-256 checksum
How to use checksums
3be4ff08445741ef261f8125b56746d171a898c23a944f6849b054e14f0243f4
BLAKE2b-256 checksum
How to use checksums
0b2f94e84785f5092dac8cd6754c56c5c0548066541f455517da9a1e2a23865a
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.88.0-py3-none-any.whl

Download URL isovar-1.88.0-py3-none-any.whl
Size 11.9 MB
Tags Python 3
SHA-256 checksum
How to use checksums
f1e4dd37c999c7ba1ba5705e18cca0fb74bb83f83ea97610b2ee64af009a3a04
BLAKE2b-256 checksum
How to use checksums
ca83c449f935994a04f08cce36cec9fda7a82516b7e4883f8e751c708f107c4b
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.88.0

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.88.0 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