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¶
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 commands share the installed package:
| Command | Purpose | Documented in |
|---|---|---|
vaxrank-mutation-figure |
Transcript and protein context figures from --output-isovar-csv |
Analysis outputs |
vaxrank-evidence-figure |
Evidence summary figure from an evidence JSON | Analysis outputs |
vaxrank-complex-result-figure |
Figures for complex-variant results JSON | Analysis outputs |
vaxrank-window-exposure |
Delivery exposure of admitted SLP windows | Window exposure |
vaxrank-test-data |
Download the shared Sid test data | Test data |
Documentation¶
Full documentation: https://openvax.github.io/vaxrank/. In reading order:
- Installation: reference annotation and PDF backends.
- Input workflows: VCF/BAM, LENS, pVACseq, Topiary tables, CTA expression, antigen sequences and saved evidence.
- Vaccine designs: the design axes, peptide and mRNA construct files, linker library, manifest schema.
- Analysis outputs: report formats and the figure commands.
- Configuration: YAML config, override order, named policy bundles, RNA reconstruction context, Topiary scoring DSL.
- 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, mixed-antigen and window exposure 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.