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.
- cobragui/__init__.py +4 -0
- cobragui/errors.py +37 -0
- cobragui/main.py +331 -0
- cobragui/registry.py +68 -0
- cobragui/schemas.py +180 -0
- cobragui/services/__init__.py +0 -0
- cobragui/services/annotation_service.py +745 -0
- cobragui/services/bigg_service.py +498 -0
- cobragui/services/comparison_service.py +164 -0
- cobragui/services/edit_service.py +942 -0
- cobragui/services/export_service.py +118 -0
- cobragui/services/identity_service.py +429 -0
- cobragui/services/medium_service.py +117 -0
- cobragui/services/metanetx.py +209 -0
- cobragui/services/model_service.py +480 -0
- cobragui/services/search_service.py +97 -0
- cobragui/services/simulation_service.py +427 -0
- gemsmap/__init__.py +6 -0
- gemsmap/__main__.py +6 -0
- gemsmap/cli.py +172 -0
- gemsmap/server.py +32 -0
- gemsmap/web/assets/index-DzyjjcSI.js +79 -0
- gemsmap/web/assets/index-N-gkf6XD.css +1 -0
- gemsmap/web/brand/cobragui-logo.png +0 -0
- gemsmap/web/brand/mapbuilder-logo.png +0 -0
- gemsmap/web/brand/templates-logo.png +0 -0
- gemsmap/web/examples/fva_2conditions.csv +33 -0
- gemsmap/web/examples/pfba_4conditions.csv +33 -0
- gemsmap/web/examples/timecourse.csv +10 -0
- gemsmap/web/favicon.svg +33 -0
- gemsmap/web/index.html +17 -0
- gemsmap-0.3.0.dist-info/METADATA +82 -0
- gemsmap-0.3.0.dist-info/RECORD +36 -0
- gemsmap-0.3.0.dist-info/WHEEL +4 -0
- gemsmap-0.3.0.dist-info/entry_points.txt +2 -0
- gemsmap-0.3.0.dist-info/licenses/LICENSE +21 -0
|
@@ -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."}
|