Vaccine designs and construct outputs¶
Experimental. Choose the vaccine type first, then antigen content and antigens per construct:
| Axis | Values | What it controls |
|---|---|---|
--vaccine-type |
peptide / mrna (multi-valued) |
The platform(s); pass both for parallel design |
--antigen-content |
mutation_spanning / minimal_epitope |
What each antigen is |
--peptide-antigens-per-construct / --mrna-antigens-per-construct |
1 / N |
How many antigens to concatenate per construct |
That matrix yields eight designs, four per vaccine type:
| Type | Content | Per-construct | Design name | Reference |
|---|---|---|---|---|
| peptide | mutation_spanning | 1 | SLP (default) | PGV-001 (Saxena 2025) |
| peptide | mutation_spanning | N | Multi-SLP / multi-epitope long peptide | |
| peptide | minimal_epitope | 1 | Minimal-ligand peptide | |
| peptide | minimal_epitope | N | Concatenated minimal-ligand peptide | |
| mrna | mutation_spanning | N | Multi-antigen mRNA (default for mRNA) | Sahin 2017 / Rojas 2023 |
| mrna | mutation_spanning | 1 | Single-antigen mRNA | |
| mrna | minimal_epitope | N | "String of beads" mRNA | Whitton 1993 |
| mrna | minimal_epitope | 1 | Single-ligand mRNA |
--epitopes-per-antigen sets how many top ligands to take from each ranked
vaccine peptide in minimal_epitope mode (default 1).
An antigen window is a selected amino-acid sequence. A construct is one peptide or RNA molecule. A peptide pool contains separate peptide molecules; concatenating antigens makes one longer molecule.
| Default setting | Synthetic peptide | mRNA |
|---|---|---|
| Requested antigen-window length | 15–25 aa | 15–25 aa |
| Antigen windows per molecule | 1 | Up to 5 |
| Molecules per vaccine design | Up to 20 | Up to 2 |
| Whole-molecule length limit | 25 aa with the default single-window layout | 4,000 nt before poly(A), including UTRs and coding elements |
These are configurable design defaults. The RNA cap is a ceiling, not a target. Peptide and mRNA assembly share packing code while supplying separate length calculations and budgets. For concatenated peptide designs, the current total capacity is derived from the configured antigen count, window length and linkers; it is not an independent synthesis-vendor limit. The length check does not establish manufacturability.
Distinct sequences and source mappings¶
Peptide and mRNA assembly group identical emitted antigen sequences after window selection or minimal-epitope selection, before packing or applying construct caps. Ten candidate IDs producing the same sequence occupy one antigen slot. Its label names all retained origins, and all contributing source mappings remain separate. The first enabled ranked source supplies its allocation category. Scores and RNA support are not added across those mappings.
--max-windows-per-antigen-source N retains up to 3 non-overlapping source
windows by default. A source is a recorded mutation/event or an identified
translated antigen, not a gene-name spelling or a sample. Boundaries may touch;
windows cannot share a residue on their parent sequence. Selection takes the
best remaining region, removes overlaps, and repeats. The near-best score
comparison restarts each round. A repeated region with no new target
peptide/allele content does not earn another window. Each retained window then
competes for vaccine capacity on its own configured combined score.
Manufacturing shifts belong to one selected region. Their recorded alternatives must preserve all selected target peptide/allele occurrences and avoid the other selected regions. They do not consume extra windows or slots. Peptide refinement enforces this target-preservation contract. Scores and eligibility still come from the configured DSL and window policy; selection is deterministic and greedy, not a global optimization or an estimate of immune response.
--peptide-candidates-per-slot, --mrna-candidates-per-slot, and
--max-vaccine-peptides-per-variant apply to legacy overlapping-candidate
selection (vaccine_peptides.max_windows_per_antigen_source: null). Saved
pre-3.53 designs and the frozen openvax-v1 profile retain that behavior. New
biological windows all reach assembly without raising candidates-per-slot.
Available sequence/prediction context limits the windows that can be selected;
a previously truncated input cannot recover omitted regions.
Set goals and caps with a separate flag for each antigen type:
| Type | Minimum goal | Maximum cap |
|---|---|---|
| Mutation | --min-mutation-antigens N |
--max-mutation-antigens N |
| Fusion | --min-fusion-antigens N |
--max-fusion-antigens N |
| SV | --min-sv-antigens N |
--max-sv-antigens N |
| CTA | --min-cta-antigens N |
--max-cta-antigens N |
| ERV | --min-erv-antigens N |
--max-erv-antigens N |
| Splice | --min-splice-antigens N |
--max-splice-antigens N |
| Viral | --min-viral-antigens N |
--max-viral-antigens N |
| Isoform | --min-isoform-antigens N |
--max-isoform-antigens N |
Counts are unique antigen sequences across the whole vaccine, including
all mRNA constructs. They count selected source windows in long-antigen mode
and individual epitopes in minimal-epitope mode. A shared sequence counts once
under its first enabled ranked source type and retains all other sources. These are
category totals, distinct from --max-windows-per-antigen-source, which caps
the number of windows taken from each source protein/event.
Minimums default to zero and are goals subject to eligibility and capacity; maximums default to no type-specific cap and are hard limits. A maximum of zero excludes that type from the vaccine. Actual counts and unmet goals appear in reports and saved decisions. A CLI limit overrides only that type's configured value; other YAML limits remain in effect.
Selection always follows the existing score/allele-coverage order, after serving explicit minimum goals and subject to maximum caps. No type receives an automatic quota. A lower-ranked viral candidate cannot displace a stronger candidate merely because no viral sequence has been selected. Scores and eligibility are unchanged; unused capacity passes to other eligible candidates that have room under their caps. No allocation-mode flag is needed.
For example, with ten slots, enough eligible candidates, and all CTA candidates
ranked above mutations, which rank above viral candidates, setting
--min-cta-antigens 2 --max-cta-antigens 4 selects four CTA and six mutation
sequences. A viral minimum would need to be requested explicitly to reserve a
viral slot in this example.
Equivalent Python/YAML settings are VaccineConfig.max_windows_per_antigen_source
and VaccineConfig.antigen_allocation; both construct option classes also accept
antigen_allocation. For example:
vaccine_peptides:
max_windows_per_antigen_source: 3
antigen_allocation:
min_per_kind: {mutation: 5}
max_per_kind: {CTA: 8, viral: 4}
Supported type names are mutation, fusion, SV, CTA, ERV, splice, and
viral, plus explicitly admitted isoform inputs. ORF context is retained as
provenance, not an extra category. These allocation settings are design
preferences, not scientifically established optimal proportions.
The former --antigen-allocation option and category-balancing algorithm have
been removed. Unchanged native designs created with balancing retain their
recorded products and audit on exact replay. They cannot be reassembled using
the retired policy. To deliberately redesign those candidates using the
current ranking, override the historical settings with this YAML (the mode
field is retained only for configuration/replay compatibility):
Both modality manifests contain antigens: exact amino-acid sequences, lengths,
zero-based half-open positions in the peptide or mRNA's encoded protein, and a
sources list. Source records retain candidate and prediction IDs, genes,
transcripts, proteins, species, input IDs, and recorded event/evidence-group
identities. The Python products expose the same records as .antigens and a
derived .antigen_sources mapping. Full prediction and reconstruction evidence
remains in the native dataset and its assembly source graph.
Different sequences are not merged across sources. In legacy selection, several
ncORF windows from one event are alternative sequences, not independent target
events. run_summary.txt counts actual products, distinct antigen sequences,
recorded source events and candidate mappings without known events separately.
An evidence group identifies shared reconstruction evidence; it is not itself a
claim of an independent biological event.
Native designs saved before 3.47.4 with duplicate slots are rebuilt on replay. That may require the configured junction predictor again. Save the corrected native output to replay it offline afterward. Historical designs without duplicate slots still restore their original products unchanged; their older manifests may lack the newer source mappings.
The commands below start from candidates.tsv, a native export with admitted
antigens and retained sequence/annotation evidence. See input workflows
to create one.
Peptide designs¶
SLP (the default): mutation-spanning long peptide, one antigen per construct, as in the PGV-001 design.
vaxrank --input-epitopes candidates.tsv --vaccine-type peptide --output-dir vaccine_out/
# → vaccine_out/{vaccine.fasta, manifest.json, order_form.csv}
Concatenate five antigens with an AAY spacer:
vaxrank --input-epitopes candidates.tsv --vaccine-type peptide \
--output-dir vaccine_out/ \
--peptide-antigens-per-construct 5 --peptide-linker AAY
Select a single short MHC ligand per construct:
vaxrank --input-epitopes candidates.tsv --vaccine-type peptide \
--output-dir vaccine_out/ \
--antigen-content minimal_epitope
mRNA designs¶
Multi-antigen mRNA is the default for --vaccine-type mrna. Antigens are linked with (G4S)2 and
emitted as CDS, no-polyA and full (with polyA) FASTAs plus a structured
manifest.
vaxrank --input-epitopes candidates.tsv --vaccine-type mrna --output-dir mrna_out/
# → mrna_out/{cds.fasta, no_polyA.fasta, full.fasta, manifest.json, mrna-sequence-parts.csv}
String-of-beads mRNA: short MHC ligands linked together rather than mutation-spanning windows.
vaxrank --input-epitopes candidates.tsv --vaccine-type mrna --output-dir out/ \
--mrna-antigen-content minimal_epitope --mrna-antigens-per-construct 8 \
--mrna-linker AAY
Top-N ligands per variant in a string of beads: pack several top MHC ligands from each ranked vaccine peptide as separate antigens.
vaxrank --input-epitopes candidates.tsv --vaccine-type mrna --output-dir out/ \
--mrna-antigen-content minimal_epitope \
--mrna-epitopes-per-antigen 2 --mrna-antigens-per-construct 16
Output modes¶
--vaccine-type defaults to peptide mrna. Specify one type to emit only that modality. --output-dir enables construct files:
a single vaccine type writes directly into the directory, while multiple types
write into peptide/ and mrna/ subdirectories. Analysis reports have their
own --output-* flags and can be requested without writing construct files.
# Both at once (per-modality subdirs in mixed_out/)
vaxrank --input-epitopes candidates.tsv --vaccine-type peptide mrna --output-dir mixed_out/
# Reports only (no vaccine constructs)
vaxrank --input-epitopes candidates.tsv --output-pdf-report report.pdf
# Drive vaccine design from a pre-computed LENS report
vaxrank --input-lens patient.lens.tsv --vaccine-type mrna \
--output-dir mrna_out/ --ensembl-release 102
One text/PDF report in the run directory starts with input coverage and emitted products, then compact candidate rankings linked to those products. Product sequences, lengths, antigen placements and source counts come from the actual assembly outputs. Candidate windows may be longer than a selected minimal epitope or differ from a trimmed product. Candidate prediction scores do not establish final-product or junction coverage. Per-modality directories contain construct files; they do not repeat the report.
Add --report-candidate-details to append grouped source windows and shared
epitope tables. Source IDs link to their complete identities, and tables retain
all source memberships. Differing support, context or predictions remain separate.
This appendix labels target and self epitopes consistently for mutations,
noncanonical ORFs and other admitted sources. Full producer JSON stays in the
native dataset. Compact reports need no annotation queries; the detailed mutation
appendix uses retained annotation or needs --ensembl-release when it is missing.
This holds equally for single files, external inputs and manifests.
The Python report API accepts TemplateDataCreator(..., products={"peptide":
peptides, "mrna": rnas}, candidate_details=False), where values are the emitted
construct lists. An empty list means a successful run with no products; omitting
products produces an analysis-only report. This replaces the old
vaccine_constructions, mrna_ranking_decisions and target_alleles report
arguments: selection forecasts are no longer displayed as final products.
Pass selection=dataset.selection to TemplateDataCreator to show the saved
effective configuration and decision audits. The CLI passes this automatically.
Omitting it leaves unavailable settings explicitly unknown; parser arguments
are never treated as authoritative assembly settings. Library assemblers accept
an optional selection_audit={} dictionary, filled with deduplication and
packing outcomes. Reports are read-only views of these records and products.
Peptide construct files¶
vaccine.fasta, manifest.json and order_form.csv, written into
--output-dir (or --output-dir/peptide/ in multi-mode). The peptide design
comes from --antigen-content and --peptide-antigens-per-construct.
| Flag | Purpose |
|---|---|
--output-dir |
Where to write the construct files |
--peptide-linker |
Inter-antigen spacer (e.g. AAY, (G4S)2); default G4S3 |
--peptide-max-antigen-length-aa |
Maximum requested antigen window length; preserve required target content |
--peptide-n-terminal-acetyl |
Add an N-terminal acetylation note to the manifest |
--peptide-c-terminal-amide |
Add a C-terminal amide note to the manifest |
mRNA construct files¶
A directory holding three FASTAs (cds.fasta, no_polyA.fasta, full.fasta)
plus manifest.json (per-element view) and mrna-sequence-parts.csv (long-format
per-element table with AA and nt). Codon optimization uses
DnaChisel; 2A
self-cleaving peptides keep their published codon usage automatically.
Construct anatomy:
| Flag | Purpose |
|---|---|
--output-dir |
Where to write construct files (or --output-dir/mrna/ in multi-mode) |
--mrna-signal-peptide |
Leader peptide: HLA-A, HLA-B, tPA, IgK, CD8A, CD28 |
--mrna-5p-utr |
5' UTR (e.g. HBB, HBB_FI tandem) |
--mrna-3p-utr |
3' UTR |
--mrna-include-mitd / --mrna-no-mitd |
Include the BioNTech MITD trafficking domain |
--mrna-mitd |
Which MITD variant (HLA-A / HLA-B) |
--mrna-max-length-nt |
Hard cap on construct length before poly(A), including UTRs and all coding elements |
--mrna-antigens-per-construct |
Antigens per CDS |
--mrna-max-constructs |
Stop emitting after this many constructs |
Both modalities use the same packing policy. An antigen that cannot fit in a construct by itself is excluded before category allocation; later candidates that fit remain eligible. Required target content is never cut to force a fit. Peptide construct capacity is the configured number of antigens times the maximum antigen length, plus intervening linkers. mRNA packing reserves the longest allowed optimized linker at each junction. Reports record length exclusions and unmet representation goals, and native replay preserves these decisions. Historical saved products remain reproducible; redesigning applies the current limits.
PolyA tail:
| Flag | Purpose |
|---|---|
--mrna-poly-a-length |
Length of polyA tail (default 120) |
--mrna-poly-a-segmented |
Use the BNT162b2-style segmented pattern (A30 + linker + A70) |
--mrna-poly-a-first-segment |
Length of the first segment when segmented |
--mrna-poly-a-segment-linker |
Inter-segment linker sequence |
Codon optimization:
| Flag | Purpose |
|---|---|
--mrna-codon-species |
Target organism for codon usage (default h_sapiens) |
--mrna-codon-method |
DnaChisel optimization strategy |
--mrna-csv-no-full-rows |
Skip the full polyA'd rows in mrna-sequence-parts.csv (saves disk space) |
Junction linker optimization¶
A per-junction, MHC-aware linker swap minimizes predicted presentation of chimeric k-mers spanning antigen junctions.
| Flag | Purpose |
|---|---|
--mrna-linker |
Default inter-antigen spacer (e.g. (G4S)2) |
--mrna-optimize-linkers / --mrna-no-optimize-linkers |
Require / disable junction prediction; auto by default |
--mrna-junction-predictor |
One MHCtools model for new junction queries; leaves candidate scores unchanged |
--mrna-junction-alleles |
Query alleles; defaults to the declared manifest genotype or VCF/BAM --mhc-alleles |
--mrna-junction-predictor-path / --mrna-junction-predictor-models-path |
Independent executable / weights locations |
--mrna-junction-candidates |
Candidate linkers considered at each junction |
--mrna-junction-rank-strong |
Strong-binder %-rank threshold |
--mrna-junction-rank-mild |
Mild-binder %-rank threshold |
VCF + BAM runs reuse a single configured candidate predictor in auto mode. With
multiple candidate predictors they keep the shared linker; select
--mrna-junction-predictor to enable junction optimization. External-report
runs use the shared linker without new predictions unless
--mrna-junction-predictor is supplied; if those reports declare no genotype,
also supply --mrna-junction-alleles, since observed report coverage is not
treated as a genotype. --mrna-no-optimize-linkers prevents all junction model
loading.
Cached JSON rerendering (--input-json-file) also needs explicit junction model
and allele options for new predictions. YAML equivalents live under mrna:;
optimize_linkers: null selects auto mode.
The rank policy uses affinity when available, otherwise presentation. It does
not add both endpoint counts or treat allele-independent processing and
haplotype-only results as allele-specific hits. The manifest records the policy,
model names/versions, alleles, lengths and peptide queries under
elements.junction_swap; native exports retain it for replay. Disable optional
cleavage annotation with --no-processing-aware-annotation.
Manifest schema¶
The peptide and mRNA construct JSON manifests share a back-compatible schema
(modality, name, length, length_unit, antigen_names, components,
manufacturability). The mRNA manifest additionally exposes cds,
no_polya_nt, full_nt, per-antigen antigens (each with AA and nt), and a
structured elements dict with one entry per layer: 5' UTR, signal peptide,
antigens, linkers per junction, MITD, stop codon, 3' UTR, polyA. Each layer
carries both AA (where applicable) and nt forms for direct inspection.
Shared linker library and grammar¶
Both vaccine types consume the same set of linker names, so one construct design can be ported between peptide and mRNA backbones.
Static entries:
| Name | Type | Use |
|---|---|---|
G2S, G3S, G4S, G5S |
flexible (Gly_n_Ser) | The (Gly4Ser)n family (Huston PNAS 1988); used clinically in BioNTech FixVac / iNeST as (G4S)2 |
EAAAK |
rigid α-helical | When fused antigens need separation rather than flex (Arai Protein Eng 2001) |
RKRR, RVKR, RKRKR |
furin cleavage | R-X-(K/R)-R motif (Hosaka J Biol Chem 1991); see the cited cleavage study |
AAY |
proteasome-friendly | Livingston 2001; spacer comparisons in Yang 2015 and Aguilar-Gurrieri 2023 |
AAA |
alanine spacer | Aguilar-Gurrieri Cancer Immunol Immunother 2023: alanine spacers improved SIINFEKL presentation in the tested cell system |
GPGPG |
helper-T spacer | Between MHC-II epitopes (Livingston J Immunol 2002) |
P2A, T2A, F2A, E2A |
self-cleaving 2A | Co-translational ribosomal skipping for mRNA constructs (Donnelly J Gen Virol 2001; Kim PLoS ONE 2011). In peptide mode these are functionally inert and the manifest annotates them as such. |
Compositional forms, parsed at lookup time:
| Form | Meaning | Example |
|---|---|---|
(BASE)N / (BASE)xN / BASExN |
Repeat N times | (G4S)2 → GGGGSGGGGS, G4Sx2 → same |
GnSm |
Literal n glycines + m serines (a single unit, not a repeat) | G6S → GGGGGGS, G4S2 → GGGGSS |
AnY |
n alanines + tyrosine | A3Y → AAAY |
An |
n alanines (no Y) | A4 → AAAA |
Gn |
n glycines (no S) | G4 → GGGG |
Repeat counts are capped at 100. The 2A entries are codon-frozen and positional, so they are rejected in repeat forms; use the base linker once.
vaccine_library.get_linker(name) returns a Linker with sequence and
primary-source citations. Junction optimization considers G3S, G4S,
(G3S)2, (G4S)2 and AAA by default.
Legacy peptide-mode flag¶
--peptide-mode {slp, minimal_epitope, multi_epitope} is kept for older
scripts. It is shorthand for the orthogonal axes:
slp≡--antigen-content mutation_spanning --peptide-antigens-per-construct 1minimal_epitope≡--antigen-content minimal_epitope --peptide-antigens-per-construct 1multi_epitope≡--antigen-content mutation_spanning --peptide-antigens-per-construct N
Prefer the explicit content and count flags for new designs.
Shared antigen sequences¶
Identical emitted amino-acid sequences occupy one antigen slot, even when
several genes or source candidates contribute them. Product labels, FASTA
headers and manifests retain all recorded origins. Reports link the shared
product to each source, mark the first enabled ranked source as the displayed
representative (is_representative: true), and list each alternative origin's
separate candidate score, admission status, RNA counts, effective lengths and
sample/temporal evidence without summing counts across origins.
Identity of a selected window does not establish identity of complete proteins
or translation of every possible source. When complete source-protein sequences
are supplied (such as verified CTA reference proteins or complete Isovar coding
candidates), manifests and reports group origins that share the exact complete
protein sequence (source_protein_groups) while keeping distinct full proteins
separate beneath the shared window; partial or local-fragment sources remain
explicitly partial or unassessed. Historical native designs retain their
recorded labels during exact replay.