Skip to main content

Tests Coverage Status Docs GitHub Pages PyPI

Vaxrank

Vaxrank selects mutated protein fragments for personalized therapeutic cancer vaccines. It is the antigen ranking and vaccine design component of the OpenVax pipeline.

It takes somatic variants, tumor RNA-seq and MHC alleles, or previously scored candidate epitopes, and returns ranked antigen windows, peptide or mRNA construct files, and reports for reviewing the evidence behind each design. Unified mutation/CTA/viral inputs and the expanded peptide/mRNA design workflows are experimental. Vaxrank builds on the openvax stack: varcode annotates variants, isovar assembles mutant protein sequence from tumor RNA, and topiary with mhctools predicts and ranks MHC ligands.

Install

pip install vaxrank
pyensembl install --release 113 --species human   # match your reference genome

Vaxrank needs Python 3.11 or newer. PDF reports additionally need wkhtmltopdf or WeasyPrint's system libraries; see installation.

Quick start

Choose the vaccine type first: peptide, mrna, or both. This smoke example uses the mouse B16 melanoma files in a repository checkout and a random test predictor. It exercises the workflow; its scores are not biological predictions.

vaxrank \
    --vaccine-type peptide \
    --download-reference-genome-data \
    --vcf tests/data/b16.f10/b16.vcf \
    --bam tests/data/b16.f10/b16.combined.bam \
    --mhc-predictor random \
    --mhc-alleles H2-Kb,H2-Db \
    --output-ascii-report vaccine-peptides.txt

The report starts with what was read and what survived each stage:

Vaccine Design Report
Vaccine type: peptide
MHC alleles: H2-K*b H2-D*b
...
Parsed variants loaded: 5
Variants with annotation results: 5
Coding-effect variants: 4
Coding-effect variants with an RNA-derived protein: 2

It continues with the selection rules, each ranked candidate window with its scored epitopes, per-source outcomes and provenance. Add --output-pdf-report vaccine-peptides.pdf for a PDF (see PDF reports).

For a real VCF + RNA run, supply:

  • --vcf: somatic variants, from any variant caller
  • --bam: tumor RNA-seq alignments, used by Isovar to assemble mutant transcripts
  • --mhc-alleles: the patient's MHC alleles, as separate quoted arguments or a quoted comma- or space-separated list
  • --mhc-predictor: which binding predictor to run (available predictors)

These allele-list forms work:

--mhc-alleles 'HLA-A*02:01' 'HLA-B*07:02'
--mhc-alleles 'HLA-A*02:01,HLA-B*07:02'
--mhc-alleles 'HLA-A*02:01 HLA-B*07:02'

Keep the quotes: an unquoted * can expand to filenames, or cause zsh to reject the command before Vaxrank starts.

To emit vaccine constructs, add --output-dir (both modalities by default). Use --vaccine-type peptide or --vaccine-type mrna to select one modality. Vaccine designs describes the peptide and mRNA designs and the files each one writes. For an offline canine DNA/RNA replay, see the WLOS_0001 TP53 example.

Command line

vaxrank is the main command. Running a design takes flags only (vaxrank --vcf … --bam …, vaxrank --input-lens …). vaxrank --help is a one-screen summary; vaxrank help TOPIC prints one group of options (variants, isovar, cta, predict, design, peptide, mrna, annotation, output, advanced) and vaxrank help all prints every option. vaxrank run FLAGS is an optional spelling of the bare form. Other commands are vaxrank policies [show NAME], vaxrank config, vaxrank replay FILE and vaxrank help. vaxrank --version prints the installed release.

Besides VCF + BAM input, it designs directly from a LENS or pVACseq report when MHC prediction has happened upstream:

vaxrank --input-lens patient.lens.tsv \
        --vaccine-type mrna --output-dir mrna_out/ \
        --ensembl-release 102

Use the Ensembl release the report was annotated with. Original predictions are reused by default. Input workflows covers pVACseq reports, saved Vaxrank evidence, combining several reports in one run, and when to compute new predictions instead.

Companion command sharing the installed package:

Command Purpose Documented in
vaxrank-test-data Download the shared Sid test data Test data

Documentation

Full documentation: https://openvax.github.io/vaxrank/. In reading order:

  1. Installation: reference annotation and PDF backends.
  2. Input workflows: VCF/BAM, LENS, pVACseq, Topiary tables, CTA expression, antigen sequences and saved evidence.
  3. Vaccine designs: the design axes, peptide and mRNA construct files, linker library, manifest schema.
  4. Analysis outputs: report formats and the figure commands.
  5. Configuration: YAML config, override order, named policy bundles, RNA reconstruction context, Topiary scoring DSL.
  6. How Vaxrank works: pipeline stages, ranking criteria, data model, module map.

The site also covers MHC binding predictors, the canine workflow, which library owns which decision, and the unified mutations/ncORFs/SVs/fusions/CTA workflow.

Evidence guides cover local Hitlist evidence and MS-supported scoring. See also the experimental antigen, Isovar, CTA expression and mixed-antigen workflows.

Development

git clone https://github.com/openvax/vaxrank.git && cd vaxrank
python -m venv venv && source venv/bin/activate
pip install -e "." 'setuptools>=77.0.3' pytest pytest-cov ruff
./lint.sh
./test.sh

Always run tests through ./test.sh, not bare pytest. Every pull request bumps vaxrank/version.py. See Development for test data, reference downloads and releases.

Clinical studies

The OpenVax pipeline has used Vaxrank in these Mount Sinai trials:

  • PGV001 / NCT02721043: personalized vaccines for solid and hematologic malignancies.
  • NCT03359239: PGV001 with atezolizumab in urothelial cancer.
  • NCT03223103: PGV001 with tumor treating fields and temozolomide in glioblastoma.

Methods and published results are cited below.

Citation

Vaxrank algorithm:

Rubinsteyn, A., Hodes, I., Kodysh, J. & Hammerbacher, J. Vaxrank: A Computational Tool For Designing Personalized Cancer Vaccines. bioRxiv (2017).

OpenVax pipeline (methods):

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

PGV001 clinical results:

Saxena, Marron, Kodysh, et al. PGV001, a Multi-Peptide Personalized Neoantigen Vaccine Platform: Phase I Study in Patients with Solid and Hematologic Malignancies in the Adjuvant Setting. Cancer Discovery 15(5), 930–947 (2025).

Saxena, Anker, Kodysh, et al. Atezolizumab plus personalized neoantigen vaccination in urothelial cancer: a phase 1 trial. Nature Cancer 6(6), 988–999 (2025).

BibTeX for the Vaxrank paper:

@article {Rubinsteyn142919,
    author = {Rubinsteyn, Alex and Hodes, Isaac and Kodysh, Julia and Hammerbacher, Jeffrey},
    title = {Vaxrank: A Computational Tool For Designing Personalized Cancer Vaccines},
    year = {2017},
    doi = {10.1101/142919},
    publisher = {Cold Spring Harbor Laboratory},
    URL = {https://www.biorxiv.org/content/early/2017/05/27/142919},
    journal = {bioRxiv}
}

License

Apache 2.0. Contributions are welcome; see CONTRIBUTING.md and the code of conduct.

Metadata

Release files for vaxrank 3.61.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 vaxrank 3.61.0
File Size Uploaded Provenance Actions
vaxrank-3.61.0.tar.gz 2.7 MB Without provenance Details for vaxrank-3.61.0.tar.gz

Built distribution (wheel)

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

Total release size: 5.5 MB

Release files / vaxrank-3.61.0.tar.gz

Download URL vaxrank-3.61.0.tar.gz
Size 2.7 MB
Tags Source
SHA-256 checksum
How to use checksums
949297b72770bc4a90127f8127705d49c94744a61eb44b45f84841b3b2ecc35f
BLAKE2b-256 checksum
How to use checksums
251225d02cde669d17a17862b13196268883197ee6f31fed414d7d2489b8f9d1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.6

Release files / vaxrank-3.61.0-py3-none-any.whl

Download URL vaxrank-3.61.0-py3-none-any.whl
Size 2.7 MB
Tags Python 3
SHA-256 checksum
How to use checksums
26653647a517a9f813a5f927e716eb36dce209a3af2721d72e19ebea9a36a1de
BLAKE2b-256 checksum
How to use checksums
8d5385df1f46eed22a50ed7b99414bb7bc9df9885e9f8485c36241efa00f09b7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.6

Security for vaxrank 3.61.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

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