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.

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; 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 \
    --output-pdf-report vaccine-peptides.pdf \
    --pdf-backend weasyprint

For an offline canine DNA/RNA replay, see the WLOS_0001 TP53 example. It uses original tumor RNA and a published matched-normal somatic call with a random test predictor; the dog's DLA genotype is unknown.

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.

Start from an already-scored report

When MHC prediction has happened upstream, design directly from a LENS or pVACseq report instead of a VCF and BAM:

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.

Command line

vaxrank is the main command; run vaxrank --help for every option and vaxrank --version for the installed release. Companion commands share the installed package:

Documentation

Full documentation: https://openvax.github.io/vaxrank/

• Installation: reference annotation and PDF backends.
• Input workflows: VCF/BAM, LENS, pVACseq, Topiary
• Canine VCF and RNA: dog reference and DLA workflow 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.
• MHC binding predictors: supported predictor names.
• How Vaxrank works: pipeline stages, ranking criteria, data model, module map.
• Varcode, Isovar, and Vaxrank: which library owns which decision.
• Development: local setup, test data, release scripts.

Experimental workflows: unified antigen inputs, Isovar ncORF, SV, viral and isoform inputs, CTA expression inputs, mixed mutation/CTA/viral selection and window exposure.

Development

git clone https://github.com/openvax/vaxrank.git && cd vaxrank
python -m venv venv && source venv/bin/activate
pip install -e ".[hitlist]" pytest pytest-cov ruff
./lint.sh
./test.sh

Always run tests through ./test.sh, not bare pytest. See Development for test data and reference downloads.

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.

Papers and citations

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.