HLA LOH + B2M / TAP / antigen-presentation pathway integrity from LENS

[iskandr]

Status

LENS reports carry essential antigen-presentation-pathway state that vaxrank currently ignores. If the patient has lost an HLA allele or has a damaging mutation in B2M / TAP1 / TAP2, MHC-I presentation is broken and predictions for that allele or pathway are clinically meaningless.

LENS columns vaxrank ignores

HLA loss-of-heterozygosity

• `lohhla_allele_loss_pval` — LOHHLA-derived p-value for HLA allele loss
• `hla_allele_proportion_rna_tumor_reads`, `hla_allele_proportion_hla_rna_tumor_reads` — HLA expression in tumor RNA
• `hla_allele_raw_read_aligned_count`, `hla_allele_support` — read support for the HLA call

Antigen presentation machinery integrity

• `b2m_mutations` (count of damaging B2M mutations) + `b2m_tpm` (β2-microglobulin expression)
• `tap1_mutations` + `tap1_tpm`
• `tap2_mutations` + `tap2_tpm`

If any of these are mutated or B2M/TAP expression is critically low, MHC-I presentation can't happen regardless of how strong a peptide-binding prediction is.

Why this matters for ranking

A patient with TAP2 mutated → all MHC-I predictions are downgraded to "presentation impossible." Today vaxrank ranks them identically to a TAP-intact patient. That's wrong and silently ships a non-functional vaccine.

Vaxrank data-model gap

These are per-patient properties (or per-allele, for LOH), not per-peptide. Need a new place to carry them:

• `PatientInfo` (already exists in `vaxrank/patient_info.py`) gains `hla_allele_status: dict[allele, dict]` and `apc_pathway_status: dict` fields.
• LENS loader populates these from the relevant columns (collapse per-allele LOH p-values across rows; B2M/TAP info is constant per patient).
• Ranking layer:
  • Hard filter: drop predictions for alleles with `lohhla_allele_loss_pval < threshold`.
  • Score penalty: apply a presentation-pathway penalty when B2M/TAP have damaging mutations.
• Reports surface the patient-level pathway status prominently so reviewers see it before consulting per-peptide predictions.

Acceptance

• LENS rows populate `PatientInfo` with HLA + APC pathway state.
• `--drop-lost-hla-alleles` flag filters predictions for LOH'd alleles (default: warn but include, so users see the data).
• Reports surface APC pathway integrity in the patient-info section.
• Tests against the Pt02 fixture pin the wiring.

Related

• Surfaced during PR LENS / pVACseq end-to-end vaccine design + processing-credibility annotation #262 audit (clinically essential info we silently ignore).
• Adjacent to safety-scoring issue Safety scoring of vaccine antigen windows: minimize self-peptide presentation + tissue-aware autoimmunity risk #254 (autoimmunity) — both are pre-vaccine-design checks.

[iskandr]

Q: Do we have any input format for HLA LOH / B2M / TAP integrity today?

A: no. Vaxrank's existing inputs cover MHC alleles (`--mhc-alleles` / `--mhc-alleles-file`) and predictor selection only. There's no field, flag, file format, or YAML schema for:

• Per-allele HLA LOH status (lost / retained / partial).
• B2M / TAP1 / TAP2 mutation status.
• B2M / TAP expression levels.

A grep for `lohhla|b2m|tap1|tap2|hla_loss|allele_loss` across the vaxrank source returns zero hits.

Where the data lives today

• LENS reports: bundled inline as columns on every neoepitope row (constant per-patient values repeated for every row): `lohhla_allele_loss_pval`, `b2m_mutations`, `b2m_tpm`, `tap1_mutations`, `tap1_tpm`, `tap2_mutations`, `tap2_tpm`, `hla_allele_proportion_rna_tumor_reads`, `hla_allele_support`, etc.
• pVACseq aggregate: doesn't carry it.
• VCF / BAM pipeline: LOHHLA / B2M somatic-mutation calls are upstream of vaxrank; the user would need to bring the data in.

Proposed input formats

Option A — derive from LENS rows automatically

LENS already has the data; the LENS loader reads it once (it's per-patient, not per-row) and populates `PatientInfo`. Zero new flags. Works only for the LENS path.

Option B — `--patient-context` JSON / YAML for the VCF/BAM path

A new flag accepting a file like:

```yaml
hla_alleles:
HLA-A02:01:
lost: false
lohhla_pval: 0.42
HLA-B07:02:
lost: true # HARD FILTER: drop predictions for this allele
lohhla_pval: 0.0001
HLA-C*03:04:
lost: false
apc_pathway:
b2m:
mutations: 0
tpm: 18.4
tap1:
mutations: 1 # damaging mutation present
damaging: true # callers can self-classify or vaxrank can use OncoKB-like rules
tpm: 5.2
tap2:
mutations: 0
tpm: 22.1
```

Loaded into `PatientInfo`; consumed by the ranking / filtering layer. Mutually composable with `--mhc-alleles` (the file refines the MHC list with status info).

Option C — augmented `--mhc-alleles`

Inline per-allele LOH status:

```
--mhc-alleles 'HLA-A02:01,HLA-B07:02[lost],HLA-C*03:04[loh_pval=0.02]'
```

Compact for HLA but doesn't extend cleanly to B2M / TAP. Probably too clever.

Recommendation

Ship A and B together. A is free (LENS already has it; just plumb it through). B gives users a path for the VCF/BAM pipeline and decouples patient context from the upstream report. Either path populates the same `PatientInfo` fields, so the downstream ranking layer doesn't care which input the data came from.

C is too cute and conflates a list flag with a structured file.

Filtering / scoring policy (from the original issue)

Once the data is loaded, three behaviors are useful:

• Hard filter for clearly-lost HLA alleles (`lohhla_pval < 0.001` by default; configurable). All predictions for that allele get dropped.
• Score penalty for damaging B2M / TAP mutations (or low expression). Multiplicative on combined_score; doesn't drop the variant but downranks it.
• Report surface in the patient-info section so reviewers see APC pathway integrity before consulting per-peptide predictions.

Acceptance

• LENS path: APC pathway state extracted from row columns and attached to PatientInfo.
• New `--patient-context` flag for the VCF/BAM path.
• `--drop-lost-hla-alleles` (default: warn-but-include; explicit opt-in to hard-filter).
• Reports surface the patient-level pathway status prominently.
• Tests against the Pt02 fixture pin LOH-aware ranking changes vs. LOH-naive.

cc @iskandr — this needs a clinical-review call on the LOH p-value threshold and which mutations count as "damaging" for B2M/TAP1/TAP2 (likely a simple OncoKB-style annotation). Happy to defer the clinical questions until the data plumbing lands.