Support VCF symbolic alleles and breakends as extended variant types

[iskandr]

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:

• Add structural variant types (translocations, inversions, duplications, breakpoints) #257 defines the Breakpoint/Translocation/Inversion/Duplication classes with two-locus representation — exactly what BND and the large-scale symbolic alleles need
• Support externally generated variant annotations #258 (external annotations) is how we'd import the SV type / copy number / inserted-sequence details that live in INFO fields
• Incorporate RNA-level evidence for variant effects #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 (Add structural variant types (translocations, inversions, duplications, breakpoints) #257)
   • <DUP> → Duplication (Add structural variant types (translocations, inversions, duplications, breakpoints) #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 (Add structural variant types (translocations, inversions, duplications, breakpoints) #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

• Add structural variant types (translocations, inversions, duplications, breakpoints) #257 — SV types foundation (blocks this)
• Support externally generated variant annotations #258 — External annotations (needed for INFO-driven SV details)
• Support loading structural variants #123 — Support loading structural variants (older request, superseded by the Load structural variant sequences from Exacto #261 roadmap)
• varcode fails when it sees strange sequences in a vcf #88 — crash fixed; visible warning added (this issue is the positive follow-up)