Surface non-SNV antigens (SPLICE / FUSION / CTA-SELF / ERV) from LENS reports

[iskandr]

Status

Currently dropped silently. ~30% of antigens in a real LENS report (Hugo IPRES Pt02: 613/2153 rows) have NaN `variant_coords` because their source isn't a single point mutation:

• SPLICE (~6% of Pt02): aberrant splice junctions — coords live in `splice_coords` / `splice_description`.
• FUSION (~0.1%): gene fusions — coords in `fusion_left_breakpoint` / `fusion_right_breakpoint` plus `fusion_left_gene` / `fusion_right_gene` / `fusion_type`.
• CTA/SELF (~13%): cancer-testis antigens — no point mutation; tumor-specificity comes from expression pattern.
• ERV (~10%): endogenous retroviruses — `erv_orf_id` and `erv_*` columns.

Why these matter

These are real neoantigens with known therapeutic value:

• Fusion-derived neoantigens are the canonical example for fusion-driven cancers (e.g. EWSR1-FLI1 in Ewing sarcoma).
• CTA-driven vaccines (NY-ESO-1, MAGE-A) are the basis for several clinical trials.
• ERV-derived antigens are an active area for melanoma and other tumors.

Vaxrank data-model gap

`MutantProteinFragment` is shaped around point mutations (single `varcode.Variant`). To represent fusion / splice / CTA / ERV, we need either:

1. Extend the data model: add an `antigen_source` field plus per-source provenance (e.g. `fusion_breakpoints: tuple`, `splice_junction: dict`, `cta_gene_id: str`, `erv_orf_id: str`). Each source type gets its own optional dataclass attached to the fragment.

2. Polymorphic dispatch: a single `SourceProvenance` union type with subclasses (SNVProvenance, SpliceProvenance, FusionProvenance, CTAProvenance, ERVProvenance).

3. Free-form metadata dict: `MutantProteinFragment.source_metadata: dict` — least invasive, least typed, most flexible.

Option 1 or 2 is the right long-term move; option 3 unlocks the data faster while we figure out the schema.

Acceptance

• LENS rows with `antigen_source` ∈ {SPLICE, FUSION, CTA/SELF, ERV} produce `MutantProteinFragment`s with their source-specific provenance preserved.
• Reports surface the antigen source so reviewers know what kind of neoantigen they're looking at.
• Per-source filtering: vaccine designs can opt in / out of CTA, ERV, etc. independently.

Related

• Surfaced during PR LENS / pVACseq end-to-end vaccine design + processing-credibility annotation #262 audit ("we're throwing away ~30% of LENS antigens").
• CTA antigen database for on-target ligand classification (#249 follow-up) #257 (CTA database) is the upstream-data side of CTA support; this issue is the data-model side.

[iskandr]

Concrete plan per source type

1. Fusion: representable today via `varcode.StructuralVariant` (added in varcode 4.x)

`varcode.StructuralVariant` (subclass of `Variant`) supports `BND` (breakend) types — exactly what fusions are at the genomic level. A fusion = two breakends, one per partner gene. LENS already gives us:

• `fusion_left_breakpoint`, `fusion_left_gene`, `fusion_left_transcript`
• `fusion_right_breakpoint`, `fusion_right_gene`, `fusion_right_transcript`
• `fusion_type`, `fusion_annotation`, `fusion_id`

Mapping: build a `StructuralVariant(sv_type="BND")` per fusion, with the mate breakpoint pointing at the partner. The peptide is the junction sequence which LENS already gives us in `pep_context` (concatenated reading frame across the breakpoint).

Implementation: `_variant_from_lens_row` grows a `FUSION` branch that builds a `StructuralVariant`, parses both breakpoints, sets the mate. `MutantProteinFragment` already accepts any `Variant` subclass, so no data-model change needed there. Future varcode-effect annotation on a `StructuralVariant` will use varcode's SV annotator.

2. Viral antigens: file-bundled FASTA, treat as a one-off variant type

These don't have a host-genome variant, but they DO have a real protein source: the viral ORF. Plan:

• Bundle a small viral-antigen FASTA (HPV E6/E7, EBV LMP1/2/EBNA1, HBV preS/S/X/core, MCPyV LT/sT) — see Oncovirus antigen database for on-target ligand classification (#249 follow-up) #258 for the full list.
• LENS doesn't emit viral antigens directly in the columns we've seen (those are all host-encoded), so this would be primarily for users running vaxrank against a viral-aware predictor.
• Vaxrank-side: a `ViralAntigen` type (or just a generic `Antigen` superclass that `MutantProteinFragment` and `ViralAntigen` both inherit from) carrying `(virus_name, protein_name, position_in_protein)`.
• The construct assemblers consume `Antigen` rather than `MutantProteinFragment` directly.

3. CTA: tier-tagged self-protein with expression-based tumor-specificity

CTAs are normal self-proteins; tumor specificity comes from expression pattern (testis-restricted in healthy tissue, re-expressed in cancer). Plan:

• Bundle a CTA database tier table (CTA antigen database for on-target ligand classification (#249 follow-up) #257) keyed by gene name.
• A `CTAAntigen` type (sibling of `MutantProteinFragment` and `ViralAntigen`) carries `(gene_name, cta_tier, source_protein_aa)`.
• LENS `CTA/SELF` rows populate this — `gene_name` + `pep_context` already give us what we need; the tier comes from the CTA database.

4. ERV (endogenous retrovirus): structurally similar to viral

Each ERV ORF is its own peptide source. LENS columns `erv_orf_id`, `erv_*_cpm`, `erv_norm_exp_status` etc. give the provenance. Plan:

• An `ERVAntigen` type carrying `(erv_orf_id, erv_orf_aa, expression_metrics)`.
• LENS `ERV` rows populate this; `pep_context` becomes `source_protein_aa` (or a window of it).

5. Splice variants

LENS `SPLICE` rows have `splice_coords` (the junction) and `splice_description`. These are tougher because the peptide arises from an aberrant junction not present in any reference transcript. Two approaches:

• Treat as a `StructuralVariant` with `sv_type="BND"` between two splice donor/acceptor sites — same machinery as fusion.
• Or treat as a `SpliceAntigen` type with the junction info preserved.

Antigen abstraction

The cleanest long-term shape is a base `Antigen` interface that `MutantProteinFragment`, `ViralAntigen`, `CTAAntigen`, `ERVAntigen`, `SpliceAntigen` all implement. Construct assemblers (`peptide.py`, `mrna.py`) and reports operate on `Antigen` and don't care about the source. The variant-aware (`MutantProteinFragment`) path stays the default; the others are added as the data-model and clinical use cases warrant.

Suggested PR sequencing

• A. Fusion via `StructuralVariant` — smallest change, leverages existing varcode features. Land first.
• B. Antigen-source tagging on `MutantProteinFragment` (free-form metadata dict) — unblocks per-source filtering in reports without restructuring the data model. Land second.
• C. Full `Antigen` abstraction + viral / CTA / ERV / splice subtypes. Larger refactor; do after A and B settle.