Experimental unified antigen inputs¶
Mutation, fusion, SV, isoform, CTA, ERV, splice and viral antigens can use the same
AntigenDataset API and --input-antigens CLI. Each record carries a
VaccineAntigen: sequence, targetable intervals, source identity and an
admission decision and its evidence.
Callers supply resolved sequences and admission evidence. Held-out records stay
in the evidence but cannot enter constructs. Isovar source inputs
can also reconstruct ncORFs, SV ORFs, viral coding and targeted isoforms directly,
retaining the producer evidence and unresolved/no-protein outcomes in
AntigenDataset.source_evidence.
Shared origin fields¶
VaccineAntigen.origin is an optional AntigenOrigin record shared by direct
variants, LENS and Isovar. It contains:
variants:VariantOriginrecords with SNV/MNV/INDEL/SV type, supplied SV subtype, genomic alleles/coordinates, reference assembly and event identity.coding_references:CodingReferencerecords with annotated/extra-ORF kind, ORF type/ID/source, reference key and source transcript.rna_product: fusion, splice or isoform when supplied.junctions:JunctionOriginrecords with shared genomic endpoints and, only when provided by reconstruction, source-protein intervals. Genomic positions are one-based, including VCF virtual telomeric positions 0 and chromosome length + 1; protein intervals are zero-based, half-open.
These fields travel through prediction, slicing, native serialization, reports
and product source mappings. Original producer evidence stays separately
available. Missing origin fields are valid for historical and unresolved inputs;
unknown does not mean no event occurred. kind remains the compatible allocation
category, not a complete biological classification. See the
event/context selectors.
Targetable intervals, tumor-specificity evidence, RNA support, translation evidence and normal/reference comparisons retain their distinct meanings. Sharing origin fields does not synthesize missing comparisons or expand a caller-selected LENS epitope into a reconstructed junction.
Prepare and predict¶
Given mutation and viral objects from your evidence adapters:
from vaxrank import AntigenDataset
from vaxrank.input_scope import InputScope
inputs = AntigenDataset(
antigens={"mutation-1": mutation, "viral-1": viral},
scope=InputScope(
patient_id="patient-001", reference_assembly="GRCh38",
annotation="ensembl:93", mhc_alleles=("HLA-A*02:01",),
),
)
inputs.save("antigens.json")
vaxrank --input-antigens antigens.json \
--mhc-predictor mhcflurry --ensembl-release 93 \
--vaccine-type peptide mrna --output-dir design \
--output-antigens design/antigens.json
The annotation describes the host; each antigen keeps its own source species
and accession. New predictions require an installed host annotation for
exact-self assessment. Conflicting reference or genotype declarations fail.
The Python equivalent is inputs.predict(predictor, genome=genome), using a
Topiary predictor. It returns the shared EpitopeDataset.
Reuse contextual Topiary predictions while retaining live coverage for cache misses:
vaxrank --input-antigens antigens.json \
--mhc-predictor mhcflurry --prediction-cache prior-predictions.tsv \
--ensembl-release 93 --output-dir design
The cache must describe the same single model/version as the configured live predictor. Lookup uses each native protein occurrence's exact neighbours, endpoint and validated patient genotype. A peptide measured beside different neighbours is a miss, not a reusable score; the live model fills that occurrence and Topiary validates its returned allele, endpoint and version before merging it. Native output retains the completed evidence and replays without either the cache or predictor.
Exact-self lookup shares repeated peptide queries within the same antigen kind and gene-exclusion policy. Overlapping ORF windows therefore do not each rescan the complete host proteome. Every source retains its own candidate identity, admission evidence and full matching gene/transcript/protein provenance; shared queries do not pool RNA support or merge candidates. Explicit host-reference snapshots and custom matching callbacks retain their own matching behavior.
Direct candidate API¶
For an admitted antigen and its scored CandidateEpitope records:
from vaxrank.vaccine_peptide import VaccinePeptide
candidate = VaccinePeptide(antigen=antigen, epitopes=epitopes)
With no mutation fragment, the default combined score is target_epitope_score;
ranking uses target epitope score, manufacturability, then self epitope score.
These are the same defaults used for antigen-only candidates through the CLI and
vaccine_peptides_for_antigen. No fabricated RNA counts are required. The source
kind alone does not imply that single-variant RNA support is available.
Candidates with a mutant_protein_fragment retain the mutation default
sqrt(n_rna_alt) * target_epitope_score and its RNA/position ranking rules.
Explicit combined_score_expr and ranking_rules are preserved. Referencing
mutation-only fields without a fragment raises an error. Resolved defaults and
explicit overrides survive JSON serialization. Admission and self-reference
requirements still apply to direct construction.
Combine new sequences and saved evidence¶
A manifest can mix new sequences with saved predictions. Paths are relative to the manifest:
schema: vaxrank.input_manifest.v1
patient_id: patient-001
reference_assembly: GRCh38
annotation: ensembl:93
mhc_alleles: [HLA-A*02:01]
inputs:
- format: epitopes
path: mutations-and-cta.tsv
- format: antigens
path: viral-antigens.json
vaxrank --input-manifest inputs.yaml \
--mhc-predictor mhcflurry --ensembl-release 93 \
--vaccine-type peptide mrna --output-dir mixed-design
Only the antigens entries receive new predictions. Saved measurements stay
unchanged. All declarations are checked before loading models; a manifest may
fill missing scope but cannot override conflicting evidence. Duplicate files
and loading an antigen input alongside its native prediction export are rejected.
When each file already declares its scope, repeat --external-input
antigens=PATH or combine --input-antigens with --input-epitopes instead.
The Python vaxrank.external_rescoring.prepare_reports API accepts the same
("antigens", path) inputs and an antigen_predictor_factory(scope) returning
a Topiary predictor. The factory runs once after validation.
Direct --vcf/--bam inputs can join this manifest in the same run; their actual
reference and declared patient scope are checked before prediction. Fresh/additive table rescoring
is a separate step. Pooling does not calibrate different models or evidence
types: use an explicit selection policy.
Add CTA expression¶
For current qualified representatives and peptide-level Unsafe containment, see the unified workflow. The historical admission options below remain available when no current sequence bundle is selected.
Add a cta_expression entry beside antigens or epitopes to select CTA targets
from patient expression before prediction:
- format: cta_expression
path: expression.tsv
sample_id: tumor-rna
cta_expression:
measurement_level: gene
id_column: gene_id
value_column: tumor_tpm
expression_unit: TPM
evidence_source: Salmon
evidence_version: "1.10.3"
assay: bulk RNA-seq
min_expression: 2
format: cta_expression selects the CTA expression adapter. The file can be CSV
or TSV; the nested cta_expression settings describe its columns and units.
Use transcript for transcript measurements. Each entry declares its own
columns, units, sample and threshold; one matrix may supply several sample
columns. Existing human Ensembl/OncoRef admission rules apply. Expression is
not converted into protein abundance or mutation read support.
Optional exclusion_policy lists gene_patterns and gene_exceptions;
defaults remain MAGE* and MAGEA4. An optional hitlist_evidence_bundle path
is relative to the manifest and is verified against that input's contract.
--output-dir writes cta_admission.json for one CTA source, or separate files
under cta_admissions/ for multiple sources. --output-cta-admission selects a
single-source file explicitly. Held-out and unresolved decisions remain in
the native evidence, even when a CTA source contributes no admitted proteins
to an otherwise usable mixed run. A wholly unadmitted CTA-only run stops after
writing requested admission records.
For gene-level expression mapped to an alternate annotated CTA gene, Vaxrank
uses Topiary's representative_transcript: complete protein-coding translation
first, then standard amino-acid alphabet, length, and lowest transcript ID.
Measured transcript inputs keep the specified transcript. This deterministic
selection is not a claim of patient isoform abundance or MANE/canonical status.
See Ensembl transcript flags
for the distinction between complete CDS annotations and canonical transcripts.
Tissue-risk protein resolution uses the same ranking when explicitly requested
with PROTEIN_RESOLUTION_REPRESENTATIVE; its default still scans every distinct
eligible protein-coding isoform. PROTEIN_RESOLUTION_LONGEST_ISOFORM remains an
accepted input alias, but newly resolved sets record the representative policy.
Previously saved sets retain their original policy and sequences.
Species-specific CTA expression (experimental)¶
For dogs, declare host_species: dog and a host_reference snapshot. The same
cta_expression entry accepts NCBI Gene IDs or versioned RefSeq transcript IDs.
It uses OncoRef's canine evidence mapped to RefSeq annotation 106 /
GCF_011100685.1. From a source checkout or extracted source distribution, build
the complete annotated reference from its pinned protein FASTA and feature table
(the transfer budget below permits up to 100 MB):
The example uses Proteome.from_refseq() and OncoRef's verified public assets.
Vaxrank checks both source hashes, the annotation, identifier namespaces and the
complete protein inventory before prediction. No Ensembl release is needed.
Canine candidates stay held out until an explicit, gene-specific evidence review
is supplied beside min_expression:
overrides:
"477552":
evidence_source: project target review
evidence_version: "1"
evidence_id: review-PRAME
rationale: Recorded justification for this research target
An override cannot bypass the expression threshold or an unresolved mapping.
Proteins with unknown residues stay unresolved, with their accession and sequence
checksum recorded; other targets continue. Gene measurements do not switch to a
different isoform to conceal an unresolved sequence.
Human MAGE* exclusions do not apply to dogs. Self checks omit only the reviewed
target gene; other genes and extra ORFs remain searchable. OncoRef's partial
coverage, family ambiguity and normal-tissue observations stay in native outputs.
Its canine evidence includes kidney expression for CTCFL and DDX53.
OncoRef 1.22.1+ provides partial P1A/Trap1a mouse evidence,
with explicit strain and normal-tissue coverage limitations. Its single-gene
sequence seed is not a complete mouse host inventory; using it as that inventory
fails before acquisition or prediction. Older snapshots without mouse evidence
raise an explicit unavailable-evidence error.
An optional evidence_snapshot path selects an exported OncoRef snapshot,
relative to the manifest. Python uses the same adapter:
admit_cta_expression(..., host_reference=host, overrides={gene_id: evidence}),
with CTAOverrideEvidence records. Saved results replay without current OncoRef
queries or the original expression table.
Common RNA restriction policy (experimental)¶
An explicit restriction_policy selects the same admission contract for human,
dog and mouse. The ordinary Vaxrank install supports OncoRef 1.23.1 through 1.27.0
and requires ORFdata 0.42.6 or newer; see installation. It
uses the snapshot's identifier namespaces: Ensembl gene IDs and exact versioned
transcripts, or NCBI Gene IDs and exact versioned RefSeq transcripts. It does not
use gene symbols, human orthology, or human default CTA exclusions to admit targets.
Build the annotated inventory with the same API for each supported reference:
from vaxrank.cta_reference_adapter import build_cta_host_reference
host = build_cta_host_reference("human", max_bytes=300_000_000)
host.save("human.proteome.json.gz")
The equivalent example is
python examples/build_cta_host_reference.py human human.proteome.json.gz --max-download-bytes 300000000.
The pinned human Ensembl source set is about 288 MB; the resulting snapshot is
about 45 MB. The builder streams source files without annotation indexes and
checks the total transfer budget before downloading. offline=True, max_bytes=0
reuses verified local files; local_overrides accepts OncoRef's species-qualified
asset paths. This produces an annotated-only inventory. Compose extra ORFs with
ORFdata when available, and retain their selection and coverage in that snapshot.
Ensembl inventories use PyEnsembl's assembly/annotation labels, checked against
the owner's exact assembly accession and release, so a matching variant input
can share the reference without relabeling its provenance.
The current human snapshot is bound to Ensembl 115 / GRCh38.p14. A variant
input annotated with another Ensembl release does not become compatible merely
because it also says GRCh38. Use matching reference/annotation inputs for a
joint design; historical snapshots retain their original identities.
Python supplies CTARestrictionPolicy and CTARestrictionEvidence from
vaxrank.cta_restriction to the existing entry point:
from vaxrank.cta_expression import admit_cta_expression
result = admit_cta_expression(
expression_path, input_contract=input_contract, admission_policy=patient_policy,
host_reference=host, evidence_snapshot=snapshot_path,
restriction_policy=normal_rna_policy, restriction_evidence=normal_rna_evidence,
)
In a manifest, cta_expression.restriction_policy contains the policy's JSON
fields and cta_expression.restriction_evidence names a JSON file relative to
the manifest. Export a typed bundle with json.dumps(dataclasses.asdict(bundle));
read it with CTARestrictionEvidence.read(path). An evidence_snapshot path
selects the exact OncoRef snapshot to which that bundle is bound.
The caller must declare a policy ID/version, native RNA unit/scale, somatic upper and reproductive lower bounds, required tissues, independent donor/sample minima, and a rationale. Vaxrank supplies no validated biological thresholds. Observations retain exact protein/transcript occurrences, quantitative bounds, allocation, tissue role, donor/sample IDs, pooling, source checksums and locators, study lineage, and exclusion reasons. Donor and sample IDs must be reconciled across studies; repeated publications and technical replicates cannot be counted as new donors.
Every full-protein equivalent occurrence in the host must have independently allocated transcript RNA coverage. Missing or ambiguous RNA, pooled negatives, unknown transcript mappings, and absent required tissues remain unresolved. Gene-level patient RNA remains gene-level RNA; it selects a reference protein without asserting isoform abundance or malignant-cell expression. Native OncoRef facts remain attached. Compatible, verified numeric transcript RNA can be compared with the policy, but never replaces independently allocated coverage. Incompatible or qualitative somatic facts require review. Exclusions cannot erase observed somatic counterevidence at the target or an identical protein at another locus.
A target is admitted only if both patient expression and the restriction policy
pass. overrides cannot be combined with this policy. Only the target's annotated
gene is excluded from self matching; other loci and all extra ORFs remain. Native
outputs freeze the policy, full evidence and findings for offline replay. A changed
reference, omitted equivalent occurrence or altered decision is rejected.
Admission remains a draft research selection requiring review. It does not establish binding, presentation, processing or immunogenicity. Existing allele capability checks and audits of every final peptide/mRNA product window still apply. The released dog and mouse candidate facts alone do not constitute a validated normal-tissue restriction panel. Existing human defaults and saved historical decisions retain their recorded semantics.
Declare the host species (experimental)¶
Declare a host by name. For an ordinary mouse, this is enough:
For an HLA mouse, add the intended MHC species:
Only use a list when targeting multiple MHC species: mhc_species: [human, mouse].
Both fields accept common names, scientific names or NCBI taxonomy IDs;
host_taxon_id remains an alias. Equivalent declarations normalize to the same
stored identity. The CLI equivalent is --host-species mouse --mhc-species human.
The API accepts the same declarations through InputScope.from_dict(...).
The host must agree with annotation; declared and observed alleles must match
the intended MHC species. Antigen source species remain separate, allowing
viral sequences in a human or mouse design. Declarations survive native replay.
For fresh mouse predictions, select mouse annotation with
--genome GRCm38 --ensembl-release 93 (or another matching build/release).
Producer tables may leave host cells blank. Integer-valued numeric taxon cells are normalized when read; fractional IDs and booleans are rejected. Manifest and API taxon IDs must be positive integers.
Inputs without new scope fields keep their historical identities; known host annotation still enables species checks.
Host proteome snapshots (experimental)¶
Use an ORFdata snapshot to include selected uORFs and other noncanonical ORFs:
Add this to a manifest with schema: vaxrank.input_manifest.v1. Paths are
relative to the manifest. Standalone inputs accept --host-reference FILE.
Build the snapshot with ORFdata's Proteome.build(...).save(...); its selected
evidence, source hashes, exclusions and every mapped occurrence are retained.
An optional {path: FILE, identity: SHA256} declaration pins its content identity.
To assert the ORF catalogue selection, add catalogues to that mapping:
host_reference:
path: host.proteome.json.gz
identity: <snapshot SHA-256>
catalogues: [] # explicitly annotated-only
For a reference containing extra ORFs, supply the exact source release labels
recorded in its host ORF layers, for example [ncorf-mammals-mouse:1].
Python uses HostReference(proteome, catalogues=["ncorf-mammals-mouse:1"]).
This asserts the existing snapshot composition; it does not acquire or add ORFs.
An omitted declaration accepts its recorded composition. A mismatch fails
before predictor acquisition, including requests for missing dog extras.
Compose the desired inventory with ORFdata first. Snapshot identity pins the
catalogue content, evidence selections, filters and mappings as well as sequences.
HostReference.coverage exposes a detached record of the actual retained
annotated and extra-ORF counts, included source layers, and compatible registered
catalogue releases observed with the installed ORFdata version. The CLI run
summary and HTML/PDF/text reports show the same coverage, even with no ranked
candidates. Registered availability does not mean installation or inclusion.
Other registered releases are reported as unsearched; opaque custom/merged
source labels retain unknown attribution instead of implying exclusions.
An unspecified host assembly leaves compatible catalogue availability unknown.
A selected layer with zero retained ORFs remains visible with its filters.
With ORFdata 0.42.6, dog references have no compatible registered ncORF catalogue. An annotated-only dog report explicitly states that ncORFs were not searched; the canine RNA/protein datasets do not fill that gap. A missing sequence match only describes the selected inventory, not unsearched ORFs.
The snapshot must match the declared host and annotation. It supplies exact-self assessment for new native antigen predictions without a live Ensembl annotation. The historical human CTA path uses annotation for transcript/sequence selection. Mapped nonhuman inputs and the opt-in common restriction policy select sequences directly from the snapshot using its declared namespaces. Custom assembly names and versioned assembly accessions use the snapshot's reference metadata directly. CTA gene exclusions remove annotated proteins, leaving additional ORFs at those genes searchable. Viral entries never become host self.
Native outputs bundle the snapshot in their .references/ directory. Move that
directory with the table for offline replay. Changed or missing snapshots fail.
Coverage is frozen in the native dataset and validated against that snapshot;
replay does not consult the current registry. Older native files with no coverage
record retain their inventory but report historical availability as unrecorded.
Inputs with conflicting frozen coverage cannot be combined; reuse the same saved
reference/dataset to preserve one consistent coverage declaration.
Saved predictions require their original reference; select a different reference
by predicting the source antigens again. Legacy producer tables and direct
VCF/BAM runs retain their existing annotated reference path.
Python accepts a HostReference, ORFdata Proteome, or snapshot path through
AntigenDataset.predict(..., host_reference=...) and
audit_construct_sequence(..., host_reference=...).
For an HLA mouse, also pass mhc_species="human" to the audit, whether using
a snapshot or a live genome.
Shared outputs¶
The ordinary ranking, peptide/mRNA assembly and reports apply to every kind.
Reports distinguish resolved, admitted and held-out records by source kind.
design/candidate_predictions.tsv retains predictions, policies and actual
products for replay:
--output-antigens exports resolved native antigen records in the input JSON
format. It preserves admission evidence and input history, including held-out
and unmeasured records. It excludes prediction values and design policies;
keep the native candidate file for replay. This export also supports native mutation and CTA expression workflows.
Pooled native files retain each input's CTA admission decisions and captured
Hitlist evidence in dataset.selection["source_evidence"], including unresolved
features. A new mixed design requires new product audits.
See mixed-source selection for evidence requirements and current source-allocation limits.
Host, MHC repertoire and antigen origin¶
The reference genome or mapped host snapshot establishes the host species.
Use --host-species mouse (or host_species: mouse in an input manifest)
when no reference establishes it. If both are supplied they must agree;
--host-taxon-id is the numeric spelling of the same declaration.
MHC alleles are checked against this host. --mhc-species human declares an
intentional human MHC repertoire in a transgenic mouse; it does not turn the
host into a human or change the antigen's source species. Each antigen keeps
its own origin, so a human host can contain viral targets.
New mRNA designs use the resolved host's bundled codon table. A mouse reference
selects m_musculus; a human reference selects h_sapiens. With an unknown host
or no bundled table, specify --mrna-codon-species (YAML mrna.codon_species)
explicitly. This override can intentionally select another expression target.
Native replay retains its recorded effective choice, and frozen named policies
such as builtin:openvax-v1 keep their explicit codon settings. In the Python
API, assemble_mrna_constructs(..., host_taxon_id=10090) supplies the host for
antigens without variant-reference metadata; RNAConstructConfig(codon_species=...)
sets an explicit target.
CTA exclusions and bundle checks use the same resolved host. Nonhuman CTA admission needs a mapped host reference and species-specific evidence; requesting human CTA source exclusions on another species raises an error.
Pepsickle uses its mammalian model by default, including for human hosts.
--pepsickle-human-only requires a known human host and selects the upstream
experimental training subset. Pepsickle documents the smaller training set.
Codon selection follows DNA Chisel's target-species contract.
Public MS evidence can annotate any antigen kind before scoring with
--hitlist-local-evidence. This is opt-in for antigen
JSON and Isovar inputs; CTA expression inputs retain automatic local lookup.