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

Built distribution (wheel)

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

Total release size: 24.6 MB

Release files / isovar-1.87.0.tar.gz

Download URL isovar-1.87.0.tar.gz
Size 12.8 MB
Tags Source
SHA-256 checksum
How to use checksums
85dd29856ec63498338157feaedf4916bb82998bad8f04ea87d31a0a6fb30812
BLAKE2b-256 checksum
How to use checksums
d32c76384225a12ecc630541f464b952f65e7bd25770c2f086defe58dba39b47
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.87.0-py3-none-any.whl

Download URL isovar-1.87.0-py3-none-any.whl
Size 11.9 MB
Tags Python 3
SHA-256 checksum
How to use checksums
05f206f092560b8511ff1ec69804de800b5df5627cbe6cc742793127b772a9d9
BLAKE2b-256 checksum
How to use checksums
1455267a6f36a2cc9be6baf2bb971a467909836b89e18b5822c837390b6d6a60
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.87.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.87.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