ADD cau igvf-export: the guide design in the IGVF per-guide format

[emattei]

The fourth step. Alignment, annotation and element mapping between them know
everything the IGVF per-guide metadata format asks for; this assembles it
into igvf/guide_metadata.tsv.

The format is Format_for_Per-Guide_Metadata.pdf, IGVF document
f6a915a9-a6b8-4015-8aeb-236764976979, which files with content_type
"guide RNA sequences" must follow. Its conventions are the ones this package
already uses, and it pins ENSEMBL ids to GENCODE v43.

What a guide targets is derived, not believed

A design's category for an element is a hypothesis; the annotation is
evidence. A validated enhancer keeps its label, since that an element
regulates a gene is experimental knowledge no annotation supplies. Everything
else follows the format's own wording: within 2 kb of a protein-coding TSS is
a promoter, then exon, then intron, then distal element.

This is not pedantry. In a real 43,778-guide screen the design labelled 344
elements promoter; the genome agreed with all 300 that have a measured
gene, but of the other 44, 39 contained no TSS of any biotype — checked
against all 62,757 genes of v43 — and one sat 109 kb from the nearest.

type has to agree with genomic_element: positive control means a known
measurable effect, so a row claiming it while the element is an exon
contradicts itself.

One row per guide

guide_id must be unique, so a guide inside two overlapping elements names
the element sharing the most bases with its protospacer, ties broken by id.
putative_target_genes keeps every gene of every element it hit.

Tests

123 new, 689 in total, on synthetic elements placed among the annotation
fixtures' genes, with the mapping built by the real map_to_elements so the
input format cannot drift.

They found three faults, all fixed here: three path options escaped the
command line as tracebacks; a guide with two sites took its class from one
row and its element from another; and a guide absent from the mapping came
out targeting FALSE with type targeting.

What it fixes in a real submission

The lab's released IGVFFI2289OJBA has 2,365 of 6,982 spacers at 19 nt
against 20 nt coordinates, pam as the literal string NGG on all 4,667
targeting rows, and genomic_element, intended_target_name and
putative_target_genes 0% filled. This export cannot produce any of those.

🤖 Generated with Claude Code