Discover variant-created ORF starts and extend partial-product annotation

Open
  • Is something wrong?
#583 1 comment 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
12/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
bioinformatics, python
Domain
bioinformatics

Research direction

Start by reading how effect_prediction.py and transcript_layout.py assign FivePrimeUTR to variants in the canonical 5-prime UTR, then trace how MutantTranscript builds alternate products. The issue is a multi-stage design (ORF model provider, per-ORF effects, splice and fusion products, start-gain search), so a newcomer should first agree the scope with maintainers. Done means the first acceptance step: REF-validated SNVs and indels in a supplied ORF model get an additive per-ORF effect while canonical effects stay unchanged, with tests for minus strand and +4 dual effects.

Written by the indexing model from the issue text.

Description

Current status (audited 2026-10-27)

Much of the original request is implemented on main at 67ea545. Keep this issue for the remaining discovery and product-coverage work, rather than recreating the ORF annotation API.

Already implemented
  • Variant.effects(extra_orfs=...) and VariantCollection.effects(extra_orfs=...) retain ordinary transcript consequences alongside supplied reference-ORF effects, including upstream/overlapping/internal/downstream frames and noncoding host transcripts.
  • The existing transcript-model engine handles supported substitutions/indels, initiation-context changes (including the +4 coding/context overlap), source-declared non-AUG starts, patient germline hypotheses and known-cis products. Supported realized splice/structural and explicitly mapped RNA products retain separate outcomes and evidence.
  • Native JSON/CSV and Proteome exports retain source/reference identities, alternative products and unavailable outcomes. Reference translation evidence does not become observed mutant translation or presentation evidence.
  • Annotated and source-defined TranscriptORF inputs and local variants in partial models with a validated coding frame are available. Unknown boundaries/frames and unsupported calculations stay explicit.

Evidence: current API guide, ordinary/extra-ORF integration regressions, non-AUG regressions, and partial/source-defined models.

Remaining work
  1. Bounded discovery of variant-created starts/ORFs. Current exports explicitly say discovery.status = reference_models_only and new_starts = not_assessed. Search changed sequence under a declared policy and bounds; retain baseline versus mutant candidates and partial/unavailable sequence. An empty supplied catalogue is not evidence of no ORF, and a new sequence candidate is not evidence of translation.
  2. Extend specific unsupported partial-product cases where the supplied evidence is sufficient. Partial-codon/boundary edits, partial germline/splice/structural composition and mapped partial RNA products currently return explicit unavailable outcomes. Identify supported subsets with independent regressions; preserve unknown frames, missing sequence and unsupported recoding instead of inventing complete products. Coordinate mapped partial-SV interpretation with #466 and shared product composition with #423.
  3. Retain the established export/evidence contract for those additions. Keep source placements, phase alternatives, initiation-context coverage, affected/native intervals and unavailable reasons. Downstream main-CDS regulation remains unassessed unless separately modeled.

The original requirements and primary scientific references are preserved below. Their supplied-model annotation, context and serialization items are now regression obligations, not a request for a new parallel engine.

Original scope and scientific references

Variants confined to the canonical 5-prime UTR currently receive FivePrimeUTR in effect_prediction.py and transcript_layout.py, even when they alter an experimentally supported upstream ORF. A uORF start loss, missense, frameshift or stop loss needs its own transcript/ORF-specific consequence alongside the canonical label. Likewise +4 can change both initiation context and a coding residue.

Proposed organization

Keep four independent layers:

  1. Model identity: assembly, transcript + version/release, ORF ID, ordered coding blocks, start/stop positions and reference sequence.
  2. Location: start-context positions (A of ATG = +1, no zero), start codon, coding body, stop codon, and splice path. Roles can overlap.
  3. Sequence consequence: reference/alternate codons and proteins, start gained/lost/changed, synonymous/missense/stop gained/lost, frame change, and altered splice products. A start-codon loss does not prove translation absence; alternative/near-cognate initiation remains a hypothesis. Kozak context is a loose positional prior, never an exclusion criterion or calibrated probability.
  4. Evidence: published Ribo-seq/MS mapped to the exact reference model/residues, patient RNA support, and observed mutant translation/HLA presentation. Missing evidence stays unknown. Native peptides cannot validate a new fusion tail. Downstream main-CDS regulation remains unassessed unless independently modeled.

Clean API and dependency direction

Add a small ORFModel / ORFModelProvider protocol or neutral JSON interchange in Varcode (or a shared lower-level package), without introducing a Varcode -> Isovar dependency. Isovar's offline catalogue can supply models/evidence to that protocol. Model lookups must pin assembly/annotation and resolve the entire spliced coding path + sequence, rather than transfer evidence by gene or unversioned transcript ID alone.

Expose additive per-ORF annotation (for example variant.orf_effects(provider=...)), preserving existing canonical effects. Return every compatible ORF and transcript outcome; retain model IDs in collection identity and export. Reuse the existing transcript-layout, MutantTranscript and effect-hypothesis pipeline with an explicit alternative ORF frame rather than a second annotation engine.

Implementation order / acceptance criteria

  1. REF-validated SNVs/MNVs and indels in supplied ORF models; genomic forward-strand alleles converted into transcript orientation. Include separate Kozak/context annotations and permit partial/missing positions. +4 has both context and coding effects.
  2. Translate affected coding paths, preserving start/stop/frame uncertainty and incomplete downstream sequence. Explicitly identify altered protein intervals and retained native intervals. Report unsupported events as unresolved, not generic silent/noncoding results.
  3. Recompute contexts/frames on realized splice, fusion and rearranged transcript products using existing hypothesis machinery; retain source placements and unknown bases. Compose patient germline/somatic haplotypes and phased edits before translation. Separate model-supported starts from newly created sequence-only candidates.
  4. Add start-gain discovery around changed sequence with explicit search bounds and unavailable/full-scan status; don't infer no uORF from an empty reference catalogue.
  5. Export lossless JSON with model/source pins, reference/alternate products, alternative hypotheses, evidence overlays and why an annotation is unresolved.

Tests should cover minus strand, a start codon/context spanning exons, partial Kozak context, ATG at the first three supplied bases with unverified biological 5-prime completeness, REF mismatch, +4 dual effects, start/stop loss, frameshifts, splice/fusion products, ambiguous phase and compatible isoforms with conflicting effects.

Existing work and primary sources

Isovar #468 adds pinned reference initiation contexts, loose per-position preferences and REF-validated context SNVs: https://github.com/openvax/isovar/issues/468
The evidence catalogue shipped in Isovar #467: https://github.com/openvax/isovar/pull/467
Compose with Varcode #423 and #574 rather than creating an independent uncertainty/export path.

Primary sources:

Dominant language
Python
Stars
88
Forks
28
Avg merge
3h 10m
Merged PRs (30d)
53

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.