Metabolite → gene links: metabolite_linked_convergence tier

[sr320]

Why

The multi_omics_convergence tier links layers only by an identical feature_id_standardized. Metabolite evidence is standardized to the metabolite name, so it could never converge with RNA-seq, methylation or proteomics evidence. CLAUDE.md requires "a transparent explanation of how molecular layers were linked".

What

The design is in docs/metabolite_gene_links.md. The decisions were confirmed before building: builder only (no KEGG table committed), no change to the score, a new fourth tier, and two demo genes.

• Link chain: metabolite name → KEGG compound (curated data/mappings/metabolite_compound_map.tsv) → KEGG reaction → KO → crg gene (NCBI GeneID, checked against the RS_2024_06 crosswalk and the retired-ID sidecar). Original identifiers are untouched, and the evidence schema is unchanged.
• Confidence: links are never exact or one_to_one_ortholog. Ambiguous names such as lactate (L- and D-lactate) give inferred. Currency metabolites (ATP, NAD⁺, …; currency_metabolites.yaml) and hub compounds (> 25 genes) are shown on cards but never credited.
• Ranking: a new tier, metabolite_linked_convergence, after multi_omics_convergence and before emerging.
  • The candidate's own layer must be significant, and a linked feature must be significant in another layer under the same phenotype and partition.
  • Linked layers do not count in n_supporting_layers or the score.
  • New fields: convergence_basis, linked_layers, linked_features, link_confidences, link_table_status, link_table_sha256.
• Evidence cards get a section headed "Metabolite–gene links (biochemical; weaker than shared gene identity)". It shows the compound/reaction/KO chain per row, link confidence, the table checksum, a different-stressor caveat, and the excluded compounds.
• Provenance: the simulated demo table and its sidecar are committed. The real table is built locally by aree build-metabolite-links / make metabolite-links. Every KEGG response is cached with its sha256, and the sidecar validates against schemas/metabolite_gene_links_provenance.schema.json. The real table is git-ignored because KEGG does not clearly permit redistribution.
• Demo: fabricated ldh (significant) and sdha (not significant) genes were added to the demo crosswalk and the GIGAS_HEAT01 chronic table. The results:
  • GIGAS_GROW06 lactate ↔ ldh → metabolite_linked_convergence (2 candidates).
  • succinate/sdha and ATP stay emerging.

Real-data check (local, not committed)

The first KEGG build gave 191 links. 10,875 of 10,879 crg genes resolve to current GeneIDs; the 4 unresolved are rRNA/tRNA pseudo-IDs. Pyruvate is a hub. No crg gene carries L-LDH (K00016), so lactate links only through D-lactate. No real candidate is linked yet, because the only real metabolomics study (DUPERRET2025_POMS_STARVE, #70) failed QC.

Testing

• pytest: 640 passed, both with and without the locally built real table (CI has no table). This includes 27 new tests in tests/test_metabolite_links.py, which cover confidence rules, hub and currency exclusion, partition isolation, tier gates, score invariance, cards, and the builder against a fake KEGG including an offline rebuild.
• ruff check src tests scripts modules/shared: clean.
• make demo-clean succeeds. quarto render docs/ renders the new page, checked from a copy, because Quarto renders nothing inside the hidden .claude/ worktree path.

Update: transporter links via KEGG BRITE ko02000

• ko02000 records no substrates. It classifies about 1,070 KOs into transporter families but carries no compound IDs. The KO → compound step is therefore curated in data/mappings/transporter_substrates.tsv: 43 rows, each with substrate_basis (ko_definition / substrate_class), the human ortholog it rests on, and a note.
• What the builder does with ko02000: it fetches get/br:ko02000, rejects any curated KO that isn't in it, records each KO's family path as brite_family, and lists curated KOs that have no crg gene.
• Confidence and cap: transporter links are always inferred. The 25-gene hub cap is applied per link type, so transporter links never remove a compound's enzyme-link credit.
• Cards show link type, basis and BRITE family, plus a paragraph explaining that transporter links rest on curation.
• Demo: results are unchanged; the demo table only gained the two new columns. The transporter path is covered by synthetic tests, including a rendered card.
• First local build (not committed): 191 enzyme + 58 transporter links. 33 curated KOs were found in ko02000 and 0 rejected; 22 have no crg gene. (S)-lactate has no L-LDH enzyme link, but now links through MCT/SMCT transporters (9 genes).
• pytest: 644 passed, with and without the local table. ruff: clean.

🤖 Generated with Claude Code