Validate external annotation imports beyond the shipped RNA outcome resolver

Open
  • Is something wrong?
#258 0 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
35/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Quiet
Tech stack
python
Domain
backend-api-design, bioinformatics

Research direction

Start with predict_variant_effects() and the existing EffectCollection concepts, then review the Exacto fields position_1_annotation, position_2_annotation, and its transcript_model_id mappings. Done means externally supplied sets of effects can be attached to a variant, retain source and evidence metadata, coexist with predictions, and validate compatibility with the variant type.

Written by the indexing model from the issue text.

Description

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

The shared annotation/evidence machinery already exists: effect candidates carry source and evidence; RNAEvidence/RNAEvidenceResolver attach sets of externally supplied observations alongside DNA predictions; make_fusion_outcome validates a supplied structural RNA model; and native Exacto transcript/primary-structure imports retain original rows and multiple interpretations. See resolver and factories, RNA imports, and regressions. The annotator= hook also permits caller-supplied annotation strategies.

The remaining generalization is a validated import contract for other external annotation sources, not a need to invent effect sets or source metadata from scratch.

Remaining work

Specify concrete producer formats and their semantics, reusing the shared candidate/transcript model. Validate variant/reference/transcript identity, source coordinate conventions and sequence compatibility. Keep externally supplied interpretations separate from Varcode predictions, retain one-to-many results and original evidence, and expose unsupported/incompatible records explicitly.

Acceptance: at least one declared non-RNA external annotation format with native fixtures; incompatible variant/reference rejection; multiple outcomes and source metadata survive serialization; imported scores retain their producer meaning rather than becoming calibrated probabilities. Generic arbitrary annotations must not be mislabeled as observed RNA. The remaining Exacto adapters are tracked in #260.

Original request

Background

Varcode currently computes all variant effects internally via predict_variant_effects(), which walks PyEnsembl transcripts and predicts coding consequences from first principles. This works well for point variants where the genomic-to-protein mapping is deterministic, but breaks down for structural variants and complex events where:

  • The effect on the protein product may not be inferrable from the genomic rearrangement alone
  • External tools (e.g., Exacto, long-read RNA assemblers) have already determined the transcript structure and translated the resulting protein
  • Annotation requires RNA-level evidence that varcode doesn't have access to

Scope

Allow varcode to accept pre-computed annotations from external tools, rather than requiring all effects to be internally predicted.

Design considerations
  1. Annotation source tracking: effects should record how they were determined — internally predicted vs. externally provided, and from which tool/pipeline.
  2. Coexistence with prediction: for the same variant, a user might want both the internally predicted effect(s) and the externally provided one(s) (e.g., to compare DNA-only predictions against RNA-observed outcomes).
  3. Structured import API: provide a way to attach an EffectCollection (or individual effects) to a variant from external data, with validation that the effect is compatible with the variant type.
  4. Confidence/evidence metadata: external annotations may come with supporting evidence (read counts, transcript models, confidence scores) that should be preservable.
  5. Sets of effects, not single annotations: a single variant (especially an SV) can produce multiple distinct protein products via alternative splicing. External annotations should be importable as a set of observed or possible effects for one variant, not forced into a single "the effect" slot. This is especially important when importing Exacto results, where one DNA variant may link to multiple transcript models, each with its own primary structure.
Relevant context
  • Exacto produces annotated variant calls with gene/transcript/exon annotations (position_1_annotation, position_2_annotation columns) and per-amino-acid primary structure tables that trace each residue back to its source variant. Critically, Exacto's integration table maps one dna_variant_call_id to potentially many transcript_model_id entries, reflecting the multiple spliced isoforms a single DNA event can produce.
  • This is a prerequisite for meaningfully importing Exacto structural variant results, since varcode cannot internally predict the effect of most SVs.
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.