Choosing and combining inputs¶

Vaxrank accepts variants, scored reports and saved evidence. Experimental antigen and CTA expression inputs use the same scoring, selection and construct outputs.

Input	Entry point	Supplies
Somatic variants + tumor RNA	`--vcf`, `--bam`, `--mhc-predictor`, `--mhc-alleles`	Isovar protein context and new predictions
LENS report	`--input-lens PATH`	Reported peptides, context and evidence
pVACseq report	`--input-pvacseq PATH`	All-epitope or aggregated TSVs; omitted candidates cannot be recovered
Topiary table	`--input-topiary FILE`	Normalized predictions, metadata and features
Native Exacto table	Manifest `format: exacto`	Peptide, ORF and RNA evidence; requires an explicit sample
Saved Vaxrank candidates	`--input-epitopes FILE`	Native candidates; enriched files also retain evidence and policies
Resolved antigens (experimental)	`--input-antigens JSON` or manifest `format: antigens`	Sequences, targetable intervals and admission evidence
CTA expression (experimental)	`--input-cta-expression FILE` or manifest `format: cta_expression`	Patient expression with declared columns, units and threshold

Table-only candidates can be ranked. Construction also requires sequence context and admission evidence. Unresolved sequence hypotheses stay in upstream tables.

Flag reference¶

Flag	Purpose
`--input-manifest PATH`	YAML/JSON input list with shared and per-input scope
`--external-input FORMAT=PATH`	Repeat for `lens`, `pvacseq`, `topiary`, `epitopes` or `antigens` files that already declare compatible scope
`--duplicate-candidates error\\|best\\|worst`	Choose a representative among duplicate observations; default requires scores to agree
`--external-predictions input\\|fresh\\|additive`	Reuse predictions (default), replace LENS/pVACseq predictions, or add named features
`--output-input-predictions PATH`	Save original predictions separately

A manifest replaces individual input flags. Direct --vcf/--bam inputs can still be added alongside it.

Declare the scope of combined reports¶

A single VCF/BAM run or imported report needs no manifest:

vaxrank --vcf somatic.vcf --bam tumor.bam \
  --mhc-predictor netmhcpan --mhc-alleles 'HLA-A*02:01,HLA-B*07:02' \
  --output-csv ranked.csv

Combining reports requires a shared patient, reference assembly and MHC allele set. Save this as inputs.yaml:

schema: vaxrank.input_manifest.v1
patient_id: patient-001
reference_assembly: GRCh38
mhc_alleles: ['HLA-A*02:01', 'HLA-B*07:02']
inputs:
  - format: lens
    path: patient.lens.tsv
    sample_id: tumor-biopsy
    library_id: tumor-rna-1
  - format: pvacseq
    path: patient.all_epitopes.tsv
    sample_id: tumor-biopsy
    library_id: tumor-rna-1

format selects the input adapter, not the file extension. Paths are relative to the manifest. Shared fields can appear at the top level or on each input:

patient_id, reference_assembly, annotation and mhc_alleles must agree wherever declared. Use the exact assembly name and, if known, annotation: ensembl:110 with the producer's release.
sample_id, library_id and timepoint may differ per input.
Optional unknown fields may be omitted or null. --output-patient-id is only a display label, not a declaration for combining evidence.

An explicit --ensembl-release must match the declared assembly and annotation. Assembly alone does not imply the producer's annotation release. Producer columns with these names are checked on every row, including LENS assembly markers; manifest values cannot override conflicts. An mhc_alleles table cell uses a JSON list. Conflicts fail before models or exports run.

Report alleles may cover a subset of the declared genotype. MHCgnomes normalizes alleles; Vaxrank rejects reported alleles outside that set and does not infer a genotype from report coverage.

Rank using original predictions¶

vaxrank --input-manifest inputs.yaml --external-predictions input \
  --output-csv original-ranked.csv --output-input-predictions originals.tsv

input is the default. It applies Vaxrank's filters and scoring to saved measurements, retaining both pooled rank and within-source source_rank. Different models are not automatically calibrated. CSV and --output-neoepitope-report report.xlsx contain per-peptide/allele results.

Saved-report-only runs need no predictor or prediction allele flags. New antigens or cta_expression entries still require a predictor and host annotation; only those entries receive new predictions.

Choose ranking signals with the Topiary DSL:

vaxrank --input-lens patient.lens.tsv \
  --config-text 'epitopes.filter_expr=(affinity.value < 500) & (gene_tpm > 1)' \
  --config-text 'epitopes.score_expr=affinity.logistic_normalized(350, 150)' \
  --output-csv expression-ranked.csv

Unqualified affinity uses each source's selected method. A qualified reference such as affinity[mhcflurry] requires that method in every scored table. Check that the chosen features exist across inputs.

Construct selection and final order¶

vaccine_peptides.combined_score_expr orders constructs across direct and imported inputs, before optional HLA-coverage selection:

Direct inputs generate windows, apply score_fraction_of_best, then select with vaccine_peptides.ranking_rules.
External inputs select the reported context containing their strongest eligible epitope. Only compatible epitopes from that context enter a construct.
Where sources offer the same variant or antigen, final ranking selects one source's construct. Counts and predictions remain with that source.

By default, require_target_epitopes_in_variant excludes constructs with no target epitopes, including known-self-only constructs. Their observations remain in the reports.

The mutation default is sqrt(n_rna_alt) * target_epitope_score. Antigens without mutation counts default to target_epitope_score. To use binding alone across sources:

--config-text 'vaccine_peptides.combined_score_expr=target_epitope_score'

The mutation DSL retains its legacy numeric zero for unavailable counts; provenance distinguishes missing from measured zero. Custom expressions using unavailable mutation fields fail for other antigen kinds.

Exact score ties use RNA support only when all tied counts share stated units and derivation, then target-epitope score, then input order. Counts are never summed across discoveries or converted from reads to fragments. CSV/Excel rank columns are epitope ranks, separate from construct order.

Generate common predictions and re-rank¶

vaxrank --input-manifest inputs.yaml --external-predictions fresh \
  --mhc-predictor mhcflurry --mhc-alleles 'HLA-A*02:01,HLA-B*07:02' \
  --config-text 'epitopes.filter_expr=affinity[mhcflurry].value < 500' \
  --config-text 'epitopes.score_expr=affinity[mhcflurry].logistic_normalized(350, 150)' \
  --output-csv fresh-ranked.csv --output-input-predictions originals.tsv \
  --output-epitopes fresh.tsv

fresh is supported for LENS/pVACseq. It predicts reported peptides with their available flanks on the requested allele set, within any declared genotype. It can add peptide/allele pairs but cannot recover omitted peptides or extend context. Haplotype models retain their genotype and deconvolved presenter; allele-free models retain their scope.

Fresh predictions populate the active candidates. Matching original values appear in Input ... report columns and input_... scoring features. Keep the separate original export: alleles outside the fresh set have no fresh report row.

Combine direct VCF/BAM with tables¶

vaxrank --vcf somatic.vcf --bam tumor.bam \
  --mhc-predictor netmhcpan --mhc-alleles 'HLA-A*02:01,HLA-B*07:02' \
  --input-manifest inputs.yaml --duplicate-candidates best \
  --output-epitopes combined.tsv --output-csv ranked.csv

Shared manifest declarations also apply to direct inputs. An optional direct: object sets their sample/library/timepoint. Reference and allele compatibility are checked before prediction.

Predictor, Isovar, DNA fallback and cache settings apply to direct candidates; imported tables retain their measurements unless additive scoring is requested. Direct fragments, counts, comparators and reference classifications are saved before window selection. Reload combined.tsv with --input-epitopes to repeat scoring and construction without VCF/BAM or models. Use the same vaccine configuration to reproduce window selection.

Construct outputs and provenance¶

Add --vaccine-type peptide mrna --output-dir vaccines for constructs and ASCII/PDF reports. Native CTA/viral reports use retained provenance. Mutation reports need --ensembl-release N when transcript annotation is missing; use the producer's release. New sequence prediction requires host annotation. These rules are the same for single files and manifests.

External inputs use the shared mRNA linker by default. Explicit junction prediction has independent model and allele settings; see junction linker optimization.

LENS supplies reported context windows. pVACseq generally supplies the epitope alone; Vaxrank does not fetch its separate mutant/wild-type FASTAs. LENS splice, CTA/self and ERV construction require source opt-ins.

Native exports retain source rows, scope, content hashes, producer declarations, manifest assertions, comparators and RNA units/derivation. External output directories include candidate_predictions.tsv and input_provenance.json. CSV includes scope columns and input_provenance_json. See the evidence model for identities and source relationships.

Reload or rank a normalized table¶

vaxrank --input-topiary candidates.tsv --output-epitopes saved.tsv --output-csv ranked.csv
vaxrank --input-epitopes saved.tsv --output-csv reloaded.csv

Topiary tables use peptide, allele, kind, value and optional prediction and annotation columns. Its CSV/TSV writers preserve typed metadata and unknown versus empty flanks. Enriched Vaxrank exports add native candidates, the evidence frame, scoring policy and antigen references.

load_predictions(path) returns candidates; EpitopeDataset.load(path) exposes the richer evidence. Older candidate-only files remain readable, but cannot recover construction evidence they did not save.

Replay a saved vaccine design¶

vaxrank --input-topiary candidates.tsv --output-dir design \
  --output-epitopes design/native.tsv --peptide-max-constructs 1 \
  --mrna-poly-a-length 73 --mrna-no-optimize-linkers
vaxrank --input-epitopes design/native.tsv --output-dir replay

A native file saved with construct outputs retains actual products, assembly settings, source mappings and audits. Unchanged replay reuses those products without prediction, codon optimization or annotation downloads, including optimized linkers and their provenance.

Current YAML and explicit CLI options override saved defaults. Changed sources, policies or assembly settings invalidate retained products and audits. Combined designs need compatible settings or explicit overrides, and are assembled anew. Checksums detect altered product payloads. Older exports without saved products can reconstruct from available evidence but cannot recover exact historical products or omitted settings.

The original --max-mutations-in-report limit also applies to assembly; other evidence stays in the native file. Move sibling reference bundles with the table as described in Moving native mutation datasets.

Saved scoring policies¶

Native reload restores saved epitope policies unless explicitly overridden. Combining different policies requires one explicit policy. Source-local model preferences survive export, as do all observations after duplicate selection.

Table-only candidates need a VaccineAntigen for construction: sequence, targetable mask and admission evidence. Supply vaxrank_antigen_json with a matching peptide_offset, or use EpitopeDataset.antigens in Python. Missing or held-out evidence appears in Construction limitation.

Add named prediction features without replacing originals:

vaxrank --input-topiary candidates.tsv \
  --external-predictions additive --external-prediction-prefix comparison \
  --mhc-predictor mhcflurry --mhc-alleles 'HLA-A*02:01,HLA-B*07:02' \
  --config-value 'epitopes.score_expr=comparison__mhcflurry__pMHC_affinity__score' \
  --output-epitopes comparison.tsv --output-csv ranked.csv

The prefix must be unique. Features affect ranking only when the DSL selects them; omit the config override to retain the current formula. Model, version, units and invocation metadata survive export. Additive inference scores existing peptide/allele candidates; it creates neither new windows nor allele assignments for allele-free Exacto observations.

Fresh and additive inference retain distinct occurrence flanks and comparator contexts. --external-peptide-only explicitly discards flanks for inference. External --prediction-cache currently requires that option and a single model; contextual cache integration is pending. Original-only replay needs neither a model nor a cache. Optional processing annotation requires --processing-aware-annotation.

Native Exacto inputs¶

Exacto peptide-variant, primary-structure and translation tables, including gzip, use Topiary's native reader:

schema: vaxrank.input_manifest.v1
patient_id: patient-001
reference_assembly: GRCh38
mhc_alleles: [HLA-A*02:01, HLA-B*07:02]
inputs:
  - format: exacto
    path: peptide-variants.tsv
    sample_id: tumor-rna
    library_id: tumor-long-reads
    exacto:
      primary_structures: primary-structures.tsv
      transcript_read_support: transcript-read-support.tsv
      read_set_id: tumor-bam-read-names
      tag: exacto-run-001
  - format: pvacseq
    path: pvacseq.tsv

Companion paths are relative to the manifest. Optional schema selects the native schema; extra fields remain in metadata. Read-support companions require library and read-set identities. Counts remain transcript-level evidence with exact read membership, not variant support or TPM.

Without primary structures, context and geometry remain unknown. Full ORFs and partial translations stay distinct. Exacto supplies no tumor-specificity admission, reference comparator or pMHC prediction; construction needs those in enriched evidence. ORF-only records can be exported without candidate peptides.

Inspect event, ORF, occurrence and RNA relationships through dataset.evidence_views(). Shared sequence alone does not merge ORFs or transfer another source's prediction, admission or support. Legacy report IDs remain in vaxrank_prediction_id when additive inference normalizes evidence.

Evidence model¶

See Evidence and provenance for the data model. Run vaxrank --print-default-config for current configuration defaults.

Experimental window exposure¶

vaxrank-window-exposure explores delivery of admitted SLP windows under explicit kinetic assumptions, without changing selection. See the window exposure guide.