Add protein/chemical overlap report

[gaurav]

Inventories the cross-references that bridge the chemical/protein boundary, so the Translator community can review which protein and chemical cliques a merge would combine. This is the empirical input to the "list of mappings that would be applied if we combined proteins and chemicals" called for in #706, and a generalization of the UMLS-only report proposed in #667.

What it does

generate_protein_chemical_overlap_report() streams the chemical compendia, the protein compendium, and every concord file, and finds concord edges whose two endpoints landed in different cliques — one chemical, one protein. It writes four TSVs under babel_outputs/reports/protein_chemical/:

• candidate_pairs.tsv — deduplicated (chemical leader → protein leader) merge candidates with supporting sources/predicates aggregated and sorted by evidence. The SSSOM-able mapping list a DrugProtein conflation (A possible solution to the protein/chemical overlap problem (DrugProtein conflation) #440) would apply.
• bridges.tsv — one row per boundary-crossing concord edge, source-attributed (raw evidence).
• duplicate_curies.tsv — CURIEs in both a chemical and a protein clique (An ID can be present in multiple cliques (CURIE duplication) #276/MeSH, DrugBank and UMLS identifiers sometimes duplicate between ChemicalEntity and Protein clique #513). Scoped to concord-referenced CURIEs to keep memory bounded; the exhaustive list is a one-query lookup against the DuckDB Edge table.
• summary.tsv — per-source counts with the discriminator splits and a TOTAL row.

Each candidate carries two triage discriminators:

• chem_has_inchikey — a structurally-defined chemical cross-referenced to a protein is usually a bug (e.g. CHEBI:24536 "Pepsin" actually being hexachlorocyclohexane); the genuine protein-as-chemical cases have no InChIKey.
• prot_reaches_gene — whether merging would make a chemical normalize all the way to a gene (the Proteins and chemicals are being combined in potentially confusing ways #662 concern), derived from the GeneProtein conflation.

Memory is bounded by concord size: only CURIEs referenced by a concord are indexed, so the large compendia are streamed rather than held in RAM.

Changes

• src/reports/protein_chemical_overlap.py — core module.
• tests/reports/test_protein_chemical_overlap.py — unit tests on synthetic fixtures (InChIKey vs no-InChIKey crossings, duplicate CURIE, gene-reaching protein, no-conflation path).
• src/snakefiles/reports.snakefile — rule generate_protein_chemical_overlap_report, gated on outputs_done and registered under all_reports.
• docs/reports/ProteinChemicalOverlap.md (+ README index entry) — purpose, discriminators, outputs, how to run against a downloaded build, and a future-work section.

Follow-up

The natural next step is a conflation-chain impact simulator that consumes candidate_pairs.tsv and shows before/after normalization for a probe set — tracked in #829.

Status / notes

• ruff check, ruff format --check, snakefmt --check, rumdl all clean; unit tests pass.
• Not yet validated against a real build — the logic is exercised by unit fixtures only. Running it against a downloaded babel_outputs/ (e.g. the stars.renci.org snapshot) and sanity-checking the top candidate pairs is a good pre-merge step. Draft until then.

Related: #706, #667, #662, #654, #513, #440, #276.

🤖 Generated with Claude Code