Skip to content

Experimental CTA expression inputs

Vaxrank accepts patient expression tables without VCF/BAM. OncoRef supplies human CTA membership; Topiary/MHCtools predict admitted proteins for the shared ranking and peptide/mRNA design workflows.

To combine expression with viral sequences or saved mutations, use a cta_expression manifest entry. For one table:

vaxrank --input-cta-expression patient-expression.tsv \
  --cta-expression-level gene --cta-id-column gene_id --cta-value-column TPM \
  --cta-expression-unit TPM --cta-min-expression 2 \
  --cta-sample-id patient-001 --cta-expression-source 'patient RNA workflow' \
  --cta-expression-version workflow-2026.10 --cta-expression-assay 'bulk RNA-seq' \
  --ensembl-release 93 --mhc-predictor mhcflurry \
  --mhc-alleles 'HLA-A*02:01,HLA-B*07:02' \
  --vaccine-type peptide mrna --output-dir cta-design \
  --output-epitopes cta-design/native.tsv

Install the annotation and predictor assets first. Use transcript with Ensembl transcript IDs for transcript measurements. The threshold is required in the declared units; 2 TPM here is an example choice.

Default exclusions are MAGE* with an exact MAGEA4 exception. Repeated --cta-exclude-gene-pattern and --cta-allow-gene options replace those lists; --cta-no-gene-exclusions removes them. Matching uses canonical, case-sensitive OncoRef symbols.

Windows use the shared selector and vaccine length settings. Ranking defaults to binding. Expression rules are explicit, for example --config-text 'epitopes.filter_expr=cta_gene_tpm > 3' or --config-text 'epitopes.score_expr=cta_expression_value'. Gene and transcript TPM columns are distinct; other units do not populate TPM columns.

Alongside standard reports and constructs, outputs include:

File Contents
cta_admission.json Every admission decision, including held-out targets
cta_target_decisions.csv Selection and rejection reasons
cta_design.json Selected coordinates and final product inventories
cta_product_predictions.tsv Final product measurements, without changing native ranking

Reload with --input-epitopes cta-design/native.tsv --output-dir replay. Unchanged products, settings and audits replay without original inputs or new queries. Changed products invalidate prior audits. See junction optimization for separate junction-model settings.

Hitlist evidence

Hitlist is installed with Vaxrank; there is no hitlist installation extra. For CTA expression inputs, Vaxrank automatically queries exact peptides in the current local Hitlist MS index, scoped to each predicted allele's MHC species. For other candidate inputs, opt in with --hitlist-local-evidence as described in Global Hitlist lookup. Existing defaults are unchanged. It uses Hitlist's normal data directory, including HITLIST_DATA_DIR when set. Vaxrank does not download data or build indexes. Use hitlist data dirs and hitlist data list to inspect the installation; register source exports with hitlist data register and build them explicitly with hitlist data build.

Missing, stale or unverifiable data leave MS evidence unknown. The saved dataset records this status in selection["hitlist_local_evidence"]. Successful queries retain their peptide/species scope, returned observations and index metadata, so native replay does not need the local installation. Pooled inputs retain these records separately under selection["source_evidence"]. Local MS records alone leave CTA-specificity and tissue-risk columns unknown.

To supply the fuller CTA-expression evidence contract, use --hitlist-evidence-bundle DIRECTORY, created by Hitlist's export cta-evidence command. An explicit bundle takes precedence over local data. Vaxrank verifies artifact hashes, relationships, expression input, columns, units, measurement level, Ensembl release and OncoRef version. It retains the captured evidence without rebuilding indexes.

Scoring columns include hitlist_ms_observations, hitlist_query_status, hitlist_cta_specific and hitlist_avoid_sequence. Per-allele facets distinguish monoallelic MS, experimental restriction, predicted restriction and donor-HLA candidates. These overlapping facets are not summed into a confidence score. Donor typing gives candidate alleles, not measured restriction.

Only exact observed peptides acquire MS support; longer observations do not support unobserved nested epitopes. Unqueried sequences have null support. Zero means no positive observations in the captured source, not an experimental negative. Only verified MS measurements count; fluorescence, binding and unknown modalities do not. Public observations remain separate from patient measurements. MS/tissue filtering is an explicit DSL choice. See the primary HLA Ligand Atlas study.

Library admission API

from pyensembl import EnsemblRelease
from vaxrank.cta_admission import CTAAdmissionPolicy
from vaxrank.cta_expression import (
    CTAExpressionInput, CTATargetExclusionPolicy, admit_cta_expression,
)

result = admit_cta_expression(
    "patient-expression.tsv",
    input_contract=CTAExpressionInput(
        measurement_level="gene",  # or "transcript"
        id_column="gene_id", value_column="TPM",
        expression_unit="TPM", sample_id="patient-001",
        evidence_source="patient RNA quantification workflow",
        evidence_version="workflow-2026.10", assay="bulk RNA-seq",
    ),
    admission_policy=CTAAdmissionPolicy(min_tumor_expression=2, expression_unit="TPM"),
    genome=EnsemblRelease(93),
    exclusion_policy=CTATargetExclusionPolicy(
        gene_patterns=("MAGE*",), gene_exceptions=("MAGEA4",)),
)
result.save("cta-admission.json")
antigens = result.admitted_antigens

Declare units, sample, measurement level, columns, assay and producer version. Blank/NA expression stays unknown; zero is measured. Negative, nonfinite, nonnumeric, missing-ID and duplicate normalized-ID rows fail. Original IDs, including version suffixes, and the input SHA-256 are retained.

Canonical gene inputs use OncoRef's canonical transcript. Verified alternate loci use their own longest annotated protein, with transcript ID breaking ties. Transcript inputs use only the measured transcript; version mismatches are held out. Gene expression is not assigned to an isoform or protein. Counts are not summed across genes, transcripts or identical proteins; source occurrences stay separate. See Salmon and Ensembl canonical selection.

Only canonical CTAs above the threshold are admitted. Noncanonical, unresolved, unmeasured and excluded targets remain in the decision list. Target exclusions are separate from the self-reference background: the full verified CTA candidate set defines source exclusions. Ambiguous or unverified loci and non-CTA sources with identical sequences remain in that background.

Audits retain annotation identities, mapping decisions and reference hashes. Earlier native files keep their original identity contract and exclusions on replay. CTAExpressionResult.load("cta-admission.json") restores admission without the expression file or new OncoRef queries; save the native candidate dataset to replay predictions and constructs too.

Pinned dated annotations

The library admission API also accepts a dated EnsemblRelease, for example EnsemblRelease("2026_04", species="human") or EnsemblRelease("2013_09", species="human", assembly="GRCh37"). Install its annotation data before admission. A saved annotation_release retains the exact YYYY_MM string; numbered releases retain their integer values.

Identity and input-scope checks use the resolved biological assembly, so an accession or custom reference_name can keep its original cache/display label. Human CTA identity still requires explicit human GRCh37/GRCh38 metadata; missing species, unknown builds and malformed release dates fail before lookup. Older annotation providers without assembly retain their reference_name fallback.

Vaxrank 3.46.11 pins OncoRef 1.19.2 for this support and requires PyEnsembl 2.29 or later. Existing numbered admissions retain their saved fingerprints and exclusions on replay. No genome cache migration or reindexing is required.

Released prerequisites

Core version requirements, including Hitlist, are installed with Vaxrank. Hitlist datasets are installed separately. CTA protein inference accepts --prediction-cache under the same contextual contract as native antigens and direct variants. Exact source neighbours, endpoint and the validated patient genotype must match; missing coverage uses the single configured live predictor. Native CTA evidence retains the completed predictions for predictor-free replay.