Skip to content

How Vaxrank works

Choose --vaccine-type peptide, mrna, or both before setting antigen lengths, linkers and construct limits. Vaxrank ranks antigen windows, assembles constructs and writes reports. Mutation/CTA/viral integration and expanded vaccine designs are experimental.

Upstream inputs

The VCF/BAM workflow starts after three upstream steps:

  1. Call somatic variants with a tool such as Mutect2 or Strelka2.
  2. Align tumor RNA-seq reads into a BAM.
  3. Obtain the patient's MHC alleles from typing or clinical records.

Pipeline stages

Step What runs
Prepare sequences Varcode annotates variants; Isovar reconstructs RNA-supported protein context. Antigen and CTA inputs use their own adapters.
Predict and score MHCtools runs predictors; Topiary applies filters and scoring expressions. Saved predictions skip model calls.
Select windows Vaxrank chooses antigen windows using epitope scores, reference matches and the configured ranking rules.
Assemble and export Vaxrank applies construct limits and linkers, then writes sequences, synthesis files and reports.

See library responsibilities, input workflows and vaccine designs.

Previously scored evidence

LENS, pVACseq, Topiary and native Vaxrank files reuse supplied predictions by default. A manifest can combine them with new antigen sequences or CTA expression. Input workflows covers prediction modes and required metadata.

LENS source labels

LENS FUSION rows can enter constructs using their supplied pep_context. SPLICE, CTA/SELF and ERV rows remain in reports but need an opt-in for construct selection. A LENS label says where a peptide came from, not that it is a safe tumor-specific target, so this gate applies only to --input-lens:

vaxrank --input-lens patient.lens.tsv \
  --include-lens-source SPLICE \
  --include-lens-source CTA/SELF \
  --include-lens-source ERV

--exclude-lens-source removes a label. The YAML equivalent is vaccine_peptides.included_lens_sources. The older spellings --include-antigen-source, --exclude-antigen-source and included_antigen_sources still work (saved records are read under the new name). Source IDs, transcripts, RNA and normal-tissue evidence remain attached to each record. Targetable intervals come from the report; CTA/self and ERV opt-ins are recorded as overrides.

Antigen types, for every input

--include-antigen-type and --exclude-antigen-type work for any input (variants, fusions, CTA, LENS, assemblies) and take the antigen types used by --min-TYPE-antigens / --max-TYPE-antigens: mutation, fusion, CTA, ERV, splice, viral, SV, isoform. --exclude-antigen-type SV is the same as --max-sv-antigens 0; --include-antigen-type SV lifts a zero cap from YAML. They do not override the LENS label gate above.

Fusion antigens from supplied assemblies

VaccineAntigen.from_fusion_sequence(...) takes a translated sequence and exact amino-acid junction. Targetable peptides must span both partners.

For results from isovar.reconstruct_fusion(...), use:

from vaxrank import fusion_antigens_from_isovar, predict_epitopes, VaccinePeptide

adapted = fusion_antigens_from_isovar(result, tumor_specificity=attestation)
for antigen in adapted.admitted_antigens:
    epitopes = predict_epitopes(mhc_predictor=predictor, antigen=antigen, genome=genome)
    candidate = VaccinePeptide(
        antigen=antigen, epitopes=epitopes,
        combined_score_expr="target_epitope_score",
        ranking_rules=("target_epitope_score", "manufacturability", "self_epitope_score"),
    )

The adapter retains all coding hypotheses in .antigens and the full Isovar result in .reconstruction. A separate tumor-specificity attestation is required for admission. Ambiguous, unsupported and partial-CDS hypotheses stay held out. Mixed junction codons are targetable; peptides wholly inside an inserted sequence are not junction-spanning. This API consumes Isovar results; fusion discovery from BAM files remains upstream.

Mutant transcript assembly (Isovar)

Isovar assembles reads around each variant, retaining nearby phased variants and supported splice context. The ordinary Vaxrank path selects IsovarResult.top_protein_sequence. The separate fusion adapter retains multiple hypotheses. RNA context settings control requested length and support thresholds.

Candidate epitope scoring

MHCtools predicts overlapping peptides at the requested lengths. The default binding policy converts affinity into a logistic score; custom filters and scores use the Topiary DSL.

Vaccine peptide ranking

The default mutation workflow ranks windows using target epitope scores and RNA support, with manufacturability criteria for window selection. Reference matching includes every available annotated protein sequence, including NMD, IG/TR and other translated biotypes. Exact self matches are excluded from mutation target epitopes. Cancer-hotspot annotations flag recurrent mutations.

Selection policies describes alternative scores and window rules. Mixed-antigen selection explains how to rank sources that carry different kinds of evidence.

Data model

Object Contents
VaccineAntigen Sequence, targetable intervals, source identity and admission evidence
MutantProteinFragment Mutation positions, variant and RNA support for mutation inputs
CandidateEpitope Peptide occurrence, context, predictions, comparators and scores
VaccinePeptide Selected antigen window and its epitopes

Ranked outputs are (source, [VaccinePeptide, ...]) pairs. New designs retain up to three non-overlapping target windows per source, controlled by --max-windows-per-antigen-source. Direct and native antigen inputs use their available parent sequence; table adapters retain the best supported source context before window selection. Each selected window competes on its own score. Both writers select unique sequences in the existing ranking order, subject to explicit antigen-type goals and caps. See vaccine designs for category caps, representation goals, manufacturing alternatives and legacy replay.

See evidence and provenance for shared-sequence mappings.

Key modules

Area Modules
Selection and scoring core_logic.py, epitope_logic.py, vaccine_peptide.py
Inputs and persistence epitope_io.py, external_input.py, antigen_input.py
Reference matching reference_proteome.py
Assembly and linkers peptide.py, mrna.py, vaccine_library.py, junction_swap.py
Reports report.py

Libraries Vaxrank builds on

PyEnsembl supplies annotation, Varcode coding consequences, Isovar RNA reconstruction, MHCtools prediction, and Topiary filtering and ranking. DnaChisel optimizes mRNA coding sequences. Jinja templates produce reports through WeasyPrint or pdfkit.