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:
- Reading and filtering results
- Choosing the reference annotation and sequencing recommendations
- Collecting and counting RNA reads and protein context selection
- Structural variants:
run_isovarrejects symbolic SVs and breakends; useisovar sv-rna,isovar sv-auditor, for a fusion assembled by another tool,isovar fusion - Internal design: how reads become proteins
- Changelog
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.