gemsmap 0.3.0b1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,737 @@
1
+ """Metabolite annotation analysis and curation (MetaNetX / MNXref).
2
+
3
+ 1. Every metabolite's existing cross-references (annotation, plus identifiers encoded in its ID) are
4
+ normalized and resolved to MetaNetX chemicals. Names never go to the ID mapper; an optional exact
5
+ name lookup only produces suggestions. When the BiGG universal tables are installed
6
+ (``npm run bigg:data``, services/bigg_service.py), they are a second, offline knowledge base: they
7
+ link BiGG IDs (current or superseded) and other identifiers to MetaNetX, add BiGG's curated
8
+ cross-references, and still resolve what they know when MetaNetX is unreachable.
9
+ 2. Each metabolite gets a status:
10
+ confident all identifiers agree on one MetaNetX chemical and the formula does not contradict it
11
+ doubt identifiers disagree, the formula conflicts, or only the ID string / the name matched
12
+ unmapped nothing found
13
+ skipped pseudo-metabolites (ecModel enzymes, protein pool)
14
+ 3. Accepted matches form a *curation layer* — new cross-references (MetaNetX ID, KEGG, ChEBI, BiGG,
15
+ ModelSEED, MetaCyc, HMDB, VMH, InChIKey …) and optionally a missing formula/charge. Existing
16
+ annotation is never removed or rewritten. The layer is saved next to the model cache, re-applied
17
+ when the model is reloaded, can be reverted per metabolite, and is part of every exported model.
18
+ """
19
+ from __future__ import annotations
20
+
21
+ import json
22
+ import re
23
+ import threading
24
+ import time
25
+ from datetime import datetime, timezone
26
+ from typing import Any, Callable, Iterable, Optional
27
+
28
+ from .. import registry
29
+ from ..errors import ScienceError
30
+ from . import metanetx as mnx_mod
31
+
32
+ ANALYSIS_VERSION = 1
33
+
34
+ # ----------------------------------------------------------------------------- identifiers
35
+
36
+ # annotation key (lower-case, separators removed) -> canonical namespace
37
+ _KEY = {
38
+ "kegg": "kegg.compound", "keggcompound": "kegg.compound", "keggid": "kegg.compound",
39
+ "keggglycan": "kegg.glycan", "keggdrug": "kegg.drug",
40
+ "chebi": "chebi", "chebiid": "chebi",
41
+ "bigg": "bigg.metabolite", "biggmetabolite": "bigg.metabolite",
42
+ "metanetx": "metanetx.chemical", "metanetxchemical": "metanetx.chemical", "mnx": "metanetx.chemical",
43
+ "seed": "seed.compound", "seedcompound": "seed.compound", "modelseed": "seed.compound",
44
+ "metacyc": "metacyc.compound", "metacyccompound": "metacyc.compound", "biocyc": "metacyc.compound",
45
+ "hmdb": "hmdb", "vmh": "vmhmetabolite", "vmhmetabolite": "vmhmetabolite",
46
+ "sabiork": "sabiork.compound", "sabiorkcompound": "sabiork.compound",
47
+ "lipidmaps": "lipidmaps", "slm": "slm", "swisslipids": "slm",
48
+ "inchikey": "inchikey",
49
+ }
50
+ # namespaces written back into the model (COBRApy annotation key = identifiers.org prefix)
51
+ WRITE = ["metanetx.chemical", "kegg.compound", "chebi", "bigg.metabolite", "seed.compound", "metacyc.compound",
52
+ "hmdb", "vmhmetabolite", "sabiork.compound", "lipidmaps", "slm", "kegg.glycan", "inchikey"]
53
+ # MetaNetX attaches whole compound classes from MetaCyc to some chemicals (D-glucose ->
54
+ # "Soyasapogenol-B-Monoglucosides"); above this many MetaCyc IDs per chemical none are written.
55
+ MAX_METACYC = 2
56
+ # MNX identifiers.org prefixes -> namespace
57
+ _MNX_PREFIX = {"kegg.compound": "kegg.compound", "chebi": "chebi", "bigg.metabolite": "bigg.metabolite",
58
+ "seed.compound": "seed.compound", "metacyc.compound": "metacyc.compound", "hmdb": "hmdb",
59
+ "vmhmetabolite": "vmhmetabolite", "sabiork.compound": "sabiork.compound", "lipidmaps": "lipidmaps",
60
+ "slm": "slm", "kegg.glycan": "kegg.glycan", "kegg.drug": "kegg.drug"}
61
+
62
+ NS_LABEL = {"metanetx.chemical": "MetaNetX", "kegg.compound": "KEGG", "chebi": "ChEBI", "bigg.metabolite": "BiGG",
63
+ "seed.compound": "ModelSEED", "metacyc.compound": "MetaCyc", "hmdb": "HMDB", "vmhmetabolite": "VMH",
64
+ "sabiork.compound": "SABIO-RK", "lipidmaps": "LIPID MAPS", "slm": "SwissLipids", "kegg.glycan": "KEGG glycan",
65
+ "kegg.drug": "KEGG drug", "inchikey": "InChIKey"}
66
+
67
+
68
+ def _keyof(k: str) -> str:
69
+ return re.sub(r"[^a-z0-9]", "", k.lower())
70
+
71
+
72
+ def norm_id(ns: str, raw: str) -> Optional[str]:
73
+ """Canonical identifier within a namespace, or None if unrecognisable."""
74
+ v = str(raw).strip()
75
+ v = re.sub(r"^https?://[^/]*(identifiers\.org|bioregistry\.io)/+", "", v, flags=re.I)
76
+ v = re.sub(r"^([a-z][a-z.]*)[/:](?=.)", lambda m: "" if _KEY.get(_keyof(m.group(1))) else m.group(0), v, flags=re.I)
77
+ if not v:
78
+ return None
79
+ if ns == "kegg.compound":
80
+ m = re.search(r"\b(C\d{5})\b", v, re.I)
81
+ return m.group(1).upper() if m else None
82
+ if ns == "kegg.glycan":
83
+ m = re.search(r"\b(G\d{5})\b", v, re.I)
84
+ return m.group(1).upper() if m else None
85
+ if ns == "kegg.drug":
86
+ m = re.search(r"\b(D\d{5})\b", v, re.I)
87
+ return m.group(1).upper() if m else None
88
+ if ns == "chebi":
89
+ m = re.search(r"(\d+)\s*$", v)
90
+ return f"CHEBI:{int(m.group(1))}" if m else None
91
+ if ns == "metanetx.chemical":
92
+ m = re.search(r"(MNXM\d+|WATER)", v, re.I)
93
+ return m.group(1).upper() if m else None
94
+ if ns == "seed.compound":
95
+ m = re.search(r"cpd\d{5}", v, re.I)
96
+ return m.group(0).lower() if m else None
97
+ if ns == "hmdb":
98
+ m = re.search(r"HMDB(\d+)", v, re.I)
99
+ return f"HMDB{m.group(1).zfill(7)}" if m else None
100
+ if ns == "metacyc.compound":
101
+ return re.sub(r"^(META|METACYC|BIOCYC)[:/]", "", v, flags=re.I).strip() or None
102
+ if ns == "inchikey":
103
+ m = re.search(r"[A-Z]{14}-[A-Z]{10}-[A-Z]", v, re.I)
104
+ return m.group(0).upper() if m else None
105
+ if ns == "slm":
106
+ m = re.search(r"(\d{9})", v)
107
+ return f"SLM:{m.group(1)}" if m else None
108
+ return v
109
+
110
+
111
+ def annotation_xrefs(annotation: Optional[dict]) -> set[tuple[str, str]]:
112
+ """(namespace, id) pairs of a COBRApy annotation dict."""
113
+ out: set[tuple[str, str]] = set()
114
+ for k, val in (annotation or {}).items():
115
+ ns = _KEY.get(_keyof(str(k)))
116
+ if not ns:
117
+ continue
118
+ for v in (val if isinstance(val, (list, tuple)) else [val]):
119
+ for part in re.split(r"[;,|]\s*|\s+", str(v)):
120
+ i = norm_id(ns, part) if part else None
121
+ if i:
122
+ out.add((ns, i))
123
+ return out
124
+
125
+
126
+ def id_xrefs(met_id: str, compartment: str) -> set[tuple[str, str]]:
127
+ """Identifiers implied by the ID string only (C00031[c], cpd00027_c0, MNXM41, glc__D_c) — weaker evidence."""
128
+ s = re.sub(r"^M_", "", met_id)
129
+ for pat, ns in ((r"^(C\d{5})(?!\d)", "kegg.compound"), (r"^(cpd\d{5})(?!\d)", "seed.compound"), (r"^(MNXM\d+)(?!\d)", "metanetx.chemical")):
130
+ m = re.match(pat, s, re.I)
131
+ if m:
132
+ return {(ns, norm_id(ns, m.group(1)))}
133
+ c = re.escape(compartment or "")
134
+ base = re.sub(rf"(\[{c}\]|\({c}\)|[_-]{c})$", "", s) if c else s
135
+ base = re.sub(r"\[[a-z0-9]+\]$", "", base, flags=re.I)
136
+ if re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_]*", base) and not base.isdigit() and len(base) <= 40:
137
+ return {("bigg.metabolite", base)}
138
+ return set()
139
+
140
+
141
+ def mnx_uri(ns: str, i: str) -> Optional[str]:
142
+ """URI form used by MNXref for an identifier."""
143
+ if ns == "metanetx.chemical":
144
+ return None # handled directly as an MNX chemical
145
+ if ns == "chebi":
146
+ return f"https://identifiers.org/{i}" # CHEBI:4167
147
+ if ns == "slm":
148
+ return f"https://identifiers.org/{i}" # SLM:000001048
149
+ if ns in ("kegg.compound", "bigg.metabolite", "seed.compound", "metacyc.compound", "hmdb", "vmhmetabolite",
150
+ "sabiork.compound", "lipidmaps", "kegg.glycan", "kegg.drug"):
151
+ return f"https://identifiers.org/{ns}:{i}"
152
+ return None
153
+
154
+
155
+ def parse_mnx_xref(uri: str) -> Optional[tuple[str, str]]:
156
+ m = re.match(r"https://identifiers\.org/([^:/]+):(.+)$", uri)
157
+ if not m:
158
+ return None
159
+ prefix, rest = m.group(1).lower(), m.group(2)
160
+ if prefix == "chebi":
161
+ return ("chebi", f"CHEBI:{int(rest)}") if rest.isdigit() else None
162
+ if prefix == "slm":
163
+ return ("slm", f"SLM:{rest}")
164
+ ns = _MNX_PREFIX.get(prefix)
165
+ if not ns:
166
+ return None
167
+ i = norm_id(ns, rest)
168
+ return (ns, i) if i else None
169
+
170
+
171
+ def heavy_atoms(formula: Optional[str]) -> Optional[dict]:
172
+ if not formula or re.search(r"[()*]|R(?![a-z])|X(?![a-z])|n$", formula):
173
+ return None
174
+ out: dict[str, int] = {}
175
+ for el, n in re.findall(r"([A-Z][a-z]?)(\d*)", formula):
176
+ if el != "H":
177
+ out[el] = out.get(el, 0) + (int(n) if n else 1)
178
+ return out or None
179
+
180
+
181
+ def formula_check(a: Optional[str], b: Optional[str]) -> Optional[str]:
182
+ x, y = heavy_atoms(a), heavy_atoms(b)
183
+ if not x or not y:
184
+ return None
185
+ return "match" if x == y else "conflict"
186
+
187
+
188
+ def compact(name: Optional[str]) -> str:
189
+ s = (name or "").lower()
190
+ s = re.sub(r"\s*\[[^\]]{1,24}\]\s*$", "", s)
191
+ s = re.sub(r"\s*\(\s*\d*\s*[+-]\s*\d*\s*\)\s*$", "", s)
192
+ return re.sub(r"[\s\-,'()\[\]{}_]", "", s)
193
+
194
+
195
+ def clean_name(name: str) -> str:
196
+ """Name as it would appear in MetaNetX (compartment and charge decorations removed)."""
197
+ s = re.sub(r"\s*\[[^\]]{1,24}\]\s*$", "", name or "").strip()
198
+ return re.sub(r"\s*\(\s*\d*\s*[+-]\s*\d*\s*\)\s*$", "", s).strip()
199
+
200
+
201
+ PSEUDO = re.compile(r"^(prot_|pmet_|prot_pool)|^(biomass|protein|lipid|dna|rna|carbohydrate)(_|\[|$)", re.I)
202
+
203
+ # ----------------------------------------------------------------------------- analysis
204
+
205
+
206
+ def snapshot(entry: registry.ModelEntry) -> list[dict]:
207
+ with entry.lock:
208
+ return [{"id": m.id, "name": m.name or "", "formula": m.formula or None,
209
+ "charge": m.charge if isinstance(m.charge, (int, float)) else None,
210
+ "compartment": m.compartment or "", "annotation": dict(m.annotation or {})}
211
+ for m in entry.model.metabolites]
212
+
213
+
214
+ def bigg_index():
215
+ """The local BiGG knowledge base, or None when it is not installed (lazy import: bigg_service imports us)."""
216
+ try:
217
+ from . import bigg_service
218
+ return bigg_service.index()
219
+ except Exception: # noqa: BLE001 - optional layer; the analysis works without it
220
+ return None
221
+
222
+
223
+ def _bigg_status(big) -> Optional[dict]:
224
+ if big is None:
225
+ return None
226
+ try:
227
+ from . import bigg_service
228
+ st = bigg_service.status()
229
+ return {"metabolites": len(big.mets), "installed": st.get("installed"), "source": st.get("source")}
230
+ except Exception: # noqa: BLE001
231
+ return {"metabolites": len(big.mets)}
232
+
233
+
234
+ def _bigg_links(m: dict, xs: list[dict], big) -> list[str]:
235
+ """BiGG universal metabolites of this metabolite (from its annotation, its ID, superseded BiGG IDs).
236
+
237
+ BiGG's own MetaNetX links are often older MNX releases (glutathione: MNXM57 in BiGG, MNXM490899 in
238
+ MNXref 4), so they only *bridge* to MetaNetX when the metabolite's identifiers resolved nothing there
239
+ (BiGG IDs unknown to MNXref, offline). Bridging inputs are ``derived``: shown as evidence, never counted
240
+ as an extra independent database in the consensus.
241
+ """
242
+ found: dict[str, tuple[str, str, bool]] = {}
243
+ ann: dict[str, list[str]] = {}
244
+ for x in xs:
245
+ if x["source"] == "annotation":
246
+ ann.setdefault(x["ns"], []).append(x["id"])
247
+ for uid in big.resolve(ann):
248
+ found.setdefault(uid, ("annotation", "annotation", False))
249
+ for ns, i in id_xrefs(m["id"], m["compartment"]):
250
+ if i:
251
+ for uid in big.resolve({ns: [i]}):
252
+ found[uid] = ("the metabolite ID", "id", True)
253
+ if not any(x.get("mnx") for x in xs):
254
+ for uid, (frm, source, anchor) in sorted(found.items()):
255
+ mnx = sorted(big.mets[uid]["xrefs"].get("metanetx.chemical", ()))
256
+ if mnx:
257
+ xs.append({"ns": "bigg.metabolite", "id": uid, "source": source, "mnx": mnx, "derived": True, "anchor": anchor, "from": frm})
258
+ return sorted(found)
259
+
260
+
261
+ def merge_bigg(info: dict, mnx_ids, big) -> dict:
262
+ """Describe from the BiGG tables the MetaNetX chemicals MetaNetX itself gave no data for (bridged IDs,
263
+ or MetaNetX unreachable). Entries MetaNetX described are left as they are."""
264
+ if big is None:
265
+ return info
266
+ for i in set(mnx_ids):
267
+ if (info.get(i) or {}).get("exists"):
268
+ continue
269
+ uids = sorted(big.by_xref.get(f"metanetx.chemical:{str(i).upper()}", ()))
270
+ if not uids:
271
+ continue
272
+ b = big.mets[uids[0]]
273
+ info[i] = {"mnx": i, "name": b["name"], "formula": b["formula"], "charge": b["charge"], "inchikey": None,
274
+ "xrefs": [], "isomers": [], "exists": True, "fromBigg": True}
275
+ return info
276
+
277
+
278
+ def bigg_additions(uids: list[str], big) -> dict[str, set[str]]:
279
+ """BiGG IDs and BiGG's curated cross-references (KEGG, ChEBI, ModelSEED, HMDB, InChIKey) of BiGG metabolites.
280
+ MetaNetX links (often an older MNX release) and MetaCyc entries (often compound classes) are left out."""
281
+ out: dict[str, set[str]] = {}
282
+ for uid in uids:
283
+ b = big.mets.get(uid)
284
+ if not b:
285
+ continue
286
+ out.setdefault("bigg.metabolite", set()).add(uid)
287
+ for ns, vals in b["xrefs"].items():
288
+ if ns in ("metanetx.chemical", "metacyc.compound") or ns not in WRITE:
289
+ continue
290
+ if ns == "inchikey" and len(vals) != 1:
291
+ continue
292
+ out.setdefault(ns, set()).update(vals)
293
+ return out
294
+
295
+
296
+ _AUTO = object()
297
+
298
+
299
+ def analyze(mets: list[dict], client: mnx_mod.MetaNetX, use_names: bool = True,
300
+ progress: Optional[Callable[[str, int, int], None]] = None, bigg=_AUTO) -> dict:
301
+ """Pure analysis (no model mutation). `progress(phase, done, total)`.
302
+ `bigg`: a BiggIndex, None to leave the BiGG tables out, or (default) the installed tables."""
303
+ t0 = time.time()
304
+ big = bigg_index() if bigg is _AUTO else bigg
305
+ report = progress or (lambda *_: None)
306
+ errors: list[str] = []
307
+
308
+ inputs: dict[str, list[dict]] = {}
309
+ for m in mets:
310
+ if PSEUDO.search(m["id"]) or PSEUDO.search(m["name"]):
311
+ continue
312
+ ann = annotation_xrefs(m["annotation"])
313
+ ids = id_xrefs(m["id"], m["compartment"]) - ann
314
+ inputs[m["id"]] = [{"ns": ns, "id": i, "source": "annotation"} for ns, i in sorted(ann)] + \
315
+ [{"ns": ns, "id": i, "source": "id"} for ns, i in sorted(ids)]
316
+
317
+ # 1. identifiers -> MNX
318
+ uris = {mnx_uri(x["ns"], x["id"]) for xs in inputs.values() for x in xs} - {None}
319
+ done = [0]
320
+
321
+ def step(phase, total):
322
+ def f(n):
323
+ done[0] += n
324
+ report(phase, min(done[0], total), total)
325
+ return f
326
+
327
+ resolved: dict[str, list[str]] = {}
328
+ try:
329
+ resolved = client.resolve_xrefs(uris, progress=step("identifiers", len(uris)))
330
+ except mnx_mod.MetaNetXUnavailable as e:
331
+ errors.append(str(e))
332
+ for xs in inputs.values():
333
+ for x in xs:
334
+ if x["ns"] == "metanetx.chemical":
335
+ x["mnx"] = [x["id"]]
336
+ else:
337
+ x["mnx"] = resolved.get(mnx_uri(x["ns"], x["id"]) or "", [])
338
+
339
+ # 1b. local BiGG tables: BiGG IDs (current or superseded) and other identifiers -> MetaNetX, offline
340
+ bigg_of: dict[str, list[str]] = {}
341
+ if big is not None:
342
+ for m in mets:
343
+ if m["id"] in inputs:
344
+ bigg_of[m["id"]] = _bigg_links(m, inputs[m["id"]], big)
345
+
346
+ # 2. optional exact name lookup for metabolites without any identifier hit
347
+ name_hits: dict[str, list[str]] = {}
348
+ if use_names and not errors:
349
+ need = {m["id"]: clean_name(m["name"]) for m in mets
350
+ if m["id"] in inputs and not any(x["mnx"] for x in inputs[m["id"]]) and clean_name(m["name"])}
351
+ variants = {v for n in need.values() for v in (n, n[:1].lower() + n[1:])}
352
+ done[0] = 0
353
+ try:
354
+ hits = client.lookup_names(variants, progress=step("names", len(variants)))
355
+ for mid, n in need.items():
356
+ found = hits.get(n) or hits.get(n[:1].lower() + n[1:]) or []
357
+ if found:
358
+ name_hits[mid] = found
359
+ except mnx_mod.MetaNetXUnavailable as e:
360
+ errors.append(str(e))
361
+
362
+ # 3. chemical details
363
+ all_mnx = {i for xs in inputs.values() for x in xs for i in x["mnx"]} | {i for v in name_hits.values() for i in v}
364
+ info: dict[str, dict] = {}
365
+ done[0] = 0
366
+ try:
367
+ info = client.chem_info(all_mnx, progress=step("compounds", len(all_mnx)))
368
+ except mnx_mod.MetaNetXUnavailable as e:
369
+ errors.append(str(e))
370
+ merge_bigg(info, all_mnx, big)
371
+
372
+ report("deciding", 0, len(mets))
373
+ items = [decide(m, inputs.get(m["id"]), name_hits.get(m["id"], []), info, bigg_of.get(m["id"], []), big) for m in mets]
374
+ summary = {k: sum(1 for it in items if it["status"] == k) for k in ("confident", "doubt", "unmapped", "skipped")}
375
+ summary["total"] = len(items)
376
+ summary["newIdentifiers"] = sum(sum(len(v) for v in it["proposal"]["add"].values()) for it in items if it.get("proposal"))
377
+ summary["formulaSuggestions"] = sum(1 for it in items if it.get("proposal") and it["proposal"].get("formula"))
378
+ return {
379
+ "version": ANALYSIS_VERSION,
380
+ "createdAt": datetime.now(timezone.utc).isoformat(timespec="seconds"),
381
+ "source": {"service": "MetaNetX / MNXref (SPARQL)" + (" + BiGG (local tables)" if big is not None else ""),
382
+ "endpoint": mnx_mod.ENDPOINT, "networkCalls": client.network_calls, "bigg": _bigg_status(big)},
383
+ "status": "partial" if errors else "done",
384
+ "errors": errors,
385
+ "seconds": round(time.time() - t0, 1),
386
+ "summary": summary,
387
+ "items": items,
388
+ }
389
+
390
+
391
+ def _candidate(i: str, info: dict, via: list[str], model_formula: Optional[str], model_name: str) -> dict:
392
+ d = info.get(i) or {"mnx": i, "exists": False, "xrefs": [], "isomers": []}
393
+ return {
394
+ "mnx": i, "name": d.get("name"), "formula": d.get("formula"), "charge": d.get("charge"), "inchikey": d.get("inchikey"),
395
+ "structured": bool(d.get("formula") or d.get("inchikey")), "exists": bool(d.get("exists")),
396
+ "via": via, "formulaCheck": formula_check(model_formula, d.get("formula")),
397
+ "nameMatch": bool(d.get("name")) and compact(d.get("name")) == compact(model_name),
398
+ "bigg": d.get("bigg", []),
399
+ "fromBigg": bool(d.get("fromBigg")),
400
+ }
401
+
402
+
403
+ def _additions(cand: dict, info: dict, existing: set[tuple[str, str]], big=None) -> dict[str, list[str]]:
404
+ d = info.get(cand["mnx"]) or {}
405
+ found: dict[str, set[str]] = {}
406
+ if big is not None:
407
+ for ns, vals in bigg_additions(cand.get("bigg") or [], big).items():
408
+ found.setdefault(ns, set()).update(vals)
409
+ for uri in d.get("xrefs", []):
410
+ p = parse_mnx_xref(uri)
411
+ if p and p[0] in WRITE:
412
+ found.setdefault(p[0], set()).add(p[1])
413
+ if len(found.get("metacyc.compound", ())) > MAX_METACYC:
414
+ found.pop("metacyc.compound")
415
+ if not d.get("fromBigg"): # an MNX ID known only through BiGG may be from an older MNX release: not written
416
+ found.setdefault("metanetx.chemical", set()).add(cand["mnx"])
417
+ if d.get("inchikey"):
418
+ found.setdefault("inchikey", set()).add(d["inchikey"])
419
+ out = {}
420
+ for ns in WRITE:
421
+ new = sorted(v for v in found.get(ns, ()) if (ns, v) not in existing)
422
+ if new:
423
+ out[ns] = new
424
+ return out
425
+
426
+
427
+ def decide(m: dict, inputs: Optional[list[dict]], names: list[str], info: dict, bigg_uids: Optional[list[str]] = None, big=None) -> dict:
428
+ base = {"id": m["id"], "name": m["name"], "compartment": m["compartment"], "formula": m["formula"], "charge": m["charge"]}
429
+ if inputs is None:
430
+ return {**base, "status": "skipped", "reason": "Pseudo-metabolite (enzyme / pool / biomass component)", "inputs": [], "candidates": []}
431
+ existing = annotation_xrefs(m["annotation"])
432
+ votes: dict[str, list[str]] = {}
433
+ src: dict[str, set[str]] = {}
434
+ for x in inputs:
435
+ label = (f"BiGG {x['id']} (local BiGG tables, from {x['from']})" if x.get("derived")
436
+ else f"{NS_LABEL.get(x['ns'], x['ns'])} {x['id']}" + (" (from the ID)" if x["source"] == "id" else ""))
437
+ for i in x["mnx"]:
438
+ votes.setdefault(i, []).append(label)
439
+ src.setdefault(i, set()).add(x["source"])
440
+ for i in names:
441
+ votes.setdefault(i, []).append(f"name “{clean_name(m['name'])}”")
442
+ src.setdefault(i, set()).add("name")
443
+ cands = [_candidate(i, info, v, m["formula"], m["name"]) for i, v in votes.items()]
444
+ if big is not None and bigg_uids:
445
+ # The BiGG metabolites this metabolite resolves to, on every candidate whose composition agrees. Several
446
+ # BiGG entries can share a KEGG/ChEBI ID (g6p and M01389): then only the one(s) the model itself uses
447
+ # (its ID or an annotated BiGG ID) are kept, otherwise none — a BiGG ID is written only when unambiguous.
448
+ own = big.resolve({"bigg.metabolite": [x["id"] for x in inputs if x["ns"] == "bigg.metabolite" and not x.get("derived")]})
449
+ for c in cands:
450
+ fit = [u for u in bigg_uids if formula_check(big.mets[u]["formula"], c["formula"]) != "conflict"]
451
+ c["bigg"] = [u for u in fit if u in own] or (fit if len(fit) == 1 else [])
452
+ cands = [c for c in cands if c["exists"]] or cands
453
+ cands.sort(key=lambda c: (-("annotation" in src[c["mnx"]]), -len(c["via"]), -c["structured"], c["formulaCheck"] == "conflict", c["mnx"]))
454
+ inputs_out = [{"xref": (f"BiGG {x['id']} (local tables)" if x.get("derived") else f"{NS_LABEL.get(x['ns'], x['ns'])} {x['id']}"),
455
+ "source": "bigg" if x.get("derived") else x["source"], "mnx": x["mnx"]} for x in inputs]
456
+ if not cands:
457
+ return {**base, "status": "unmapped", "reason": "No identifier or name of this metabolite is known to MetaNetX" if inputs else "No database identifier, and no exact name match in MetaNetX",
458
+ "inputs": inputs_out, "candidates": []}
459
+
460
+ def reduce(group: list[dict]) -> tuple[Optional[dict], str]:
461
+ """One chemical, or one structured chemical whose structureless twins carry the same name."""
462
+ if len(group) == 1:
463
+ return group[0], ""
464
+ structured = [c for c in group if c["structured"]]
465
+ if len(structured) == 1 and all(c["structured"] or compact(c["name"]) == compact(structured[0]["name"]) for c in group):
466
+ others = ", ".join(c["mnx"] for c in group if c is not structured[0])
467
+ return structured[0], f" ({others}: entry without structure, same name)"
468
+ return None, ""
469
+
470
+ ann = [c for c in cands if "annotation" in src[c["mnx"]]]
471
+ idc = [c for c in cands if "id" in src[c["mnx"]] and "annotation" not in src[c["mnx"]]]
472
+ status, reason, chosen = "doubt", "", cands[0]
473
+ # The metabolite's own ID (BiGG base, KEGG C-number…) is the model author's statement of identity: the anchor.
474
+ anchor = {i for ns, i0 in id_xrefs(m["id"], m["compartment"]) for x in inputs
475
+ if x["ns"] == ns and x["id"] == i0 and not x.get("derived") for i in x["mnx"]}
476
+ anchor |= {i for x in inputs if x.get("anchor") for i in x["mnx"]} # the ID, through the BiGG tables
477
+ if ann:
478
+ # consensus by DATABASE, not by identifier: annotations often list several ChEBI entries (acid, anion,
479
+ # parent class) that MNXref keeps apart, while BiGG/KEGG/SEED/HMDB agree on one chemical
480
+ support = {c["mnx"]: {x["ns"] for x in inputs if x["source"] == "annotation" and not x.get("derived") and c["mnx"] in x["mnx"]} for c in ann}
481
+ nvotes = {c["mnx"]: len(c["via"]) for c in ann}
482
+ # salts, hydrates and conjugates that annotations often drag along have another composition
483
+ compatible = [c for c in ann if c["formulaCheck"] != "conflict"] or ann
484
+ excluded = [c for c in ann if c not in compatible]
485
+ ranked = sorted(compatible, key=lambda c: (-(c["mnx"] in anchor), -len(support[c["mnx"]]), -nvotes[c["mnx"]], -c["structured"], c["mnx"]))
486
+ one, note = reduce(compatible)
487
+ top, nxt = ranked[0], (ranked[1] if len(ranked) > 1 else None)
488
+ ns_top, ns_next = len(support[top["mnx"]]), (len(support[nxt["mnx"]]) if nxt else 0)
489
+ v_top, v_next = nvotes[top["mnx"]], (nvotes[nxt["mnx"]] if nxt else 0)
490
+ ignored = ", ".join(f"{c['mnx']} {c['name']} {c['formula']}" for c in excluded[:3]) # no nested quotes: Python 3.10
491
+ dropped = f" Ignored (different formula): {ignored}." if excluded else ""
492
+ others = "; ".join(f"{c['mnx']} ({c['name']}) via {', '.join(c['via'][:3])}" for c in ranked[1:4])
493
+ if one:
494
+ chosen, status, reason = one, "confident", f"All annotated identifiers point to {one['mnx']}{note}.{dropped}"
495
+ elif top["mnx"] in anchor and ns_top >= 2 and v_top > v_next:
496
+ chosen, status = top, "confident"
497
+ reason = (f"The metabolite ID and {', '.join(NS_LABEL.get(n, n) for n in sorted(support[top['mnx']]))} agree on {top['mnx']}. "
498
+ f"Other annotated identifiers point elsewhere: {others}.{dropped}")
499
+ elif not anchor and ns_top >= 2 and ns_next <= 1 and v_next * 2 <= v_top:
500
+ chosen, status = top, "confident"
501
+ reason = f"{', '.join(NS_LABEL.get(n, n) for n in sorted(support[top['mnx']]))} agree on {top['mnx']}; minor identifiers point elsewhere: {others}.{dropped}"
502
+ else:
503
+ chosen = top
504
+ reason = f"Annotated identifiers point to {len(compatible)} different MetaNetX chemicals: " + "; ".join(
505
+ f"{c['mnx']} ({c['name']}) via {', '.join(c['via'][:4])}" for c in ranked[:4]) + f".{dropped}"
506
+ elif idc:
507
+ one, note = reduce(idc)
508
+ if one and (one["formulaCheck"] == "match" or one["nameMatch"]):
509
+ chosen, status, reason = one, "confident", f"ID encodes {', '.join(one['via'])}; {'formula' if one['formulaCheck'] == 'match' else 'name'} agrees{note}"
510
+ elif one:
511
+ chosen, reason = one, "Matched only through the ID string, without an annotation, formula or name to confirm it"
512
+ else:
513
+ reason = f"The ID string points to {len(idc)} different MetaNetX chemicals"
514
+ else:
515
+ reason = "Exact name match only — names are not identities; please confirm"
516
+ if status == "confident" and anchor and chosen["mnx"] not in anchor:
517
+ status = "doubt"
518
+ reason = (f"The metabolite ID points to {', '.join(sorted(anchor))} "
519
+ f"({', '.join(c['name'] or '?' for c in cands if c['mnx'] in anchor)}), the annotation to {chosen['mnx']} ({chosen['name']})")
520
+ if status == "confident" and chosen["formulaCheck"] == "conflict":
521
+ status, reason = "doubt", f"{chosen['mnx']} has formula {chosen['formula']}, the model has {m['formula']} (H not compared)"
522
+ if chosen.get("fromBigg"):
523
+ reason += (" Described from the local BiGG tables (MetaNetX gave no data for it): its BiGG cross-references are"
524
+ " proposed, its MetaNetX ID is not written until MetaNetX confirms it.")
525
+ proposal = {"mnx": chosen["mnx"], "add": _additions(chosen, info, existing, big)}
526
+ if not m["formula"] and chosen.get("formula"):
527
+ proposal["formula"] = chosen["formula"]
528
+ proposal["charge"] = chosen.get("charge")
529
+ return {**base, "status": status, "reason": reason, "inputs": inputs_out, "candidates": cands[:6], "proposal": proposal}
530
+
531
+
532
+ # ----------------------------------------------------------------------------- persistence
533
+
534
+ def _path(mid: str, kind: str):
535
+ return registry.cache_dir() / f"{mid}.{kind}.json"
536
+
537
+
538
+ def load_json(mid: str, kind: str) -> Optional[dict]:
539
+ p = _path(mid, kind)
540
+ try:
541
+ return json.loads(p.read_text(encoding="utf-8")) if p.exists() else None
542
+ except Exception: # noqa: BLE001 - corrupt cache file: start over
543
+ return None
544
+
545
+
546
+ def save_json(mid: str, kind: str, data: dict) -> None:
547
+ _path(mid, kind).write_text(json.dumps(data), encoding="utf-8")
548
+
549
+
550
+ def empty_curation() -> dict:
551
+ return {"version": 1, "metabolites": {}, "rejected": []}
552
+
553
+
554
+ def curation(mid: str) -> dict:
555
+ return load_json(mid, "curation") or empty_curation()
556
+
557
+
558
+ def _as_list(v: Any) -> list[str]:
559
+ return [str(x) for x in v] if isinstance(v, (list, tuple)) else ([str(v)] if v not in (None, "") else [])
560
+
561
+
562
+ def _apply_one(met, c: dict) -> None:
563
+ ann = met.annotation
564
+ for ns, vals in c["added"].items():
565
+ cur = _as_list(ann.get(ns))
566
+ ann[ns] = cur + [v for v in vals if v not in cur]
567
+ if c.get("formula"):
568
+ met.formula = c["formula"]
569
+ if c.get("charge") is not None:
570
+ met.charge = c["charge"]
571
+
572
+
573
+ def _revert_one(met, c: dict) -> None:
574
+ ann = met.annotation
575
+ for ns, vals in c["added"].items():
576
+ left = [v for v in _as_list(ann.get(ns)) if v not in vals]
577
+ if left:
578
+ ann[ns] = left if len(left) > 1 else left[0]
579
+ else:
580
+ ann.pop(ns, None)
581
+ if c.get("formula"):
582
+ met.formula = c["original"].get("formula") or ""
583
+ met.charge = c["original"].get("charge")
584
+
585
+
586
+ def apply_curation_to_model(model, cur: dict) -> int:
587
+ """Re-apply a saved curation layer (model reload). Returns the number of metabolites touched."""
588
+ n = 0
589
+ for mid, c in (cur or {}).get("metabolites", {}).items():
590
+ if mid in model.metabolites:
591
+ _apply_one(model.metabolites.get_by_id(mid), c)
592
+ n += 1
593
+ return n
594
+
595
+
596
+ def _refresh(entry: registry.ModelEntry, ids: Iterable[str]) -> list[dict]:
597
+ """Update the catalog rows (and search index) of changed metabolites."""
598
+ from . import model_service as ms
599
+ from .search_service import SearchIndex
600
+ ids = set(ids)
601
+ rows = []
602
+ pos = {m["id"]: i for i, m in enumerate(entry.catalog["metabolites"])}
603
+ for mid in ids:
604
+ if mid not in entry.model.metabolites or mid not in pos:
605
+ continue
606
+ met = entry.model.metabolites.get_by_id(mid)
607
+ row = {**entry.catalog["metabolites"][pos[mid]], "formula": met.formula or None,
608
+ "charge": met.charge if isinstance(met.charge, (int, float)) else None, "annotation": ms._ann(met.annotation)}
609
+ entry.catalog["metabolites"][pos[mid]] = row
610
+ rows.append(row)
611
+ if ids:
612
+ entry.search = SearchIndex(entry.model)
613
+ return rows
614
+
615
+
616
+ def apply(entry: registry.ModelEntry, choices: list[dict], source: str = "user") -> dict:
617
+ """choices: [{id, mnx?, fillFormula?}] — mnx defaults to the analysis proposal."""
618
+ analysis = load_json(entry.id, "annotation")
619
+ if not analysis:
620
+ raise ScienceError("No annotation analysis", "Run the metabolite analysis first.")
621
+ by_id = {it["id"]: it for it in analysis["items"]}
622
+ cur = curation(entry.id)
623
+ changed = []
624
+ with entry.lock:
625
+ for ch in choices:
626
+ it = by_id.get(ch["id"])
627
+ if not it or ch["id"] not in entry.model.metabolites:
628
+ continue
629
+ met = entry.model.metabolites.get_by_id(ch["id"])
630
+ old = cur["metabolites"].get(ch["id"])
631
+ if old:
632
+ _revert_one(met, old)
633
+ want = ch.get("mnx") or (it.get("proposal") or {}).get("mnx")
634
+ cand = next((c for c in it.get("candidates", []) if c["mnx"] == want), None)
635
+ if not cand:
636
+ continue
637
+ try:
638
+ info = mnx_mod.client().chem_info([want])
639
+ except mnx_mod.MetaNetXUnavailable:
640
+ info = {}
641
+ big = bigg_index()
642
+ merge_bigg(info, [want], big)
643
+ c = {"mnx": want, "added": _additions(cand, info, annotation_xrefs(met.annotation), big), "source": source,
644
+ "status": it["status"], "at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
645
+ "original": {"formula": met.formula or None, "charge": met.charge if isinstance(met.charge, (int, float)) else None}}
646
+ if ch.get("fillFormula", True) and not met.formula and cand.get("formula"):
647
+ c["formula"], c["charge"] = cand["formula"], cand.get("charge")
648
+ _apply_one(met, c)
649
+ cur["metabolites"][ch["id"]] = c
650
+ cur["rejected"] = [x for x in cur["rejected"] if x != ch["id"]]
651
+ changed.append(ch["id"])
652
+ save_json(entry.id, "curation", cur)
653
+ rows = _refresh(entry, changed)
654
+ return {"curation": curation_summary(cur), "metabolites": rows}
655
+
656
+
657
+ def reject(entry: registry.ModelEntry, ids: list[str]) -> dict:
658
+ """Keep the model as it is for these metabolites (undoing an accepted match) and remember the decision."""
659
+ cur = curation(entry.id)
660
+ accepted = [i for i in ids if i in cur["metabolites"]]
661
+ rows = revert(entry, accepted, cur)["metabolites"] if accepted else []
662
+ cur["rejected"] = sorted(set(cur["rejected"]) | set(ids))
663
+ save_json(entry.id, "curation", cur)
664
+ return {"curation": curation_summary(cur), "metabolites": rows}
665
+
666
+
667
+ def revert(entry: registry.ModelEntry, ids: Optional[list[str]], cur: Optional[dict] = None) -> dict:
668
+ cur = cur or curation(entry.id)
669
+ targets = list(cur["metabolites"]) if ids is None else [i for i in ids if i in cur["metabolites"]]
670
+ with entry.lock:
671
+ for mid in targets:
672
+ if mid in entry.model.metabolites:
673
+ _revert_one(entry.model.metabolites.get_by_id(mid), cur["metabolites"][mid])
674
+ cur["metabolites"].pop(mid, None)
675
+ save_json(entry.id, "curation", cur)
676
+ rows = _refresh(entry, targets)
677
+ return {"curation": curation_summary(cur), "metabolites": rows}
678
+
679
+
680
+ def curation_summary(cur: dict) -> dict:
681
+ ms_ = cur.get("metabolites", {})
682
+ return {
683
+ "accepted": len(ms_),
684
+ "identifiers": sum(sum(len(v) for v in c["added"].values()) for c in ms_.values()),
685
+ "formulas": sum(1 for c in ms_.values() if c.get("formula")),
686
+ "rejected": len(cur.get("rejected", [])),
687
+ "entries": {k: {"mnx": c["mnx"], "source": c["source"], "formula": bool(c.get("formula")), "at": c["at"]} for k, c in ms_.items()},
688
+ "rejectedIds": cur.get("rejected", []),
689
+ }
690
+
691
+
692
+ # ----------------------------------------------------------------------------- jobs
693
+
694
+ _jobs: dict[str, dict] = {}
695
+ _jobs_lock = threading.Lock()
696
+
697
+
698
+ def job(mid: str) -> Optional[dict]:
699
+ with _jobs_lock:
700
+ j = _jobs.get(mid)
701
+ return dict(j) if j else None
702
+
703
+
704
+ def start(entry: registry.ModelEntry, use_names: bool, auto_apply: bool, fill_formulas: bool) -> dict:
705
+ with _jobs_lock:
706
+ j = _jobs.get(entry.id)
707
+ if j and j["state"] == "running":
708
+ return dict(j)
709
+ j = {"state": "running", "phase": "preparing", "done": 0, "total": 0, "startedAt": time.time(), "error": None}
710
+ _jobs[entry.id] = j
711
+ mets = snapshot(entry)
712
+
713
+ def progress(phase, done, total):
714
+ with _jobs_lock:
715
+ j.update(phase=phase, done=done, total=total)
716
+
717
+ def run():
718
+ try:
719
+ result = analyze(mets, mnx_mod.client(), use_names=use_names, progress=progress)
720
+ save_json(entry.id, "annotation", result)
721
+ if auto_apply:
722
+ rejected = set(curation(entry.id)["rejected"])
723
+ apply(entry, [{"id": it["id"], "fillFormula": fill_formulas} for it in result["items"]
724
+ if it["status"] == "confident" and it["id"] not in rejected], source="auto")
725
+ with _jobs_lock:
726
+ j.update(state="done", phase="done", finishedAt=time.time())
727
+ except Exception as e: # noqa: BLE001 - reported to the UI
728
+ with _jobs_lock:
729
+ j.update(state="error", error=str(e))
730
+
731
+ threading.Thread(target=run, name=f"annotate-{entry.id}", daemon=True).start()
732
+ return dict(j)
733
+
734
+
735
+ def status(entry: registry.ModelEntry, full: bool = True) -> dict:
736
+ return {"job": job(entry.id), "analysis": load_json(entry.id, "annotation") if full else None,
737
+ "curation": curation_summary(curation(entry.id))}