Link symbolic-allele and breakend records to the genes their REF span overlaps

[ecrum19]

Problem

The gene linkers' interval join returned no key for any record whose ALT is a symbolic allele (<DEL>, <DUP>, <INS:ME:ALU>, …) or a breakend (vcf_rdfizer_linking/runner.py). An unkeyed record has no gene link, so a vcfp:LinkedSelector never selects it. A prohibition on a gene panel therefore fails open for structural variants inside the panel's genes. This is the same class of gap that v3.3.1 closed for spanning-deletion * alleles (#32).

How it was found

vcf-rdfizer-testing experiment 17, arm 2, rerun with v3.3.1 on 104 high-coverage 1000 Genomes genomes. The rerun added a record-level check that compares the records each governed release view keeps against the bcftools baseline:

Requester	Purpose	Baseline	RDF route
clinical	DUO:0000043	421,991	421,991
cardio	DUO:0000007 (disease-specific research)	685,818	685,928 (+110)
biobank	DUO:0000042 (general research)	356,777	356,835 (+58)

Re-applying the baseline's rule to every record in the RDF route's decision log shows the cause. Every extra released record is a symbolic structural variant (66 <INS:ME:…>, 24 <DUP>, 20 <INS> for cardio) anchored inside a cancer-predisposition gene: BRCA2, WT1, NF2, STK11, TSC2, and others. None had a gene link. Carrier lists agreed throughout, because ClinVar does not match these records. Only the record counts showed the gap.

The other arms are unaffected: their inputs contain no symbolic or breakend records.

Change

• Interval join: every record whose REF is DNA bases now keys its REF span, anchor base included, whatever its ALT. Only a record whose REF is not bases is still skipped and counted in skipped_records.
• Not read: INFO/END and breakend mates. A structural variant therefore links to the genes its anchor lies in, not to every gene its extent reaches. The docs state this and point to a vcfp:RegionSelector where that matters. Linking by full extent would need its own coordinate policy, and is left for later.
• SPDI join: unchanged. Symbolic alleles and breakends have no allele sequence to express.
• Docs: datalinking.md, limitations.md (now including the arm-2 numbers), policy-demonstrator.md, and the ensembl-genes-grch38 and gene-demo linker READMEs.
• Tests:
  • The interval-key test now expects <DEL>, <INS:ME:ALU>, breakend and mixed ALTs to keep the REF span.
  • A non-base REF still keys nothing.
  • New end-to-end test: <DEL>, <INS:ME:ALU> and breakend records anchored in a gene link to it, and a <DUP> anchored outside does not.

Testing

python3 -m unittest discover -s test -p 'test_*.py'
Ran 1293 tests — OK (skipped=38)

Not in this PR

• No release. The BioMedSem 2026 manuscript keeps v3.3.1 and reports this as a limitation.

🤖 Generated with Claude Code

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!