Complete RNA-path integration beyond shipped observed-structure and protein imports

Open
  • Is something wrong?
#259 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Active
Tech stack
python
Domain
bioinformatics

Research direction

Start by reading the existing SpliceDonor, SpliceAcceptor, ExonicSpliceSite, and EffectCollection implementations, then review related issue #252 and Exacto's transcript and integration-table context. Define how DNA predictions, RNA observations, transcript model IDs, read support, and multiple isoform outcomes coexist; done means the effect model supports the requested RNA-informed types and uncertainty without losing existing splice handling.

Written by the indexing model from the issue text.

Description

Current status (2026-10-26; Varcode 10.20.2)

The premise that Varcode only returns deterministic DNA-only effects is obsolete. Candidate/outcome sets, RNAEvidence, supplied mutant transcript structures, make_fusion_outcome, native Exacto fusion and primary-structure imports, and explicitly labelled reference-completion hypotheses are shipped. Multiple observed interpretations can coexist with DNA predictions; partial sequence and uncertain protein consequences are retained. See RNA structures and Exacto imports and library responsibilities.

The existing 9.1/9.2 release comments remain valid historical evidence. Newer APIs do not complete every original RNA-event class or all splice/phase/SV combinations. RNA reconstruction and read-based reconciliation belong in Isovar or another producer; Varcode consumes the resulting structures and predicts consequences.

Remaining work

Track the unimplemented path/model integrations explicitly: circular/back-spliced and multi-gene paths (#252/#260), broader native caller adapters, and composition of splice, phase and structural alternatives (#421/#423). Isovar's nominated-SV reconstruction/reconciliation is tracked in openvax/isovar#305 and #306.

Acceptance for each supported path must preserve nucleotide sequence/structure, reference/source coordinates, completeness, frame assumptions, all compatible transcript interpretations and DNA/RNA provenance through serialization and downstream consumption. Candidate counts or read counts are not calibrated probabilities. Local RNA evidence must not automatically establish full-length expression, abundance or translation. Missing coverage must remain distinct from evidence against a hypothesis.

Keep this umbrella open, but use the linked concrete gaps rather than treating observed-RNA import or outcome sets as wholly unimplemented.

Original request

Background

Varcode currently predicts variant effects purely from genomic (DNA) coordinates mapped against reference gene annotations. For many structural variants, the actual protein-level consequence cannot be reliably determined from WGS alone:

  • A genomic translocation may or may not produce a fusion transcript — this depends on whether the rearrangement is transcribed and how the resulting RNA is spliced
  • A fusion protein is obvious from RNA-seq even when the underlying genomic breakpoint is complex or ambiguous
  • RNA-level events (cryptic exons, exon truncations, intron retention, circular RNAs) have direct protein consequences that are invisible to DNA-only analysis
  • UTR extensions and alternative splicing around breakpoints can only be resolved with transcript-level data

Core modeling problem: one variant, many possible isoforms

A single DNA event — especially an SV — can produce multiple distinct spliced isoforms, each with a different protein consequence. Consider a translocation whose breakpoint falls in a non-coding region: depending on which cryptic splice sites are used, the resulting transcript could include different amounts of intronic/intergenic sequence, skip different exons, or frame-shift at different points. The set of possible protein products is combinatorial.

Without RNA evidence, the best we can do is enumerate a set of plausible splice outcomes based on nearby canonical and non-canonical splice signals, scored by likelihood. This is a departure from varcode's current approach, which returns a single deterministic effect per transcript. But it's the honest representation — a SpliceDonor effect today doesn't tell you what the resulting protein looks like, just that splicing is probably disrupted.

With RNA evidence, the possibility set collapses to what was actually observed: which isoforms are expressed, at what levels, producing which proteins. RNA data constrains and resolves the ambiguity that DNA-only analysis cannot.

This principle — DNA predicts possibilities, RNA resolves them — applies retroactively to existing splice-site variant handling (see "Implications for existing code" below), not just to new SV types.

Scope

Extend varcode's effect model to incorporate RNA-derived evidence, specifically:

New RNA-informed effect types
  • FusionTranscript / FusionProtein: chimeric transcript joining exons from two genes, with the resulting protein sequence
  • CircularRNA: back-spliced transcript forming a circle
  • CrypticExon: novel exon not present in reference annotations, often from sequence that was previously intronic or intergenic
  • ExonTruncation: partial exon usage at or near a breakpoint
  • IntronRetention: failure to splice out an intron, with protein consequence
  • UTRExtension: extended untranslated region altering regulation
Possibility-set model for splice effects
  • When predicting from DNA alone, splice-disrupting variants should produce a set of possible effects (e.g., "exon skip leading to frameshift," "cryptic donor activation leading to truncated exon," "intron retention leading to premature stop"), each with an estimated plausibility
  • When RNA evidence is available, this set is narrowed to the observed isoforms, with expression-level support
  • The EffectCollection for a single variant should be able to represent this uncertainty: "here are the N possible outcomes, here is which ones we observed"
Reference sequence beyond exons
  • Many novel isoforms incorporate sequence from outside annotated exonic regions — intronic sequence retained by intron retention, intergenic sequence recruited by a translocation, cryptic exons from previously non-coding regions
  • Effect prediction must be able to access genomic sequence around breakpoints and splice sites, not just the annotated exon sequences that current code uses
Evidence model
  • Record whether an effect was predicted from DNA (with associated uncertainty) vs. observed in RNA (with transcript model IDs and read support)
  • Allow both to coexist for the same variant — the DNA prediction set and the RNA observations
  • Distinguish between DNA/RNA concordant variants (seen in both) and RNA-only or DNA-only events
  • Link effects to supporting transcript model IDs and read evidence
Implications for existing splice-site effect handling

Today, SpliceDonor, SpliceAcceptor, and ExonicSpliceSite each return a single effect. ExonicSpliceSite has an alternate_effect field ("what happens if splicing isn't disrupted"), but this is one alternative, not a set of possibilities. We should consider evolving these to return or be expandable into a set of possible outcomes — this makes the existing model more honest and provides a natural place for RNA evidence to narrow the set.

Relevant context

  • Exacto identifies all of the above RNA variant types from long-read transcriptome assemblies, providing transcript structures, RNA variant calls, and DNA/RNA integrated variant tables.
  • Exacto's translate-structs command produces per-residue primary structure tables with rna_variant_call_ids and dna_variant_call_ids columns, providing the evidence linkage.
  • Exacto's integration table shows one dna_variant_call_id mapping to multiple transcript_model_id entries — directly reflecting the one-DNA-event-to-many-isoforms relationship.
  • Related: #252 (gene fusion effects) — this issue provides the broader RNA-evidence framework that fusion support would fit within.
Dominant language
Python
Stars
88
Forks
28
Avg merge
2h 11m
Merged PRs (30d)
45

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from openvax/varcode

All issues in openvax/varcode

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.