Surface mhcflurry pres_score / pres_perc / proc_score from LENS (complement to pepsickle)

[iskandr]

Status

LENS files carry mhcflurry's full prediction stack. Vaxrank reads only two of the five fields:

LENS column	What it is	Vaxrank status
`mhcflurry_2.1.1.aff`	Mutant peptide IC50 (nM)	✓ → `ic50`
`mhcflurry_2.1.1.aff_perc`	IC50 percentile rank	✓ → `percentile_rank`
`mhcflurry_2.1.1.proc_score`	Antigen-processing prior (per-peptide; flank-aware)	ignored
`mhcflurry_2.1.1.pres_score`	Presentation score (proc × binding combined)	ignored
`mhcflurry_2.1.1.pres_perc`	Presentation percentile rank	ignored

Correction: mhcflurry's processing score is NOT the same as pepsickle's

These signals are complementary, not substitutes:

Predictor	Granularity	What it tells you
mhcflurry proc_score	one number per 9-mer	"Does this k-mer survive processing, conditioned on its N-terminal + C-terminal flanks?" Trained on mass-spec eluted ligands.
pepsickle	per-position probabilities across the whole source	"Would the proteasome cut C-terminally to residue i?" for every position. Lets us compute fine-grained C-term cleavage prob and max internal cut prob inside each peptide.

You can't get pepsickle's two metrics out of mhcflurry's single number, and you can't get mhcflurry's flank-aware prior out of pepsickle's per-position scan. Vaxrank should surface both — the LENS-emitted mhcflurry processing score (per-peptide prior) AND the pepsickle credibility tag (per-position-derived c_term + max_internal).

What this issue is asking for (corrected scope)

`EpitopePrediction` gains three optional fields, populated from LENS when present:

• `presentation_score: Optional[float]` — mhcflurry pres_score
• `presentation_percentile_rank: Optional[float]` — pres_perc
• `mhcflurry_processing_score: Optional[float]` — proc_score (per-peptide prior, distinct semantically + numerically from pepsickle's composite)

Reports surface presentation_score / pres_perc alongside ic50 when available.

The pepsickle credibility tagging in PR #262 stays — it provides finer per-position signal that mhcflurry's per-peptide score doesn't capture. The new fields are additive: a fully-annotated EpitopePrediction would carry mhcflurry presentation + mhcflurry processing + pepsickle c_term/max_internal + pepsickle composite, all visible to clinical reviewers.

Acceptance

• LENS path populates the three new fields when columns are present.
• Reports surface presentation_score / pres_perc.
• Pepsickle credibility tagging is retained (different signal, complementary).
• Tests pin the LENS fixture's pres_perc value flowing through to the report and pin that pepsickle's pepsickle-derived fields and mhcflurry's processing fields are independent (one can be set without the other).

Related

• Surfaced in PR LENS / pVACseq end-to-end vaccine design + processing-credibility annotation #262 audit.
• Reports surface only the canonical predictor's IC50 — multi-predictor LENS data lost in HTML/PDF/CSV #261 (multi-predictor reporting) is the column-management side.
• The bigger refactor sketched in EpitopePrediction's TODO comment (split into mhc_affinity_* / pmhc_presentation_* / antigen_processing_* groups) is the right long-term shape.

[iskandr]

Correction: not 9-mer-only

The earlier comparison table said "one number per 9-mer" for mhcflurry's processing score. That's wrong — mhcflurry's affinity / processing / presentation models all accept MHC-I peptides of length 8–15 aa (the full canonical class-I range; the model has length-specific calibration). Pepsickle's per-position scoring is length-agnostic — it scans the source sequence and returns a probability for every residue, so the per-peptide credibility tag (`c_term × (1 - max_internal)`) works for whatever peptide lengths the upstream MHC predictor emits.

So the corrected table:

Predictor	Granularity	What it tells you
mhcflurry `proc_score`	one number per peptide (8–15 aa)	"Does this peptide survive processing, conditioned on its N+C flanks?" Trained on mass-spec eluted ligands.
pepsickle	per-position probabilities across the source	"Would the proteasome cut C-terminally to residue i?" for every position. Lets us compute fine-grained C-term cleavage prob + max-internal-cut prob inside each peptide of any length.

Composite score formula (already implemented in `vaxrank/processing.py:_composite_processing_score`):

```
processing_score = c_term_cleavage_prob × (1 − max_internal_cut_prob)
```

— "good cut at the end (clean release), no big cut in the middle (would destroy the ligand)." Same formula for any peptide length, attached to each EpitopePrediction's annotation. `1 − max` is a conservative approximation for "no internal cut" — the joint `Π(1 − p_i)` over internal positions is strictly more accurate but proteasomes cut roughly once per substrate so the single-max heuristic is a reasonable proxy.