openvax / openvax/varcode

Support VCF symbolic alleles and breakends as extended variant types

Open
#264 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
87
Forks
28
Avg merge
3h 27m
Merged PRs (30d)
27

Description

Background

VCF 4.0+ allows alternate alleles that are not literal nucleotide strings:

Symbolic alleles — placeholders inside angle brackets, with detail supplied in INFO:

  • <DEL> — deletion
  • <DUP> — duplication (tandem, dispersed)
  • <INS> — insertion of unspecified sequence
  • <INV> — inversion
  • <CN0>, <CN1>, <CN2>, <CN3>, ... — copy number states
  • <INS:ME:ALU>, <INS:ME:LINE1>, <INS:ME:SVA> — mobile element insertions
  • <DEL:ME:ALU> — deletion of a mobile element

Breakend (BND) notation — two-ended rearrangements joining distant loci:

  • G]17:198982] — G joined to position 17:198982, orientations encoded by bracket direction
  • ]17:198982]G, [13:123456[T, T[13:123456[ — variants for different orientations

Spanning deletion placeholder:

  • * — indicates an allele deleted by an upstream variant

Current state (after #88 is fixed in PR #XXX)

load_vcf() now detects these and skips them with a visible warning instead of crashing. This preserves the rest of the VCF but silently drops real variants that a user might care about.

Desired state

Represent these alleles as first-class variant types so downstream code (effect prediction, filtering, annotation export) can reason about them. This ties directly to the in-progress structural variant work:

  • openvax/varcode#257 defines the Breakpoint/Translocation/Inversion/Duplication classes with two-locus representation — exactly what BND and the large-scale symbolic alleles need
  • openvax/varcode#258 (external annotations) is how we'd import the SV type / copy number / inserted-sequence details that live in INFO fields
  • openvax/varcode#259 (RNA-level evidence) is how we'd determine the actual protein consequences, which for most SVs cannot be predicted from DNA alone

Implementation sketch

  1. Parse INFO fields for SV context: SVTYPE, END, SVLEN, CIPOS, CIEND, MATEID, CHR2/POS2, INSSEQ, etc.
  2. Dispatch table for symbolic alleles:
    • <DEL> / <DEL:ME:*> → SV Deletion (single-locus, large; from START to END)
    • <INS> / <INS:ME:*> → SV Insertion (with optional inserted sequence)
    • <INV> → Inversion (#257)
    • <DUP> → Duplication (#257)
    • <CN*> → CopyNumberVariant (new class, or subclass of Duplication/Deletion based on count)
  3. Breakend pairing: match MATEID pairs and construct a single Translocation/Breakpoint (#257) from the pair rather than two half-breakends.
  4. Spanning deletion *: represent as a reference to the variant that consumed the position, or skip with metadata (it's a placeholder, not an independent variant).

Relation to existing issues

  • #257 — SV types foundation (blocks this)
  • #258 — External annotations (needed for INFO-driven SV details)
  • #123 — Support loading structural variants (older request, superseded by the #261 roadmap)
  • #88 — crash fixed; visible warning added (this issue is the positive follow-up)

Contributor guide

Open the contributing guide

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.

Research direction

Start with load_vcf(), where symbolic alleles and breakends are currently detected and skipped, then review the structural-variant foundation in #257. Read #258 and #259 for the planned annotation and RNA-level dependencies. Done means the listed symbolic, breakend, and spanning-deletion forms are represented as first-class variants without silently dropping them.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
bioinformatics
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.