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.83.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.83.0
File Size Uploaded Provenance Actions
isovar-1.83.0.tar.gz 12.7 MB Without provenance Details for isovar-1.83.0.tar.gz

Built distribution (wheel)

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

Total release size: 24.5 MB

Release files / isovar-1.83.0.tar.gz

Download URL isovar-1.83.0.tar.gz
Size 12.7 MB
Tags Source
SHA-256 checksum
How to use checksums
127c0576a968ad09dfee4dc4695f6bcc846e38ebbcc8d2c2f02d6033752ee190
BLAKE2b-256 checksum
How to use checksums
fc6e37ff987c6457e447828b669954220e64668ec0615140d6effb758d11c803
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.83.0-py3-none-any.whl

Download URL isovar-1.83.0-py3-none-any.whl
Size 11.8 MB
Tags Python 3
SHA-256 checksum
How to use checksums
c6a6845388e7d43ad38d9a6c2fd69d2475b3b339229cb3824f4efd3fda43e186
BLAKE2b-256 checksum
How to use checksums
1953bad1407668a6bf635c9b40a43f3d0ed6de993cc2790d44d71871ca74f6d9
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.83.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.83.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