Metabolite → gene links: transporter links via KEGG BRITE ko02000

README.md

@@ -151,7 +151,7 @@ AREE/
 | `aree build-evidence-cards [--phenotype <p>] [--feature-type <t>] [--max-adjusted-p <q>] [--all-cards]` | Rank every candidate into `reports/evidence_cards/candidates.tsv` and write an evidence card for each one with a BH-adjusted p ≤ `q` (default 0.05, pooled or in any contributing study) |
 | `aree top-candidates [--n <N>] [--candidates <path>] [--out <path>]` | Regroup an existing `candidates.tsv` by phenotype and write the top `N` (default 10) per phenotype, ranked by tier then score, to `reports/top_candidates_summary.md` |
 | `aree build-crosswalk --taxid <n> [--slug <s>]` | Build a real identifier crosswalk from NCBI Gene + UniProtKB for a registered species |
-| `aree build-metabolite-links [--offline]` | Build the real *C. gigas* metabolite → enzyme gene link table from the KEGG REST API (curated compounds only; output is git-ignored, not redistributed). See [docs/metabolite_gene_links.md](docs/metabolite_gene_links.md) |
+| `aree build-metabolite-links [--offline]` | Build the real *C. gigas* metabolite → enzyme / transporter gene link table from the KEGG REST API and BRITE ko02000 (curated compounds only; output is git-ignored, not redistributed). See [docs/metabolite_gene_links.md](docs/metabolite_gene_links.md) |
 | `aree fetch-reference --assembly <acc> [--genome] [--proteins] [--plan] [--check]` | Fetch, verify and record a RefSeq reference bundle (transcriptome, GTF, tx2gene, optional genome, optional one-protein-per-gene proteome) |
 | `aree build-orthogroups --orthofinder <path> [--threads N] [--activate]` | Infer orthogroups across every species with a crosswalk (OrthoFinder on RefSeq proteomes); writes `data/reference/orthogroups/<run_id>/` |
 | `aree build-dashboard [--out <path>]` | Summarize registry, pipeline, and findings state into `docs/dashboard/data.json` (plus the top candidates' evidence cards) for the Quarto dashboard page |

data/demo/metabolomics/GIGAS_GROW06_hypoxia_vs_control_metabolite_features_demo.tsv

@@ -5,4 +5,4 @@ M003	glycine_betaine	2	osmolyte	-0.50	0.1800	0.2500
 M004	succinate	1	organic_acid	1.50	0.0025	0.0100
 M005	unknown_feature_881	3	unknown	0.90	0.0600	0.1000
 M006	alanine	2	amino_acid	0.70	0.0450	0.0800
-M007	glucose	1	carbohydrate	-0.90	0.0210	0.0500
+M007	glucose	1	carbohydrate	-0.90	0.0060	0.0200

data/demo/rnaseq/GIGAS_HEAT01_chronic_heat_vs_control_dge_demo.tsv

@@ -9,3 +9,4 @@ LOC105331241	910.2	0.30	0.30	1.00	0.3170	0.4000
 LOC105329871	701.3	0.20	0.31	0.65	0.5160	0.6000
 LOC105342001	1520.3	1.05	0.30	3.50	0.0005	0.0100
 LOC105342002	840.7	0.25	0.31	0.81	0.4200	0.5200
+LOC105342003	980.4	0.95	0.29	3.28	0.0010	0.0200

data/mappings/gene_id_crosswalk.tsv

@@ -40,3 +40,4 @@ LOC105340020	ENSCGRG00000020	K1QQ20	LOC105340020	atp1a_nka	OG0000020
 LOC105341000	ENSCGRG00000021	K1QQ21	LOC105341000	actin	OG0000021
 LOC105342001	ENSCGRG00000022	K1QQ22	LOC105342001	ldh	OG0000022
 LOC105342002	ENSCGRG00000023	K1QQ23	LOC105342002	sdha	OG0000023
+LOC105342003	ENSCGRG00000024	K1QQ24	LOC105342003	glut1	OG0000024

data/mappings/metabolite_gene_links_demo.provenance.json

@@ -1,18 +1,23 @@
 {
   "artifact": "metabolite_gene_links_demo.tsv",
-  "artifact_sha256": "2156a4428d9a46ea18f979cccff155ed280c5ca666414f2143c9181b9850d3f0",
+  "artifact_sha256": "2e19208c611d8f6e45d337f9e84e3ea6f1f16c2f148b3eff1504adcc36fe5129",
   "simulated": true,
   "builder": "hand-written demo fixture",
   "date_generated": "2026-10-16",
   "ncbi_taxid": 29159,
   "organism": "Magallana gigas (Crassostrea gigas) \u2014 SIMULATED demo partition only",
-  "source_summary": "SIMULATED demo links; real KEGG reaction/KO IDs, fabricated gene IDs",
+  "source_summary": "SIMULATED demo links; real KEGG reaction/KO/BRITE IDs, fabricated gene IDs",
   "reference_annotation": "cgigas_annotation_v1_demo (fabricated demo crosswalk, data/mappings/gene_id_crosswalk.tsv)",
   "sources": [
     {
       "name": "KEGG REST (identifiers only, checked by hand)",
       "url": "https://rest.kegg.jp/get/R00703+R02164",
       "accessed": "2026-10-16"
+    },
+    {
+      "name": "KEGG BRITE ko02000 (family path for K07299, checked by hand)",
+      "url": "https://rest.kegg.jp/get/br:ko02000",
+      "accessed": "2026-10-17"
     }
   ],
   "max_genes_per_compound": 25,

data/mappings/metabolite_gene_links_demo.tsv

@@ -1,9 +1,10 @@
 # SIMULATED DEMO metabolite -> gene link table. The gene IDs are the FABRICATED demo LOC numbers
 # from data/mappings/gene_id_crosswalk.tsv and must never be read as real C. gigas genes. The KEGG
-# compound, reaction and KO identifiers are real KEGG identifiers (checked 2026-10-16); only the
-# KO -> gene assignment is fabricated. Never merge with a real table (metabolite_gene_links_mgigas.tsv).
+# compound, reaction and KO identifiers are real KEGG identifiers (checked 2026-10-16), as is the GLUT1
+# BRITE ko02000 family path (2026-10-17); only the KO -> gene assignment is fabricated. Never merge with a real table (metabolite_gene_links_mgigas.tsv).
 # Columns are the same contract `aree build-metabolite-links` writes. See docs/metabolite_gene_links.md.
-kegg_compound	compound_name	kegg_reaction	equation_side	ko	ncbi_gene_id	link_type
-C00186	(S)-Lactate	R00703	left	K00016	LOC105342001	enzyme
-C00022	Pyruvate	R00703	right	K00016	LOC105342001	enzyme
-C00042	Succinate	R02164	left	K00234	LOC105342002	enzyme
+kegg_compound	compound_name	kegg_reaction	equation_side	ko	ncbi_gene_id	link_type	link_basis	brite_family
+C00186	(S)-Lactate	R00703	left	K00016	LOC105342001	enzyme	kegg_reaction	
+C00022	Pyruvate	R00703	right	K00016	LOC105342001	enzyme	kegg_reaction	
+C00042	Succinate	R02164	left	K00234	LOC105342002	enzyme	kegg_reaction	
+C00031	D-Glucose			K07299	LOC105342003	transporter	ko_definition	Solute carrier family (SLC) > SLC2: Facilitative GLUT transporter; Major facilitator superfamily (MFS) > Sugar transporters > Sugar porter (SP) family [TC:2.A.1.1]

data/mappings/transporter_substrates.tsv

@@ -0,0 +1,54 @@
+# Curated transporter KO -> substrate compound assignments for metabolite -> gene TRANSPORTER links.
+# KEGG BRITE ko02000 (Transporters) classifies KOs into transporter families but records NO substrate
+# compounds, so the substrate is a curation step, recorded here row by row. `aree build-metabolite-links`
+# checks every KO below against ko02000 (a KO absent from ko02000 is rejected and listed in provenance).
+# substrate_basis:
+#   ko_definition    the KEGG KO definition itself names the compound (e.g. "facilitated glucose transporter")
+#   substrate_class  the definition names a substrate class (e.g. "monocarboxylic acid"); the compound is the
+#                    curator's call from the characterized human members, given in human_ortholog
+# Every transporter link is 'inferred': substrate specificity of the oyster ortholog has not been measured.
+# Only compounds that are also in metabolite_compound_map.tsv are used. See docs/metabolite_gene_links.md.
+ko	kegg_compound	substrate_basis	human_ortholog	note	curator	date_curated
+K07299	C00031	ko_definition	SLC2A1/GLUT1	KO definition: facilitated glucose transporter.	aree_curator	2026-10-17
+K07593	C00031	ko_definition	SLC2A2/GLUT2	KO definition: facilitated glucose transporter.	aree_curator	2026-10-17
+K08142	C00031	ko_definition	SLC2A3/GLUT3	KO definition: facilitated glucose transporter.	aree_curator	2026-10-17
+K07191	C00031	ko_definition	SLC2A4/GLUT4	KO definition: facilitated glucose transporter.	aree_curator	2026-10-17
+K08144	C00031	ko_definition	SLC2A6/GLUT6	KO definition: facilitated glucose transporter.	aree_curator	2026-10-17
+K08145	C00031	ko_definition	SLC2A8/GLUT8	KO definition: facilitated glucose transporter.	aree_curator	2026-10-17
+K08147	C00031	ko_definition	SLC2A10/GLUT10	KO definition: facilitated glucose transporter.	aree_curator	2026-10-17
+K08148	C00031	ko_definition	SLC2A11/GLUT11	KO definition: facilitated glucose transporter.	aree_curator	2026-10-17
+K08149	C00031	ko_definition	SLC2A12/GLUT12	KO definition: facilitated glucose transporter.	aree_curator	2026-10-17
+K08143	C00031	ko_definition	SLC2A5/GLUT5	KO definition: glucose/fructose; human GLUT5 is mainly a fructose transporter.	aree_curator	2026-10-17
+K12201	C00031	ko_definition	SLC2A7/GLUT7	KO definition: glucose/fructose.	aree_curator	2026-10-17
+K08146	C00031	ko_definition	SLC2A9/GLUT9	KO definition names glucose, but human GLUT9 is chiefly a urate transporter.	aree_curator	2026-10-17
+K14158	C00031	ko_definition	SLC5A1/SGLT1	KO definition: sodium/glucose cotransporter.	aree_curator	2026-10-17
+K14382	C00031	ko_definition	SLC5A2/SGLT2	KO definition: sodium/glucose cotransporter.	aree_curator	2026-10-17
+K14389	C00031	ko_definition	SLC5A9/SGLT4	KO definition: sodium/glucose cotransporter.	aree_curator	2026-10-17
+K14390	C00031	ko_definition	SLC5A10/SGLT5	KO definition: sodium/glucose cotransporter.	aree_curator	2026-10-17
+K14384	C00031	ko_definition	SLC5A4/SGLT3	KO definition: low-affinity sodium-glucose cotransporter; human SGLT3 acts mainly as a glucose sensor.	aree_curator	2026-10-17
+K08175	C00031	ko_definition	SLC60A2/MFSD4B/NaGLT1	KO definition: Na+-dependent glucose transporter.	aree_curator	2026-10-17
+K08179	C00186	substrate_class	SLC16A1/MCT1	KO definition says 'monocarboxylic acid transporter'; MCT1-4 are the characterized proton-linked lactate/pyruvate carriers in vertebrates. Other SLC16 members (thyroid hormone, aromatic amino acid, creatine) are deliberately excluded. Lactate stereoisomers both mapped: MCTs carry L- and D-lactate.	aree_curator	2026-10-17
+K08179	C00256	substrate_class	SLC16A1/MCT1	KO definition says 'monocarboxylic acid transporter'; MCT1-4 are the characterized proton-linked lactate/pyruvate carriers in vertebrates. Other SLC16 members (thyroid hormone, aromatic amino acid, creatine) are deliberately excluded. Lactate stereoisomers both mapped: MCTs carry L- and D-lactate.	aree_curator	2026-10-17
+K08179	C00022	substrate_class	SLC16A1/MCT1	KO definition says 'monocarboxylic acid transporter'; MCT1-4 are the characterized proton-linked lactate/pyruvate carriers in vertebrates. Other SLC16 members (thyroid hormone, aromatic amino acid, creatine) are deliberately excluded. Lactate stereoisomers both mapped: MCTs carry L- and D-lactate.	aree_curator	2026-10-17
+K08184	C00186	substrate_class	SLC16A7/MCT2	KO definition says 'monocarboxylic acid transporter'; MCT1-4 are the characterized proton-linked lactate/pyruvate carriers in vertebrates. Other SLC16 members (thyroid hormone, aromatic amino acid, creatine) are deliberately excluded. Lactate stereoisomers both mapped: MCTs carry L- and D-lactate.	aree_curator	2026-10-17
+K08184	C00256	substrate_class	SLC16A7/MCT2	KO definition says 'monocarboxylic acid transporter'; MCT1-4 are the characterized proton-linked lactate/pyruvate carriers in vertebrates. Other SLC16 members (thyroid hormone, aromatic amino acid, creatine) are deliberately excluded. Lactate stereoisomers both mapped: MCTs carry L- and D-lactate.	aree_curator	2026-10-17
+K08184	C00022	substrate_class	SLC16A7/MCT2	KO definition says 'monocarboxylic acid transporter'; MCT1-4 are the characterized proton-linked lactate/pyruvate carriers in vertebrates. Other SLC16 members (thyroid hormone, aromatic amino acid, creatine) are deliberately excluded. Lactate stereoisomers both mapped: MCTs carry L- and D-lactate.	aree_curator	2026-10-17
+K08185	C00186	substrate_class	SLC16A8/MCT3	KO definition says 'monocarboxylic acid transporter'; MCT1-4 are the characterized proton-linked lactate/pyruvate carriers in vertebrates. Other SLC16 members (thyroid hormone, aromatic amino acid, creatine) are deliberately excluded. Lactate stereoisomers both mapped: MCTs carry L- and D-lactate.	aree_curator	2026-10-17
+K08185	C00256	substrate_class	SLC16A8/MCT3	KO definition says 'monocarboxylic acid transporter'; MCT1-4 are the characterized proton-linked lactate/pyruvate carriers in vertebrates. Other SLC16 members (thyroid hormone, aromatic amino acid, creatine) are deliberately excluded. Lactate stereoisomers both mapped: MCTs carry L- and D-lactate.	aree_curator	2026-10-17
+K08185	C00022	substrate_class	SLC16A8/MCT3	KO definition says 'monocarboxylic acid transporter'; MCT1-4 are the characterized proton-linked lactate/pyruvate carriers in vertebrates. Other SLC16 members (thyroid hormone, aromatic amino acid, creatine) are deliberately excluded. Lactate stereoisomers both mapped: MCTs carry L- and D-lactate.	aree_curator	2026-10-17
+K08180	C00186	substrate_class	SLC16A3/MCT4	KO definition says 'monocarboxylic acid transporter'; MCT1-4 are the characterized proton-linked lactate/pyruvate carriers in vertebrates. Other SLC16 members (thyroid hormone, aromatic amino acid, creatine) are deliberately excluded. Lactate stereoisomers both mapped: MCTs carry L- and D-lactate.	aree_curator	2026-10-17
+K08180	C00256	substrate_class	SLC16A3/MCT4	KO definition says 'monocarboxylic acid transporter'; MCT1-4 are the characterized proton-linked lactate/pyruvate carriers in vertebrates. Other SLC16 members (thyroid hormone, aromatic amino acid, creatine) are deliberately excluded. Lactate stereoisomers both mapped: MCTs carry L- and D-lactate.	aree_curator	2026-10-17
+K08180	C00022	substrate_class	SLC16A3/MCT4	KO definition says 'monocarboxylic acid transporter'; MCT1-4 are the characterized proton-linked lactate/pyruvate carriers in vertebrates. Other SLC16 members (thyroid hormone, aromatic amino acid, creatine) are deliberately excluded. Lactate stereoisomers both mapped: MCTs carry L- and D-lactate.	aree_curator	2026-10-17
+K14388	C00186	substrate_class	SLC5A8/SLC5A12 (SMCT1/2)	KO definition: sodium-coupled monocarboxylate transporter; human SMCTs carry lactate and pyruvate.	aree_curator	2026-10-17
+K14388	C00256	substrate_class	SLC5A8/SLC5A12 (SMCT1/2)	KO definition: sodium-coupled monocarboxylate transporter; human SMCTs carry lactate and pyruvate.	aree_curator	2026-10-17
+K14388	C00022	substrate_class	SLC5A8/SLC5A12 (SMCT1/2)	KO definition: sodium-coupled monocarboxylate transporter; human SMCTs carry lactate and pyruvate.	aree_curator	2026-10-17
+K08178	C00186	ko_definition	JEN (fungal)	KO definition: lactate transporter.	aree_curator	2026-10-17
+K14445	C00042	substrate_class	SLC13A2/3/5 (NaDC1, NaDC3, NaCT)	KO definition: sodium-dependent dicarboxylate transporter; NaDC1/3 carry succinate (NaCT prefers citrate).	aree_curator	2026-10-17
+K13577	C00042	substrate_class	SLC25A10/DIC	KO definition: mitochondrial dicarboxylate transporter; human DIC exchanges malate/succinate for phosphate.	aree_curator	2026-10-17
+K05045	C00719	ko_definition	SLC6A12/BGT1	KO definition: betaine/GABA transporter.	aree_curator	2026-10-17
+K14990	C00041	substrate_class	SLC38A1/SNAT1	KO definition: sodium-coupled neutral amino acid transporter; system A members, for which alanine is the canonical substrate. System N members (SNAT3/5) excluded.	aree_curator	2026-10-17
+K14207	C00041	substrate_class	SLC38A2/SNAT2	KO definition: sodium-coupled neutral amino acid transporter; system A members, for which alanine is the canonical substrate. System N members (SNAT3/5) excluded.	aree_curator	2026-10-17
+K14991	C00041	substrate_class	SLC38A4/SNAT4	KO definition: sodium-coupled neutral amino acid transporter; system A members, for which alanine is the canonical substrate. System N members (SNAT3/5) excluded.	aree_curator	2026-10-17
+K05615	C00041	substrate_class	SLC1A4/ASCT1	KO definition: neutral amino acid transporter; ASC system (alanine, serine, cysteine).	aree_curator	2026-10-17
+K05616	C00041	substrate_class	SLC1A5/ASCT2	KO definition: neutral amino acid transporter; ASC system (alanine, serine, cysteine).	aree_curator	2026-10-17
+K14209	C00041	substrate_class	SLC36A/PAT	KO definition: proton-coupled amino acid transporter; PAT1/2 carry alanine, proline and glycine.	aree_curator	2026-10-17

docs/identifier_mapping.md

@@ -397,7 +397,9 @@ annotations.
 Metabolite evidence keeps the reported metabolite name as its
 `feature_id_standardized`; it is never forced into the gene hierarchy above.
 Its connection to genes is a separate, weaker relationship (metabolite →
-KEGG compound → reaction → KO → crg GeneID) resolved at ranking time from
+KEGG compound → reaction → KO → crg GeneID for enzymes; metabolite → compound
+→ curated transporter KO in KEGG BRITE ko02000 → crg GeneID for transporters)
+resolved at ranking time from
 `data/mappings/metabolite_gene_links_*.tsv`, chosen per partition exactly as
 the crosswalk is: the simulated demo table for simulated evidence, the table
 registered under `metabolite_gene_links` in `genome_assemblies.yaml` for real