Unified MultiOutcomeEffect / OutcomeSet generalization across splice, readthrough, germline, and RNA evidence

[iskandr]

Background

PR #292 introduces `SpliceOutcomeSet`, a multi-outcome wrapper for splice-disrupting variants. The same "one DNA event → multiple plausible proteins" pattern appears in several adjacent workstreams:

• Splice disruption (Prototype multi-effect candidates for splice-site variants #262, shipped in PR Prototype multi-effect splice outcome possibility sets (#262) #292) — exon skipping / intron retention / cryptic splice / normal splicing.
• RNA-level evidence (Incorporate RNA-level evidence for variant effects #259) — enumerate plausible splice outcomes from DNA, narrow to observed isoforms using RNA-seq.
• Germline-aware annotation (Germline-aware effect prediction (umbrella) #268, Sub-1 is [#268 Sub-1] GermlineAwareEffect data model #282) — the same somatic variant expressed against different germline backgrounds produces different haplotype-level outcomes.
• Phasing / cis-trans composition (Phasing: cis/trans-aware effect prediction for nearby variants #269) — two nearby variants on the same or different haplotypes produce different composite effects.
• Future: stop-loss with readthrough, alternative start codons, selenocysteine resolution (Check which apparent stop codons are actually selenocysteines #42).

Each of these will want to wrap an underlying effect in a set of plausible outcomes. Committing to the `SpliceOutcomeSet` name / shape pigeonholes the abstraction into splicing.

Scope

• Introduce a `MultiOutcomeEffect` protocol / base class (already added in PR Prototype multi-effect splice outcome possibility sets (#262) #292's follow-up as a minimal marker: `.candidates`, `.most_likely`, `.priority_class`).
• Rename / refactor `SpliceOutcomeSet` to inherit from it cleanly and expose splice-specific fields (`disrupted_signal_class`, `candidate_proteins`, etc.) as extensions of the generic surface.
• Design the `Candidate` side analogously — `SpliceCandidate` becomes a subclass of a generic `OutcomeCandidate` carrying `(outcome_label, plausibility, description, coding_effect, predicted_class_name)`.
• Consider integrating with `predict_variant_effects` uniformly: a single `multi_outcome=True` (or `outcome_sets=True`) kwarg that wraps any multi-outcome-capable effect, of which splice is the first implementation.
• Downstream consumers (isovar, vaxrank, neoantigen pipelines) write `isinstance(e, MultiOutcomeEffect)` rather than `isinstance(e, SpliceOutcomeSet)`, so future wrappers don't churn their filtering code.

Ordering

This should land after the foundational `MutantTranscript` refactor (#271) — the generic `MultiOutcomeEffect` is a good customer for a proper transcript-edit abstraction, and doing both at once collapses two refactors into one.

Related

• Prototype multi-effect candidates for splice-site variants #262 — multi-effect splice modeling (tracking issue, partial: splice piece shipped).
• Incorporate RNA-level evidence for variant effects #259 — RNA evidence; naturally uses the same shape.
• Germline-aware effect prediction (umbrella) #268 / [#268 Sub-1] GermlineAwareEffect data model #282 — germline-aware annotation; GermlineAwareEffect data model should share the protocol.
• Foundational refactor: MutantTranscript abstraction #271 — MutantTranscript foundation; dependency.
• PR Prototype multi-effect splice outcome possibility sets (#262) #292 — prototype that motivated this generalization.