Safety scoring of vaccine antigen windows: minimize self-peptide presentation + tissue-aware autoimmunity risk

[iskandr]

Motivation

Multi-antigen vaccine constructs (peptide or mRNA) can present non-mutant self-peptides to the patient's MHC. Three failure modes are currently unmodeled in vaxrank:

1. Off-target self-peptide presentation inside SLP windows. A 25-mer SLP that flanks a mutation can still slide MHC-I/II k-mers across non-mutant regions. Those k-mers are wild-type and won't drive a tumor-specific response — they dilute the immune response and waste vaccine dose. Today vaxrank ranks windows only by mutant-epitope binding; it never scores the interior of the window for non-mutant binders.

2. Self-cross-reactivity within ±1 aa. A window may produce a k-mer that differs by ≤1 aa from a strongly-presenting self-peptide. Those neoantigens carry autoimmunity risk: the responding T-cell clone may also recognize the wild-type self-peptide on healthy tissue.

3. Tissue-aware autoimmunity safety. When self-cross-reactivity is unavoidable, prefer windows whose source proteins are not highly expressed in essential tissues (heart, brain, liver, kidney, lung, pancreas, gut epithelium). Even if some autoimmunity is triggered, hitting a less-essential tissue is far safer.

This issue tracks a safety module that scores candidate vaccine windows on those three axes and uses the scores as ranking tie-breakers (or, optionally, hard filters).

Scope

A. Self-peptide presentation scoring

For each candidate SLP window:

1. Slide MHC-I (8-11) and MHC-II (13-25) k-mers across the non-mutant residues only.
2. Score each k-mer with the configured presentation predictor (mhcflurry-presentation by default).
3. Drop k-mers that already appear in a configurable reference proteome (already-tolerated; not new presentation).
4. Aggregate per window: `self_strong_count` (rank ≤ 0.5%), `self_mild_count` (rank ≤ 2.0%), `worst_self_rank`.

The reference proteome should be pluggable: default to the patient's matched reference (already in vaxrank), but allow users to substitute a custom k-mer index (e.g. tumor-cell-line proteome, restricted self-proteome, or species-specific for non-human work).

B. Self-cross-reactivity (within ±1 aa)

For each mutant epitope produced by a window:

1. Look up all reference-proteome peptides within Hamming distance 1.
2. If any has a strong predicted presentation rank (configurable threshold, default rank ≤ 0.5%), flag the epitope as `autoimmune_risk`.
3. Aggregate to a window-level `autoimmune_risk_count`.

C. Tissue-expression-aware safety penalty

When at least one autoimmune-risk hit fires for a candidate window, weight it against tissue expression:

1. Look up the source gene's expression across essential tissues (GTEx is the standard source — bundle a small `gtex_essential_tissue_tpm.tsv` or query a configurable URL/file).
2. `autoimmune_risk_score = autoimmune_risk_count × max_tpm_in_essential_tissue`.
3. Use as a tie-breaker (or a configurable weighted term in the combined score) to prefer:
   • windows with zero autoimmune-risk hits, then
   • windows whose source proteins are lowly expressed in essential tissues.

The tissue list and TPM threshold are configurable; default essential-tissue list: heart, brain (cortex / cerebellum / basal ganglia), liver, kidney cortex/medulla, lung, pancreas, small intestine, colon. The TPM threshold for "highly expressed" defaults to 10.

API sketch

```yaml

In vaxrank YAML config

vaccine_peptides:
safety:
enabled: false # off by default; opt-in
presentation_predictor: mhcflurry # uses --mhc-predictor by default
reference_proteome: default # "default" = patient ref proteome already in use
self_kmer_lengths_class_i: [8, 9, 10, 11]
self_kmer_lengths_class_ii: [13, 14, 15]
rank_strong: 0.5
rank_mild: 2.0
cross_reactivity_max_hamming: 1
cross_reactivity_rank_strong: 0.5
tissue_expression:
enabled: false
source: bundled # bundled GTEx file, or path to user-supplied TSV
essential_tissues:
- heart
- brain_cortex
- liver
- kidney
- lung
- pancreas
- small_intestine
- colon
tpm_high_threshold: 10.0
weight_in_combined_score: 0.0 # 0 = tie-breaker only; >0 = additive penalty
```

CLI sketch

```
--vaccine-safety-enabled
--vaccine-safety-cross-reactivity-hamming 1
--vaccine-safety-tissue-source gtex_essential_tissue_tpm.tsv
--vaccine-safety-tpm-high 10.0
```

Manifest fields

Each ranked window gains a `safety` block:

```json
{
"safety": {
"self_strong": 0,
"self_mild": 2,
"worst_self_rank": 8.4,
"autoimmune_risk_count": 0,
"autoimmune_risk_hits": [],
"essential_tissue_tpm_max": 0.3,
"essential_tissue": "none",
"safety_score": 0.0
}
}
```

Acceptance

• `safety` block on each window's manifest entry.
• Windows can be ranked / filtered by safety score (configurable weight in the combined score).
• Pluggable reference-proteome backend; default pulls from existing vaxrank reference proteome.
• Bundled small GTEx essential-tissue TPM table (or HTTPS-fetchable manifest).
• Tests: window ordering changes when safety is enabled and one window has a strong self-binder vs another has none; cross-reactivity flag fires for a 1-aa-distance hit; tissue penalty downranks a window whose gene is highly expressed in heart relative to a low-expression peer.

Related

• Filter self peptides #28 (closed 2016, stub for "filter self peptides" / ligandome — never landed)
• Junction-aware ordering for multi-antigen constructs #247 (junction-aware swap; complementary at the inter-antigen level)
• Boundary-processing-aware SLP windowing #249 (boundary-processing-aware SLP windowing; complementary at the SLP boundary)

This issue covers the interior of an SLP window and the cross-reactivity / tissue axes — distinct from #247 (junctions) and #249 (boundaries).

[iskandr]

Pre-implementation: open design questions

The shape is right but three of the knobs aren't decided. Worth resolving before code.

1. Tissue expression data sourcing

• Bundle a GTEx TPM file? What release (GTEx v10 is current as of 2025), what subset of tissues, and at what granularity? A bundled snapshot ages without explicit refresh discipline; it's also nontrivial in size.
• Fetch on demand? Avoids the staleness problem but introduces network dependency and a "first run is slow" footgun. Could cache locally per-release, mirroring pyensembl install.
• GTEx tissue names don't map 1:1 to a clinical "essential" list — GTEx splits brain into 13 sub-regions (cortex, cerebellum, hippocampus, basal ganglia, hypothalamus, ...), heart into 2 (left ventricle, atrial appendage), and so on. The vaccine-safety list is at the organ-system level. Need a curated GTEx-tissue → organ-system mapping bundled with vaxrank.

Decision needed: bundled-snapshot vs fetch-on-demand vs both (bundled minimal table + fetch hook for refresh).

2. "Essential tissues" list

Heart / brain / liver / kidney / lung / pancreas / gut epithelium is a reasonable starting set, but this is a clinical-review call, not a code decision. Open questions:

• Single hardcoded list vs. tier-weighted? Uniform "any essential-tissue expression is bad" treats heart and brain the same as lung and gut. Reality: irreversible/critical tissues (heart, CNS, pancreatic β-cells) carry higher autoimmunity risk than regenerable epithelia.
• Tier proposal: tier-1 (CNS, heart, pancreas, kidney) ≫ tier-2 (liver, lung) ≫ tier-3 (gut epithelium, skin, mucosae). Penalty scales with tier.
• TPM threshold: 10 TPM is a reasonable default but this is also a clinical-review call. May need to be tier-specific (e.g. tier-1 alarm at 1 TPM, tier-3 alarm at 50 TPM).

Decision needed: organ-system list + tier weighting + per-tier TPM threshold. Best landed via a small clinical/immunology review pass, not by the implementer alone.

3. ±1 Hamming distance scan against the reference proteome

The current reference_proteome.py is an exact-match k-mer set with O(1) lookup. Hamming-1 needs more.

• Generate-per-query: for each candidate epitope of length L, generate all 19·L Hamming-1 neighbors and look each up in the existing exact-match set. Per-epitope cost is 19·L hashtable hits — fast (~150-200 lookups for a 9-mer). Memory unchanged. But repeated for every candidate epitope → could add measurable runtime on large patient cohorts.
• BK-tree / Vantage-point tree indexed by edit distance: builds once, supports radius queries directly. Memory cost goes up significantly on a 20M-peptide proteome (each k-mer length needs its own tree, and trees are heavier than a hash set).
• k-mer-LSH / SimHash: probabilistic; might miss true neighbors. Likely overkill at Hamming-1.

Recommendation: prototype the generate-per-query approach first. 19·L lookups per candidate × ~10k candidates per patient = ~20M hashtable hits, comfortably under a second on a hot index. If profiling later shows it's a bottleneck, escalate to a tree.

Worth a small bench script before committing to an architecture.

4. Calibration: weight_in_combined_score

autoimmune_risk_score = autoimmune_risk_count × max_tpm_in_essential_tissue is the current sketch, then folded into the combined score with weight w.

The unanswered question: at what w does a self-cross-reactivity hit outrank a stronger-binding mutant epitope? Without a calibration story, w is just a magic number and users won't know whether to trust the ranking.

Possible approaches:

• Hard filter, not weight: any epitope within Hamming-1 of a strongly-presented essential-tissue self-peptide gets dropped (or moved to a separate "review" tier in the report). No combined-score arithmetic.
• Tier-1 hits = veto, tier-2/3 = weighted penalty: hybrid. Tier-1 (CNS / heart / pancreas) cross-reactivity is a hard exclusion; tier-2/3 contributes to ranking.
• Empirical calibration: pick w so that on a held-out PGV-001 / FixVac neoantigen set the new ranking agrees with the historical clinical-review decisions. Requires labeled data.

Recommendation: ship as a hard filter with a configurable tier set in the first implementation. Save the weighted-score machinery for after we have feedback on the filter behavior.

---

Suggested PR scoping

Splitting the original acceptance criteria into smaller PRs that can land independently:

• A. Interior off-target burden only (no tissue, no Hamming-1): score windows by self-presentation k-mers inside non-mutant residues. The smallest unit; uses the existing exact-match proteome index.
• B. Hamming-1 cross-reactivity (no tissue): add neighbor scan, flag epitopes with self-cross-reactivity. Land after benchmarking the generate-per-query vs tree decision.
• C. Tissue-aware autoimmunity safety: bundle GTEx essential-tissue table, add tier weighting, hard-filter for tier-1. Last because it depends on the clinical-review decisions in items 1 + 2.

Each sub-PR is a self-contained ship; running everything together as one PR is high risk for the sourcing and calibration questions to land arbitrarily.

cc @iskandr — flagging for review of the clinical questions in items 1 + 2.