Analysis outputs and figures¶
Analysis outputs are requested with their own flags, with or without construct files.
Analysis reports¶
Tables of ranked candidates, predicted epitopes and applicable manufacturability metrics.
The console run summary and human-readable reports use the same rule for resolved provenance. Patient alleles and host-species scope inferred or copied from an input are shown; parser snapshots, assembly graphs and other runtime state remain internal. A leading underscore is storage convention, not the classification rule.
| Flag | Output |
|---|---|
--output-ascii-report |
Plain-text summary |
--output-html-report |
HTML report |
--output-pdf-report |
PDF report (wkhtmltopdf or WeasyPrint backend) |
--output-xlsx-report |
Ranked candidate windows: All sheet and one sheet per source |
--output-csv |
The same ranked candidate rows and columns as the workbook |
--output-json-file |
Explicit legacy ranked-object JSON export |
--output-policy-dir |
Optional resolved configuration and policy decision/evidence tables |
CSV/XLSX candidate rows use one schema for VCF/BAM, external and native inputs.
source_rank orders the ranked source groups; window_rank orders candidate
windows within each group. Source kind, identifiers, genes, transcripts, species
and zero-based, end-exclusive targetable intervals accompany each sequence.
Mutation coordinates and expression scores are blank when no mutation fragment
is available. Scores retain their numeric precision. These are candidate windows;
manifests and FASTAs describe the emitted products. Empty results still write
headers and an empty All worksheet.
With --output-dir, the default bundle is ranked_candidates.csv,
candidate_predictions.tsv, vaccine_report.txt, vaccine_report.pdf and the
modality construct files. Native evidence retains source provenance, configuration
and policy decisions. --output-policy-dir DIR additionally writes
DIR/selection_policy.json and DIR/policy_evidence/ for inspecting individual
criteria. Removing those optional exports does not prevent native replay.
Checksum-verified candidate_predictions.tsv.references/ resources, when present,
are required for portable annotation/reference access; keep them with the dataset.
Migration from earlier output bundles:
--output-csvnow always exports ranked windows. To export prediction evidence from external/native input, use--output-neoepitope-report predictions.csv.source_rank/window_rankreplace the mutation-specificvariant_rank/peptide_rankcolumn names. The workbook no longer repeats rank in an unnamed column.- Default runs no longer write
input_provenance.json, a sibling.policy/directory or legacy ranked JSON. Explicit--output-json-filestill works. - Legacy
--input-json-filesupports reports/products but cannot reconstruct a complete native prediction dataset. It does not auto-export native evidence; an explicit--output-epitopesrequest with that input raises an explanatory error.
Joint protein collections¶
The Python API exports retained source proteins, evidence and Vaxrank's selection state to ORFdata without running prediction or ranking again:
from orfdata import ReferenceContext
from vaxrank import to_proteome
reference = ReferenceContext(9606, "human", "GRCh38", "Ensembl", "115")
patient = to_proteome(
results,
sample_id="tumor-1",
source="vaxrank-run-1",
reference=reference,
)
joint = reference_transcriptome.proteome(nc_orf_sources="all").merge(patient)
joint.write_fasta("joint.fasta")
joint.save("joint.proteome.json.gz")
To convert RNA-backed results again without the original reads, save Isovar's portable hypotheses with the same sample and run IDs:
from pathlib import Path
from vaxrank.vaxrank_results import VaxrankResults
Path("results.json").write_text(
results.to_json(sample_id="tumor-1", source="vaxrank-run-1")
)
restored = VaxrankResults.from_json(Path("results.json").read_text())
replayed = to_proteome(
restored, sample_id="tumor-1", source="vaxrank-run-1", reference=reference
)
assert replayed.identity == patient.identity
This JSON retains the source hypotheses and evidence for ORFdata replay. It does not reconstruct live Isovar read objects.
Every retained Isovar alternative comes through Isovar's own adapter. Vaxrank adds an export path and its recorded fragment/selection state without creating a second source protein. DNA-predicted and supplied fragments keep their exact window and mutation intervals; they are not presented as reconstructed full-length proteins. Unknown source references remain unknown and require ORFdata's explicit compatibility policy when composed with a known host.
Reviewing a vaccine design¶
With --output-dir, one vaccine_report.txt and vaccine_report.pdf summarize
all emitted modalities. The product section shows exact sequences, lengths,
antigen placements and source mappings; the candidate table links ranked source
windows to the products that use them. Historical files without source mappings
say that the information is unavailable. Successful empty designs explicitly
report zero products.
The report follows input coverage, emitted products and selection reasons, candidate ranking, source
outcomes, optional candidate evidence, then methods and provenance.
--report-candidate-details adds annotated source windows and paired epitope/WT
comparisons after the source outcomes. Without that flag, the report retains
its compact, annotation-free ranking view. Candidate evidence and manufactured
product coverage remain separately labeled.
Detailed reports group candidates only when their recorded evidence agrees, including source support, admission, coding context, target masks, flanks, comparators and unrounded prediction values. Exact repeated tables are displayed once and linked from every group that uses them. A shared prediction table can accompany different source/window contexts; it does not make those observations equivalent or independent. Recorded source sequences, offsets and flank strings remain in the window-context tables. Empty flank strings do not establish a biological sequence endpoint.
Short identifiers (S1 for a source, G1 for an evidence group and E1 for a
table) are local navigation aids. Full source identities and saved antigen
labels appear under methods/provenance. Native prediction IDs, every source
record, CSV/XLSX candidate rows, product sequences and manifest mappings remain
unchanged. Grouping is a report view, not a ranking or filtering operation.
Target highlighting follows recorded intervals (including disjoint regions and deletion junctions). WT differences are marked for equal-length recorded pairs; unequal-length pairs are not given an invented alignment. WT is a comparator, not evidence of an observed patient-normal protein. Product highlights require unambiguous placement and agreement among the linked source masks.
The predictor overview describes evidence actually available in the reported candidates, including imported results. Missing MHCflurry results are explicit; disabled Pepsickle is distinguished from missing or partial cleavage evidence. NetMHCpan presentation is labeled Score_EL, while MHCflurry presentation and processing retain their model names. Presentation scores run higher-is-stronger; presentation percentile ranks run lower-is-stronger. These model outputs are separate from Vaxrank's configured ranking score and from Pepsickle cleavage annotations. The report's score guide defines each quantity.
The per-row WT affinity must match the target's allele, predictor and version;
a missing matching value is reported as unavailable. Gene/antigen names lead
product headings, with stable product IDs retained for manifest/order-form lookup.
Report-only commands without --output-dir show candidate results and state
that no construct files were emitted. HTML/PDF styling is bundled locally.
Selection explanations¶
Effective settings come from the native dataset's resolved run configuration and actual modality assembly configuration. Saved assembly settings take precedence: a saved peptide cap of 10 remains 10 even when a replay parser has a default of 20. The Methods table labels raw invocation arguments separately.
Candidate calculations show the actual combined-score expression, bound RNA values and units, and retained target contributions by allele. Binding, presentation, comparator and processing annotations do not automatically contribute to that expression. Admission and window constraints can act separately. The optional window utility deduplicates sequence/allele pairs; the ordinary target-epitope score sums retained occurrences.
Window decision references link products and candidates to recorded coordinates, constraints, ordering keys and a labeled preview of alternatives. New selections record score-fraction/lexicographic choices as well as optional window-utility choices. Exact-sequence deduplication precedes construct limits; distinct overlapping sequences can occupy separate slots without representing separate source events. New assembly audits distinguish final capacity exclusion from window eligibility failure. Linker sections show actual per-junction choices and the recorded whole-construct burden comparison, or why prediction was skipped. A zero self/serum weight does not establish a completed assessment.
Historical missing decisions remain explicitly unavailable. Report generation never reruns selectors or changes product manifests. Native replay preserves saved assembly records; new explanatory metadata is checksummed with the products but does not invalidate an otherwise identical historical assembly. No additional decision sidecar is required.
Length settings retain their existing semantics: without window refinement, the minimum antigen length is a warning threshold. A single antigen exceeding a packer's length target can still be emitted with a warning. The report shows actual product lengths as well as these settings.
Neoepitope report¶
A per-(peptide, allele) table in XLSX or CSV, chosen by file extension. Request it explicitly for VCF/BAM, external or native input; it supplements the ranked candidate table and native prediction dataset.
| Flag | Output |
|---|---|
--output-neoepitope-report |
XLSX (default) or CSV (by extension) |
Mutation and assembly figures¶
vaxrank-mutation-figure turns the Isovar table produced by
--output-isovar-csv into publication-ready, white-background transcript and
protein context figures. When the input includes the optional *_cdna_sequence
and *_cdna_variant_{start,end} columns, each variant also gets a
5-prime-to-3-prime nucleotide comparison. Both views separate the reference
transcript, the annotation-only mutant prediction and the RNA-assembled
sequence, so unsupported or assembly-refined claims stay explicit.
The random predictor below is for testing the figure workflow only.
vaxrank --vcf variants.vcf --bam tumor-rna.bam \
--mhc-predictor random --mhc-alleles 'HLA-A*02:01' \
--output-isovar-csv patient-isovar.csv
vaxrank-mutation-figure patient-isovar.csv \
--output-root figures \
--variant DYNC1H1 \
--format svg --format pdf --format png \
--png-scale 3
Outputs are grouped under figures/YYYY-MM-DDTHHMMSSZ/. Every variant gets an
SVG, a PDF, a high-resolution PNG (3600×2100 at the default 3× scale) and a
compact JSON record. The figure and JSON distinguish annotation
gene/transcript provenance from RNA-assembly provenance. The run manifest
records the input checksum, Vaxrank version, formats, raster dimensions and
file inventory. Omit --variant to render every row. Use --timestamp for
reproducible builds or tests; an existing run is never overwritten.
Evidence figures for structural variants¶
For structural variants and fusion junctions, use a cross-platform evidence JSON rather than an Isovar table:
vaxrank-evidence-figure evidence.json \
--output-root evidence-figures \
--format svg --format pdf --format png
This view keeps DNA, short-read RNA, short-read assembly and long-read RNA as
separate evidence stages. It displays the junction nucleotide sequence and
withholds a protein unless the input supplies an established coding sequence.
See examples/osteosarc_evidence_figures/ for DNA-only, cross-platform,
matched-sample long-read rescue, and unresolved long-read-only examples.
Complex-result figures¶
To show the downstream Vaxrank decision rather than the evidence alone, use a complex-result record. This view separates DNA interpretation, RNA support, translated protein, target epitopes and the final vaccine-construct selection:
vaxrank-complex-result-figure results.json \
--output-root result-figures \
--combined-output vaxrank-complex-variant-results.pdf
The timestamped run contains a compact combined PDF and one high-resolution
PNG/SVG page per result. See examples/osteosarc_complex_results/ for a real
assembly-dependent frameshift selection, an assembled indel with no passing
binder, an ambiguous fusion held out of ranking, and an unresolved long-read
fusion whose protein is deliberately withheld.