gemsmap 0.3.0__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,498 @@
1
+ """BiGG data layer: the universal metabolites and reactions of BiGG Models (https://bigg.bio) as a local knowledge
2
+ base for building templates. GEMsMAP does not talk to the BiGG API: the published bulk tables are installed once
3
+ (``gemsmap bigg-data``, or ``npm run bigg:data`` in a development checkout) into the backend cache and indexed in memory.
4
+
5
+ 1. Metabolite identity: search by BiGG ID (current or superseded), any cross-referenced identifier (KEGG, ChEBI,
6
+ MetaNetX, ModelSEED, MetaCyc, HMDB) or name. A candidate carries the BiGG universal ID, the union of the
7
+ cross-references of its charge states, and the formula / charge of the neutral form.
8
+ 2. Reaction identity: the template's participants (all of them, cofactors included) are resolved to BiGG universal
9
+ metabolites through their identifiers, and the universal reactions that convert a main substrate into a main
10
+ product are scored on participant coverage, coefficients, compartments, EC and transport consistency, with
11
+ evidence for every point.
12
+ 3. BiGG IDs for templates: entities and reactions get their BiGG universal IDs when exactly one fits, so a template
13
+ matches models downloaded from BiGG by their own identifiers.
14
+ 4. Models downloaded from BiGG: IDs normalized (``__<model>__`` prefixes of model-specific entries removed) and
15
+ annotations completed from the universal tables when the file is imported.
16
+
17
+ Nothing here decides an identity: the Template Builder shows candidates and the user confirms them.
18
+ Standard library only.
19
+ """
20
+ from __future__ import annotations
21
+
22
+ import json
23
+ import re
24
+ import threading
25
+ import time
26
+ from pathlib import Path
27
+ from typing import Optional
28
+
29
+ from .annotation_service import compact
30
+
31
+ SOURCE = "https://bigg.bio"
32
+
33
+ # BiGG cross-reference namespaces -> GEMsMAP identifier keys (others: drugbank, kegg.drug, wikipedia, GO are left out)
34
+ MET_NS = {"CHEBI": "chebi", "kegg.compound": "kegg.compound", "metacyc.compound": "metacyc.compound", "metanetx.chemical": "metanetx.chemical",
35
+ "seed.compound": "seed.compound", "hmdb": "hmdb", "inchikey": "inchikey"}
36
+ RXN_NS = {"metanetx.reaction": "metanetx.reaction", "metacyc.reaction": "metacyc.reaction", "seed.reaction": "seed.reaction", "rhea": "rhea",
37
+ "kegg.reaction": "kegg.reaction"}
38
+ # BiGG compartment ids -> template conceptual compartments
39
+ COMPARTMENT = {"c": "cytosol", "m": "mitochondria", "e": "extracellular", "p": "periplasm", "x": "peroxisome", "r": "endoplasmic_reticulum",
40
+ "n": "nucleus", "v": "vacuole", "g": "golgi", "l": "lysosome", "h": "chloroplast", "u": "thylakoid", "im": "mitochondrial_intermembrane"}
41
+ PROTON = {"h"} # templates usually leave protons out; never counted against a candidate
42
+
43
+
44
+ class BiggDataError(Exception):
45
+ pass
46
+
47
+
48
+ def data_dir() -> Path:
49
+ from ..registry import cache_dir
50
+ d = cache_dir().parent / "bigg"
51
+ d.mkdir(parents=True, exist_ok=True)
52
+ return d
53
+
54
+
55
+ # ----------------------------------------------------------------------------- index
56
+
57
+ def _norm(ns: str, v: str) -> str:
58
+ v = str(v).strip()
59
+ if ns == "chebi":
60
+ m = re.search(r"(\d+)$", v)
61
+ return f"CHEBI:{int(m.group(1))}" if m else v
62
+ if ns in ("kegg.compound", "kegg.reaction", "metanetx.chemical", "metanetx.reaction", "inchikey"):
63
+ return v.upper()
64
+ if ns in ("seed.compound", "seed.reaction"):
65
+ return v.lower()
66
+ if ns == "hmdb":
67
+ m = re.search(r"(\d+)$", v)
68
+ return f"HMDB{m.group(1).zfill(7)}" if m else v
69
+ if ns == "metacyc.compound" or ns == "metacyc.reaction":
70
+ return v.upper()
71
+ return v
72
+
73
+
74
+ def _split_cid(cid: str) -> tuple[str, str]:
75
+ """'g6p_c' -> ('g6p', 'c'); compartment = the shortest known suffix."""
76
+ for c in sorted(COMPARTMENT, key=len, reverse=True):
77
+ if cid.endswith("_" + c):
78
+ return cid[: -len(c) - 1], c
79
+ i = cid.rfind("_")
80
+ return (cid[:i], cid[i + 1:]) if i > 0 else (cid, "")
81
+
82
+
83
+ class BiggIndex:
84
+ def __init__(self, metabolites: list[dict], reactions: list[dict]):
85
+ self.mets: dict[str, dict] = {}
86
+ for row in metabolites:
87
+ uid = row.get("universalcomponent__bigg_id") or str(row.get("bigg_id", "")).split(":")[0]
88
+ m = self.mets.setdefault(uid, {"id": uid, "name": None, "names": [], "formula": None, "charge": None, "xrefs": {}, "old": set(), "comps": set()})
89
+ if row.get("charge") == 0 or m["formula"] is None:
90
+ m["formula"], m["charge"] = row.get("formula"), row.get("charge")
91
+ if row.get("charge") == 0 and row.get("name"):
92
+ m["name"] = row["name"]
93
+ for n in (row.get("name"), row.get("universalcomponent__name")):
94
+ if n and n not in m["names"]:
95
+ m["names"].append(n)
96
+ m["old"].update(row.get("universalcomponent__old_bigg_ids") or [])
97
+ for cc in row.get("compartmentalized_components") or []:
98
+ m["comps"].add(_split_cid(cc.split(":")[0])[1])
99
+ for x in row.get("cross_references") or []:
100
+ ns = MET_NS.get(x.get("namespace"))
101
+ if ns and not x.get("source_obsolete"):
102
+ m["xrefs"].setdefault(ns, set()).add(_norm(ns, x["identifier"]))
103
+ self.by_xref: dict[str, set[str]] = {}
104
+ self.by_name: dict[str, set[str]] = {}
105
+ self.by_old: dict[str, str] = {}
106
+ for m in self.mets.values():
107
+ m["name"] = m["name"] or (m["names"][0] if m["names"] else m["id"])
108
+ for ns, vals in m["xrefs"].items():
109
+ for v in vals:
110
+ self.by_xref.setdefault(f"{ns}:{v}", set()).add(m["id"])
111
+ for n in m["names"]:
112
+ self.by_name.setdefault(compact(n), set()).add(m["id"])
113
+ for o in m["old"]:
114
+ self.by_old[o] = m["id"]
115
+
116
+ self.rxns: dict[str, dict] = {}
117
+ for row in reactions:
118
+ rid = row.get("universalreaction__bigg_id") or row.get("bigg_id")
119
+ r = self.rxns.get(rid)
120
+ if r is None:
121
+ parts = []
122
+ for coef, cid in row.get("universalreaction__participants") or []:
123
+ base, comp = _split_cid(cid)
124
+ parts.append((float(coef), base, comp))
125
+ r = self.rxns[rid] = {
126
+ "id": rid, "name": row.get("universalreaction__name") or rid, "parts": parts,
127
+ "transport": bool(row.get("universalreaction__is_transport")), "exchange": bool(row.get("universalreaction__is_exchange")),
128
+ "pseudo": bool(row.get("universalreaction__is_pseudo")), "xrefs": {}, "ec": set(), "old": set(row.get("universalreaction__old_bigg_ids") or []),
129
+ }
130
+ for x in row.get("cross_references") or []:
131
+ if x.get("source_obsolete"):
132
+ continue
133
+ if x.get("namespace") == "ec-code":
134
+ r["ec"].add(x["identifier"])
135
+ continue
136
+ ns = RXN_NS.get(x.get("namespace"))
137
+ if ns:
138
+ r["xrefs"].setdefault(ns, set()).add(_norm(ns, x["identifier"]))
139
+ self.rxn_by_met: dict[str, set[str]] = {}
140
+ self.rxn_by_old: dict[str, str] = {}
141
+ for r in self.rxns.values():
142
+ for _, base, _c in r["parts"]:
143
+ self.rxn_by_met.setdefault(base, set()).add(r["id"])
144
+ for o in r["old"]:
145
+ self.rxn_by_old[o] = r["id"]
146
+
147
+ # ------------------------------------------------------------------ metabolites
148
+
149
+ def met_candidate(self, uid: str, score: float, match: str) -> dict:
150
+ m = self.mets[uid]
151
+ ids = {ns: sorted(v) for ns, v in m["xrefs"].items()}
152
+ ids["bigg.metabolite"] = [uid]
153
+ return {"name": m["name"], "formula": m["formula"], "charge": m["charge"], "synonyms": [n for n in m["names"] if n != m["name"]][:12],
154
+ "identifiers": ids, "mnx": (ids.get("metanetx.chemical") or [None])[0], "structured": bool(m["formula"]),
155
+ "sources": ["BiGG"], "score": score, "match": match, "note": f"BiGG universal {uid}" + (f" · compartments in models: {', '.join(sorted(m['comps']))}" if m["comps"] else "")}
156
+
157
+ def resolve(self, identifiers: dict) -> set[str]:
158
+ """BiGG universal metabolites for a set of identifiers (template entity)."""
159
+ out: set[str] = set()
160
+ for ns, vals in (identifiers or {}).items():
161
+ for v in vals or []:
162
+ if ns == "bigg.metabolite":
163
+ v = re.sub(r"^M_", "", str(v))
164
+ if v in self.mets:
165
+ out.add(v)
166
+ elif v in self.by_old:
167
+ out.add(self.by_old[v])
168
+ continue
169
+ key = MET_NS.get(ns, ns if ns in MET_NS.values() else None)
170
+ if key:
171
+ out |= self.by_xref.get(f"{key}:{_norm(key, v)}", set())
172
+ return out
173
+
174
+ def search_metabolites(self, q: str, limit: int = 8) -> list[dict]:
175
+ q = q.strip()
176
+ if not q:
177
+ return []
178
+ hits: dict[str, tuple[float, str]] = {}
179
+
180
+ def add(uid: str, score: float, why: str):
181
+ if uid in self.mets and score > hits.get(uid, (0, ""))[0]:
182
+ hits[uid] = (score, why)
183
+
184
+ base = re.sub(r"^M_", "", q)
185
+ if base in self.mets:
186
+ add(base, 1.0, f"BiGG ID {base}")
187
+ if base in self.by_old:
188
+ add(self.by_old[base], 0.97, f"superseded BiGG ID {base}")
189
+ stripped = _split_cid(base)[0]
190
+ if stripped != base and stripped in self.mets:
191
+ add(stripped, 0.95, f"BiGG ID {stripped} (compartment suffix ignored)")
192
+ for pat, ns in ((r"^C\d{5}$", "kegg.compound"), (r"^CHEBI:\s*\d+$", "chebi"), (r"^MNXM\d+$", "metanetx.chemical"), (r"^cpd\d{5}$", "seed.compound"), (r"^HMDB\d+$", "hmdb")):
193
+ if re.match(pat, q, re.I):
194
+ for uid in self.by_xref.get(f"{ns}:{_norm(ns, q)}", ()):
195
+ add(uid, 1.0, f"identifier {q}")
196
+ k = compact(q)
197
+ if k:
198
+ for uid in self.by_name.get(k, ()):
199
+ m = self.mets[uid]
200
+ add(uid, 1.0 if compact(m["name"]) == k else 0.9, "exact name" if compact(m["name"]) == k else "name of a charge state")
201
+ if len(k) >= 3 and len(hits) < limit:
202
+ for key, uids in self.by_name.items():
203
+ if key.startswith(k) or (len(k) >= 4 and k in key):
204
+ for uid in uids:
205
+ add(uid, 0.7 if key.startswith(k) else 0.5, "name starts with the query" if key.startswith(k) else "name contains the query")
206
+ ranked = sorted(hits.items(), key=lambda kv: (-kv[1][0], len(self.mets[kv[0]]["name"])))[:limit]
207
+ return [self.met_candidate(uid, s, why) for uid, (s, why) in ranked]
208
+
209
+ # ------------------------------------------------------------------ reactions
210
+
211
+ def met_name(self, base: str) -> str:
212
+ m = self.mets.get(base)
213
+ return m["name"] if m else base
214
+
215
+ def equation(self, r: dict) -> str:
216
+ def term(c, base, comp):
217
+ n = abs(c)
218
+ return f"{'' if n == 1 else (int(n) if n == int(n) else n)} {self.met_name(base)} [{comp}]".strip()
219
+ left = " + ".join(term(c, b, k) for c, b, k in r["parts"] if c < 0)
220
+ right = " + ".join(term(c, b, k) for c, b, k in r["parts"] if c > 0)
221
+ return f"{left} ⇌ {right}"
222
+
223
+ def search_reactions(self, participants: list[dict], ec: list[str], limit: int = 8) -> dict:
224
+ resolved = [(p, self.resolve(p.get("identifiers") or {})) for p in participants]
225
+ notes = [f"{p.get('name') or '?'}: not found in BiGG through its identifiers" for p, ids in resolved if not ids]
226
+ subs = [x for x in resolved if (x[0].get("coefficient") or 0) < 0 and x[0].get("main", True) and x[1]]
227
+ prods = [x for x in resolved if (x[0].get("coefficient") or 0) > 0 and x[0].get("main", True) and x[1]]
228
+ if not subs or not prods:
229
+ return {"candidates": [], "notes": notes + ["BiGG needs the identity of at least one drawn substrate and one drawn product"]}
230
+ a, b = subs[0][1], prods[0][1]
231
+ cand = set().union(*(self.rxn_by_met.get(x, set()) for x in a)) & set().union(*(self.rxn_by_met.get(x, set()) for x in b))
232
+ comps_t = {p.get("compartment") for p, _ in resolved if p.get("compartment")}
233
+ spans = len(comps_t) > 1
234
+ out = []
235
+ for rid in cand:
236
+ r = self.rxns[rid]
237
+ if r["pseudo"] or r["exchange"]:
238
+ continue
239
+ side = {} # base -> (sign, coef, comp)
240
+ for c, base, comp in r["parts"]:
241
+ side.setdefault(base, []).append((1 if c > 0 else -1, abs(c), comp))
242
+ fwd = any(s < 0 for x in a for s, _, _ in side.get(x, [])) and any(s > 0 for x in b for s, _, _ in side.get(x, []))
243
+ rev = any(s > 0 for x in a for s, _, _ in side.get(x, [])) and any(s < 0 for x in b for s, _, _ in side.get(x, []))
244
+ if not (fwd or rev):
245
+ continue
246
+ flip = 1 if fwd else -1
247
+ evidence, got, total, coef_ok, comp_bad = [], 0.0, 0.0, True, 0
248
+ used: set[str] = set()
249
+ for p, ids in resolved:
250
+ w = 1.0 if p.get("main", True) else 0.5
251
+ total += w
252
+ want = (1 if (p.get("coefficient") or 0) > 0 else -1) * flip
253
+ role = "substrate" if (p.get("coefficient") or 0) < 0 else "product"
254
+ match = [(base, s, n, k) for base in ids for s, n, k in side.get(base, []) if s == want]
255
+ if match:
256
+ base, _, n, k = match[0]
257
+ used.add(base)
258
+ got += w
259
+ if abs(n - abs(p.get("coefficient") or 1)) > 1e-9:
260
+ coef_ok = False
261
+ tc = p.get("compartment")
262
+ comp_txt = ""
263
+ if tc and COMPARTMENT.get(k) and COMPARTMENT[k] != tc:
264
+ comp_bad += 1
265
+ comp_txt = f" — BiGG has it in {COMPARTMENT[k]} ({k})"
266
+ evidence.append({"ok": not comp_txt, "text": f"{p.get('name') or base} ({role}, BiGG {base}_{k}){comp_txt}"})
267
+ elif any(base in side for base in ids):
268
+ evidence.append({"ok": False, "text": f"{p.get('name') or '?'} is on the other side"})
269
+ else:
270
+ evidence.append({"ok": False, "text": f"{p.get('name') or '?'} not in this reaction"})
271
+ extra = [base for base in side if base not in used and base not in PROTON]
272
+ if extra:
273
+ evidence.append({"ok": None, "text": f"also in BiGG: {', '.join(self.met_name(x) for x in extra[:5])}"})
274
+ if not coef_ok:
275
+ evidence.append({"ok": False, "text": "stoichiometric coefficients differ"})
276
+ ec_ok = bool(set(ec) & r["ec"])
277
+ if ec and r["ec"]:
278
+ evidence.append({"ok": ec_ok, "text": f"EC {', '.join(sorted(r['ec']))}" + (" matches" if ec_ok else f" (template: {', '.join(ec)})")})
279
+ elif ec:
280
+ evidence.append({"ok": None, "text": "no EC number in BiGG for this reaction"})
281
+ if r["transport"] != spans:
282
+ evidence.append({"ok": False, "text": "BiGG marks it as a transport reaction" if r["transport"] else "the template reaction spans compartments, BiGG's does not"})
283
+ score = got / total * 0.75 + (0.1 if ec_ok else 0) + (0.05 if coef_ok else 0) + (0.1 if r["transport"] == spans else 0)
284
+ score -= 0.03 * len(extra) + 0.08 * comp_bad
285
+ ids_out = {ns: sorted(v) for ns, v in r["xrefs"].items()}
286
+ ids_out["bigg.reaction"] = [rid]
287
+ out.append({"name": rid, "canonicalName": r["name"], "ec": sorted(r["ec"]), "identifiers": ids_out, "equation": self.equation(r),
288
+ "direction": "as drawn" if fwd else "written in reverse in BiGG", "sources": ["BiGG"],
289
+ "score": round(max(0.0, min(1.0, score)), 3), "evidence": evidence})
290
+ out.sort(key=lambda c: (-c["score"], c["name"]))
291
+ return {"candidates": out[:limit], "notes": notes}
292
+
293
+
294
+ # ----------------------------------------------------------------------------- data files
295
+
296
+ _index: Optional[BiggIndex] = None
297
+ _index_stamp: Optional[float] = None
298
+ _lock = threading.Lock()
299
+
300
+
301
+ def _files() -> tuple[Path, Path, Path]:
302
+ d = data_dir()
303
+ return d / "metabolites.json", d / "reactions.json", d / "meta.json"
304
+
305
+
306
+ def status() -> dict:
307
+ met, rxn, meta = _files()
308
+ if not (met.exists() and rxn.exists() and meta.exists()):
309
+ return {"available": False, "source": SOURCE, "install": "gemsmap bigg-data"}
310
+ info = json.loads(meta.read_text(encoding="utf-8"))
311
+ return {"available": True, "source": info.get("source", SOURCE), "installed": info.get("installed"),
312
+ "metabolites": info.get("metabolites"), "reactions": info.get("reactions"), "bytes": info.get("bytes")}
313
+
314
+
315
+ def install(met_bytes: bytes, rxn_bytes: bytes, source: str = SOURCE) -> dict:
316
+ """Install the bulk metabolite and reaction tables of BiGG (the JSON files of bigg.bio/data_access)."""
317
+ try:
318
+ mets, rxns = json.loads(met_bytes), json.loads(rxn_bytes)
319
+ except ValueError as e:
320
+ raise BiggDataError(f"not BiGG JSON ({e})")
321
+ if not (isinstance(mets, list) and mets and "universalcomponent__bigg_id" in mets[0]):
322
+ raise BiggDataError("the metabolite file is not the BiGG metabolite download")
323
+ if not (isinstance(rxns, list) and rxns and "universalreaction__bigg_id" in rxns[0]):
324
+ raise BiggDataError("the reaction file is not the BiGG reaction download")
325
+ ix = BiggIndex(mets, rxns)
326
+ met, rxn, meta = _files()
327
+ met.write_bytes(met_bytes)
328
+ rxn.write_bytes(rxn_bytes)
329
+ meta.write_text(json.dumps({"source": source, "installed": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
330
+ "metabolites": len(ix.mets), "reactions": len(ix.rxns), "bytes": len(met_bytes) + len(rxn_bytes)}), encoding="utf-8")
331
+ global _index, _index_stamp
332
+ with _lock:
333
+ _index, _index_stamp = ix, meta.stat().st_mtime
334
+ return status()
335
+
336
+
337
+ BULK_URL = "https://bigg.bio/api/v3/download/{}"
338
+
339
+
340
+ def download_bulk(kind: str, log=print) -> bytes:
341
+ """One published bulk file of bigg.bio ('metabolites' or 'reactions'); only used by the one-time installation."""
342
+ import urllib.request
343
+ from .. import __version__
344
+ log(f"Downloading {BULK_URL.format(kind)} …")
345
+ req = urllib.request.Request(BULK_URL.format(kind), headers={"User-Agent": f"GEMsMAP/{__version__} (template data layer, one-time install)"})
346
+ with urllib.request.urlopen(req, timeout=600) as res:
347
+ return res.read()
348
+
349
+
350
+ def read_bulk(folder: Path, kind: str, log=print) -> bytes:
351
+ """A bulk file downloaded by hand from https://bigg.bio/data_access (a *metabolites*.json / *reactions*.json)."""
352
+ hits = sorted(p for p in Path(folder).glob("*.json") if kind in p.name.lower())
353
+ if not hits:
354
+ raise BiggDataError(f"no *{kind}*.json in {folder}")
355
+ log(f"Reading {hits[0]}")
356
+ return hits[0].read_bytes()
357
+
358
+
359
+ def install_from(folder: Optional[Path] = None, log=print) -> dict:
360
+ """Download (or read from ``folder``) the two bulk tables and install them: `gemsmap bigg-data` / `npm run bigg:data`."""
361
+ if folder:
362
+ return install(read_bulk(folder, "metabolites", log), read_bulk(folder, "reactions", log), f"{SOURCE} (local files)")
363
+ return install(download_bulk("metabolites", log), download_bulk("reactions", log), SOURCE)
364
+
365
+
366
+ def reset() -> None:
367
+ """Forget the in-memory index (tests)."""
368
+ global _index, _index_stamp
369
+ with _lock:
370
+ _index, _index_stamp = None, None
371
+
372
+
373
+ def index() -> Optional[BiggIndex]:
374
+ """The in-memory index of the installed tables (None until installed)."""
375
+ global _index, _index_stamp
376
+ met, rxn, meta = _files()
377
+ if not meta.exists():
378
+ return None
379
+ stamp = meta.stat().st_mtime
380
+ with _lock:
381
+ if _index is None or _index_stamp != stamp:
382
+ _index = BiggIndex(json.loads(met.read_text(encoding="utf-8")), json.loads(rxn.read_text(encoding="utf-8")))
383
+ _index_stamp = stamp
384
+ return _index
385
+
386
+
387
+ # ----------------------------------------------------------------------------- BiGG IDs for templates
388
+
389
+ def template_bigg_ids(entities: list[dict], reactions: list[dict]) -> dict:
390
+ """BiGG universal IDs for template entities (through their identifiers) and reactions (through their participants).
391
+ An ID is proposed only when it is unambiguous; otherwise the candidates are returned for review."""
392
+ ix = index()
393
+ if ix is None:
394
+ return {"available": False, "entities": {}, "reactions": {}}
395
+ ents = {}
396
+ for e in entities:
397
+ have = set((e.get("identifiers") or {}).get("bigg.metabolite") or [])
398
+ found = ix.resolve({k: v for k, v in (e.get("identifiers") or {}).items() if k != "bigg.metabolite"})
399
+ if not found:
400
+ ents[e["id"]] = {"status": "none"}
401
+ elif have & found:
402
+ ents[e["id"]] = {"status": "known", "bigg": sorted(have & found)[0]}
403
+ elif len(found) == 1:
404
+ uid = next(iter(found))
405
+ extra = {ns: sorted(v) for ns, v in ix.mets[uid]["xrefs"].items()}
406
+ ents[e["id"]] = {"status": "known" if uid in have else "one", "bigg": uid, "name": ix.mets[uid]["name"], "identifiers": extra}
407
+ else:
408
+ ents[e["id"]] = {"status": "several", "candidates": [{"bigg": u, "name": ix.mets[u]["name"]} for u in sorted(found)]}
409
+ rxns = {}
410
+ for r in reactions:
411
+ have = set((r.get("identifiers") or {}).get("bigg.reaction") or [])
412
+ res = ix.search_reactions(r.get("participants") or [], r.get("ec") or [], 3)
413
+ # proposed only when nothing contradicts the template (every participant present, same side, compartment,
414
+ # coefficient; EC agreeing when given) and the candidate stands out; extra BiGG cofactors are allowed
415
+ c = [x for x in res["candidates"] if all(e["ok"] is not False for e in x["evidence"])]
416
+ tied = [x for x in c if c and c[0]["score"] - x["score"] < 0.1]
417
+ if not c:
418
+ rxns[r["id"]] = {"status": "none", "notes": res["notes"]}
419
+ elif have & {x["name"] for x in tied}:
420
+ rxns[r["id"]] = {"status": "known", "bigg": sorted(have & {x["name"] for x in tied})[0]}
421
+ elif len(tied) > 1:
422
+ rxns[r["id"]] = {"status": "several", "candidates": [{"bigg": x["name"], "name": x["canonicalName"], "score": x["score"]} for x in c[:3]]}
423
+ else:
424
+ top = c[0]
425
+ rxns[r["id"]] = {"status": "known" if top["name"] in have else "one", "bigg": top["name"], "name": top["canonicalName"], "score": top["score"],
426
+ "identifiers": top["identifiers"], "ec": top["ec"], "equation": top["equation"]}
427
+ return {"available": True, "entities": ents, "reactions": rxns}
428
+
429
+
430
+ # ----------------------------------------------------------------------------- models exported by BiGG
431
+
432
+ def looks_like_bigg_export(model: dict) -> bool:
433
+ """bigg.bio model files: 'biggr' annotations and/or '__<model id>__' prefixes on model-specific entries."""
434
+ mid = model.get("id") or ""
435
+ mets = model.get("metabolites") or []
436
+ return any("biggr" in (m.get("annotation") or {}) for m in mets[:50]) or (bool(mid) and any(str(m.get("id", "")).startswith(f"__{mid}__") for m in mets[:200]))
437
+
438
+
439
+ def enrich_model(model: dict) -> tuple[dict, dict]:
440
+ """Normalize the IDs of a model file exported by bigg.bio and complete its annotations from the universal tables."""
441
+ mid = model.get("id") or ""
442
+ prefix = f"__{mid}__" if mid else None
443
+ fix = (lambda s: s.replace(prefix, "")) if prefix else (lambda s: s)
444
+ ix = index()
445
+ report = {"metabolites": 0, "metabolitesAnnotated": 0, "reactions": 0, "reactionsAnnotated": 0, "renamed": 0, "bigg": ix is not None}
446
+ seen: set[str] = set()
447
+ out_mets = []
448
+ for m in model.get("metabolites", []):
449
+ new_id = fix(m["id"])
450
+ if new_id in seen: # keep the original when the prefix-free ID is taken
451
+ new_id = m["id"]
452
+ seen.add(new_id)
453
+ report["renamed"] += new_id != m["id"]
454
+ ann = {k: v for k, v in (m.get("annotation") or {}).items() if k != "biggr"}
455
+ base = _split_cid(new_id)[0]
456
+ ann.setdefault("bigg.metabolite", base)
457
+ if ix and base in ix.mets:
458
+ for ns, vals in ix.mets[base]["xrefs"].items():
459
+ cur = ann.get(ns)
460
+ cur = cur if isinstance(cur, list) else [cur] if cur else []
461
+ ann[ns] = sorted(set(map(str, cur)) | vals)
462
+ report["metabolitesAnnotated"] += 1
463
+ report["metabolites"] += 1
464
+ out_mets.append({**m, "id": new_id, "annotation": ann})
465
+ rename = {m["id"]: o["id"] for m, o in zip(model.get("metabolites", []), out_mets)}
466
+ out_rxns = []
467
+ for r in model.get("reactions", []):
468
+ new_id = fix(r["id"])
469
+ ann = {k: v for k, v in (r.get("annotation") or {}).items() if k != "biggr"}
470
+ base = new_id
471
+ if ix and base not in ix.rxns:
472
+ base = ix.rxn_by_old.get(base, base)
473
+ ann.setdefault("bigg.reaction", base)
474
+ if ix and base in ix.rxns:
475
+ rr = ix.rxns[base]
476
+ for ns, vals in rr["xrefs"].items():
477
+ ann[ns] = sorted(vals)
478
+ if rr["ec"]:
479
+ ann["ec-code"] = sorted(rr["ec"])
480
+ report["reactionsAnnotated"] += 1
481
+ report["reactions"] += 1
482
+ out_rxns.append({**r, "id": new_id, "metabolites": {rename.get(k, fix(k)): v for k, v in r.get("metabolites", {}).items()}, "annotation": ann})
483
+ notes = dict(model.get("notes") or {})
484
+ notes["GEMsMAP"] = "BiGG export: IDs normalized; annotations completed from the BiGG universal tables" if ix else "BiGG export: IDs normalized"
485
+ return {**model, "metabolites": out_mets, "reactions": out_rxns, "notes": notes}, report
486
+
487
+
488
+
489
+ def normalize_bigg_json(data: bytes) -> tuple[bytes, Optional[dict]]:
490
+ """For a COBRA JSON exported by BiGG: normalized and annotated copy plus a report; other files unchanged."""
491
+ try:
492
+ model = json.loads(data)
493
+ except ValueError:
494
+ return data, None
495
+ if not isinstance(model, dict) or not looks_like_bigg_export(model):
496
+ return data, None
497
+ m, report = enrich_model(model)
498
+ return json.dumps(m).encode("utf-8"), report
@@ -0,0 +1,164 @@
1
+ """Result-vs-result comparison (B relative to reference A).
2
+
3
+ Every row is classified before any ratio is computed, so biologically distinct events are never
4
+ collapsed into one number:
5
+ both-zero | unchanged | changed | activated (0 → v) | inactivated (v → 0) | reversal (sign flip) | missing
6
+ Fold changes compare magnitudes |B| / |A| and are only defined for 'changed'/'unchanged' rows. For
7
+ activated/inactivated rows a log2FC is produced only when the caller explicitly sets a pseudocount
8
+ (the row is then flagged). Direction reversals never get a fold change.
9
+ """
10
+ import math
11
+ from typing import Optional
12
+
13
+ from ..errors import ScienceError, num
14
+ from ..schemas import ResultPayload
15
+
16
+
17
+ def classify(a: Optional[float], b: Optional[float], tol: float) -> str:
18
+ if a is None or b is None:
19
+ return "missing"
20
+ za, zb = abs(a) <= tol, abs(b) <= tol
21
+ if za and zb:
22
+ return "both-zero"
23
+ if za:
24
+ return "activated"
25
+ if zb:
26
+ return "inactivated"
27
+ if (a > 0) != (b > 0):
28
+ return "reversal"
29
+ return "unchanged" if abs(b - a) <= tol else "changed"
30
+
31
+
32
+ def _row(id_: str, a, b, tol: float, pseudo: Optional[float]) -> dict:
33
+ cat = classify(a, b, tol)
34
+ log2fc = fc = None
35
+ used_pseudo = False
36
+ if cat in ("changed", "unchanged"):
37
+ fc = abs(b) / abs(a)
38
+ log2fc = math.log2(fc)
39
+ elif cat in ("activated", "inactivated") and pseudo:
40
+ fc = (abs(b) + pseudo) / (abs(a) + pseudo)
41
+ log2fc = math.log2(fc)
42
+ used_pseudo = True
43
+ delta = (b - a) if a is not None and b is not None else None
44
+ return {"id": id_, "a": num(a), "b": num(b), "delta": num(delta), "absDelta": num(abs(delta)) if delta is not None else None,
45
+ "foldChange": num(fc), "log2fc": num(log2fc), "category": cat, "pseudocount": used_pseudo}
46
+
47
+
48
+ def _counts(rows: list[dict]) -> dict:
49
+ out: dict[str, int] = {}
50
+ for r in rows:
51
+ out[r["category"]] = out.get(r["category"], 0) + 1
52
+ return out
53
+
54
+
55
+ def _compare_vectors(va: dict, vb: dict, tol: float, pseudo: Optional[float]) -> list[dict]:
56
+ ids = list(dict.fromkeys([*va.keys(), *vb.keys()]))
57
+ return [_row(i, va.get(i), vb.get(i), tol, pseudo) for i in ids]
58
+
59
+
60
+ def _config_diff(a: ResultPayload, b: ResultPayload) -> dict:
61
+ ma, mb = a.metadata or {}, b.metadata or {}
62
+ oa, ob = ma.get("objective") or {}, mb.get("objective") or {}
63
+ meda, medb = ma.get("medium") or {}, mb.get("medium") or {}
64
+ medium = []
65
+ for rid in sorted(set(meda) | set(medb)):
66
+ x, y = meda.get(rid), medb.get(rid)
67
+ if x != y:
68
+ medium.append({"reaction": rid, "a": x, "b": y})
69
+ ba = {c["reaction"]: c["current"] for c in ma.get("boundChanges") or []}
70
+ bb = {c["reaction"]: c["current"] for c in mb.get("boundChanges") or []}
71
+ bounds = []
72
+ for rid in sorted(set(ba) | set(bb)):
73
+ if ba.get(rid) != bb.get(rid):
74
+ bounds.append({"reaction": rid, "a": ba.get(rid), "b": bb.get(rid)})
75
+ return {
76
+ "sameModel": (ma.get("model") or {}).get("checksum") == (mb.get("model") or {}).get("checksum"),
77
+ "objective": {"a": oa, "b": ob, "changed": oa != ob},
78
+ "methods": {"a": a.method, "b": b.method},
79
+ "medium": medium,
80
+ "bounds": bounds,
81
+ }
82
+
83
+
84
+ def compare(a: ResultPayload, b: ResultPayload, tol: float, pseudo: Optional[float]) -> dict:
85
+ for r, label in ((a, "A"), (b, "B")):
86
+ if r.solver_status and r.solver_status != "optimal":
87
+ raise ScienceError(f"Result {label} is not optimal", f"'{r.name}' has solver status '{r.solver_status}'.",
88
+ hints=["Only optimal solutions can be compared."])
89
+ fva_a, fva_b = a.fva is not None, b.fva is not None
90
+ if fva_a != fva_b:
91
+ raise ScienceError("Cannot compare FVA with a flux distribution",
92
+ "FVA gives an independent feasible interval per reaction, not one flux vector.",
93
+ hints=["Compare two FVA results, or two FBA/pFBA/loopless results."])
94
+ out = {"a": {"id": a.id, "name": a.name, "method": a.method}, "b": {"id": b.id, "name": b.name, "method": b.method},
95
+ "zeroTolerance": tol, "pseudocount": pseudo, "config": _config_diff(a, b)}
96
+ if fva_a:
97
+ rows = []
98
+ for rid in dict.fromkeys([*a.fva.keys(), *b.fva.keys()]):
99
+ ia, ib = a.fva.get(rid), b.fva.get(rid)
100
+ if not ia or not ib or None in (ia.get("minimum"), ia.get("maximum"), ib.get("minimum"), ib.get("maximum")):
101
+ rows.append({"id": rid, "category": "missing"})
102
+ continue
103
+ wa, wb = ia["maximum"] - ia["minimum"], ib["maximum"] - ib["minimum"]
104
+ overlap = min(ia["maximum"], ib["maximum"]) - max(ia["minimum"], ib["minimum"]) >= -tol
105
+ dw = wb - wa
106
+ cat = "unchanged" if abs(ia["minimum"] - ib["minimum"]) <= tol and abs(ia["maximum"] - ib["maximum"]) <= tol \
107
+ else ("disjoint" if not overlap else "narrowed" if dw < -tol else "widened" if dw > tol else "shifted")
108
+ rows.append({"id": rid, "aMin": ia["minimum"], "aMax": ia["maximum"], "bMin": ib["minimum"], "bMax": ib["maximum"],
109
+ "aWidth": num(wa), "bWidth": num(wb), "deltaWidth": num(dw), "absDeltaWidth": num(abs(dw)),
110
+ "overlap": overlap, "category": cat})
111
+ out.update({"kind": "fva", "reactions": rows, "counts": _counts(rows)})
112
+ return out
113
+ if a.reaction_fluxes is None or b.reaction_fluxes is None:
114
+ raise ScienceError("Missing flux vectors", "Both results need reaction fluxes.")
115
+ reactions = _compare_vectors(a.reaction_fluxes, b.reaction_fluxes, tol, pseudo)
116
+ metabolites = _compare_vectors(a.metabolite_turnover or {}, b.metabolite_turnover or {}, tol, pseudo) \
117
+ if a.metabolite_turnover and b.metabolite_turnover else []
118
+ exchanges = []
119
+ ea, eb = a.exchanges or {}, b.exchanges or {}
120
+ for rid in dict.fromkeys([*ea.keys(), *eb.keys()]):
121
+ xa, xb = ea.get(rid) or {}, eb.get(rid) or {}
122
+ row = _row(rid, xa.get("flux"), xb.get("flux"), tol, pseudo)
123
+ net_a = (xa.get("uptake") or 0) - (xa.get("secretion") or 0)
124
+ net_b = (xb.get("uptake") or 0) - (xb.get("secretion") or 0)
125
+ if row["category"] == "reversal":
126
+ row["switch"] = "uptake → secretion" if net_a > 0 else "secretion → uptake"
127
+ row.update({"metabolite": xa.get("metabolite") or xb.get("metabolite"), "kind": xa.get("kind") or xb.get("kind"),
128
+ "uptakeA": xa.get("uptake"), "uptakeB": xb.get("uptake"),
129
+ "secretionA": xa.get("secretion"), "secretionB": xb.get("secretion"),
130
+ "deltaUptake": num((xb.get("uptake") or 0) - (xa.get("uptake") or 0)),
131
+ "deltaSecretion": num((xb.get("secretion") or 0) - (xa.get("secretion") or 0)),
132
+ "netA": num(net_a), "netB": num(net_b)})
133
+ exchanges.append(row)
134
+ out.update({"kind": "flux", "reactions": reactions, "metabolites": metabolites, "exchanges": exchanges,
135
+ "counts": _counts(reactions),
136
+ "objective": {"a": a.objective_value, "b": b.objective_value}})
137
+ return out
138
+
139
+
140
+ def explain_turnover(entry, met_id: str, fa: dict, fb: dict, tol: float) -> dict:
141
+ """Per-reaction contributions 0.5·|S·v| to a metabolite's turnover in A and B (descriptive, not causal)."""
142
+ model = entry.model
143
+ if met_id not in model.metabolites:
144
+ raise ScienceError("Unknown metabolite", met_id, status=404)
145
+ met = model.metabolites.get_by_id(met_id)
146
+
147
+ def role(c, v):
148
+ p = c * v
149
+ return "produces" if p > tol else "consumes" if p < -tol else "inactive"
150
+
151
+ rows = []
152
+ for r in met.reactions:
153
+ c = float(r.metabolites[met])
154
+ va, vb = fa.get(r.id) or 0.0, fb.get(r.id) or 0.0
155
+ ca, cb = 0.5 * abs(c * va), 0.5 * abs(c * vb)
156
+ rows.append({"reaction": r.id, "name": r.name or "", "coefficient": c, "fluxA": num(va), "fluxB": num(vb),
157
+ "contributionA": num(ca), "contributionB": num(cb), "delta": num(cb - ca),
158
+ "roleA": role(c, va), "roleB": role(c, vb), "category": classify(va, vb, tol)})
159
+ rows.sort(key=lambda x: -abs(x["delta"] or 0))
160
+ ta = sum(x["contributionA"] or 0 for x in rows)
161
+ tb = sum(x["contributionB"] or 0 for x in rows)
162
+ return {"metabolite": met_id, "name": met.name or met_id, "turnoverA": num(ta), "turnoverB": num(tb),
163
+ "delta": num(tb - ta), "rows": rows,
164
+ "note": "Flux contributions to the turnover change. Descriptive decomposition — not a causal inference."}