Support VCF symbolic alleles and breakends as extended variant types
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/Duplicationclasses 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
- Parse INFO fields for SV context:
SVTYPE,END,SVLEN,CIPOS,CIEND,MATEID,CHR2/POS2,INSSEQ, etc. - Dispatch table for symbolic alleles:
<DEL>/<DEL:ME:*>→ SV Deletion (single-locus, large; fromSTARTtoEND)<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)
- Breakend pairing: match
MATEIDpairs and construct a single Translocation/Breakpoint (#257) from the pair rather than two half-breakends. - 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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