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:
- Call somatic variants with a tool such as Mutect2 or Strelka2.
- Align tumor RNA-seq reads into a BAM.
- 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.