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,942 @@
1
+ """Structural edits of the working model: reactions, metabolites and compartments.
2
+
3
+ Edits are a reversible layer on top of the imported file, like the metabolite curation:
4
+
5
+ - An edit is a *transaction* of primitive operations
6
+ ``{"type": "reaction" | "metabolite" | "compartment", "before": snapshot | None, "after": snapshot | None}``.
7
+ ``before = None`` adds the entity, ``after = None`` removes it, both = update (the id may change: rename).
8
+ - The inverse of a transaction is the reversed list with before/after swapped, so undo and redo never
9
+ copy the model (copying a genome-scale model takes seconds).
10
+ - A transaction is validated first (pure checks on the model plus the transaction's own additions),
11
+ then applied to the real ``cobra.Model`` used by every simulation. If applying fails midway, the
12
+ operations already done are reverted; if even that fails, the model is rebuilt from the file and the
13
+ log. An invalid edit never leaves the model half-modified.
14
+ - The log is saved per model (``<cache>/<id>.edits.json``), re-applied when the model is loaded again
15
+ and exported as a model patch (``model_patch.json``): the transactions, plus the net list of
16
+ reactions / metabolites added, removed and changed.
17
+
18
+ Validation separates errors (the edit is refused) from warnings (shown, never blocking): an
19
+ unbalanced reaction is a warning, because biomass, pseudo-reactions and boundaries are unbalanced by
20
+ design.
21
+ """
22
+ from __future__ import annotations
23
+
24
+ import hashlib
25
+ import json
26
+ import math
27
+ import re
28
+ import time
29
+ import uuid
30
+ from typing import Any, Optional
31
+
32
+ import cobra
33
+
34
+ from .. import registry
35
+ from ..errors import ScienceError, bound_in, num
36
+ from . import model_service as ms
37
+
38
+ SID = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
39
+ SBO = {"exchange": "SBO:0000627", "demand": "SBO:0000628", "sink": "SBO:0000632"}
40
+ # identifiers compared for duplicate detection (annotation keys, lower-case)
41
+ XREF_KEYS = ("metanetx.chemical", "kegg.compound", "chebi", "bigg.metabolite", "seed.compound", "inchikey",
42
+ "metacyc.compound", "hmdb")
43
+ RXN_XREF_KEYS = ("metanetx.reaction", "rhea", "kegg.reaction", "bigg.reaction", "seed.reaction", "metacyc.reaction")
44
+
45
+
46
+ # ----------------------------------------------------------------------------- snapshots
47
+
48
+ def _ann_in(a: Any) -> dict:
49
+ out = {}
50
+ for k, v in (a or {}).items():
51
+ if isinstance(v, (list, tuple)):
52
+ vals = [str(x).strip() for x in v if str(x).strip()]
53
+ if vals:
54
+ out[str(k)] = vals if len(vals) > 1 else vals[0]
55
+ elif v not in (None, ""):
56
+ out[str(k)] = str(v).strip()
57
+ return out
58
+
59
+
60
+ def snap_reaction(model: cobra.Model, r: cobra.Reaction) -> dict:
61
+ obj = ms.objective_coefficients(model)
62
+ return {
63
+ "id": r.id, "name": r.name or "", "lb": num(r.lower_bound), "ub": num(r.upper_bound),
64
+ "subsystem": r.subsystem or "", "gpr": r.gene_reaction_rule or "",
65
+ "metabolites": {m.id: float(c) for m, c in r.metabolites.items()},
66
+ "annotation": _ann_in(r.annotation), "notes": ms._notes(r.notes),
67
+ "objective": float(obj.get(r.id, 0.0)),
68
+ }
69
+
70
+
71
+ def snap_metabolite(m: cobra.Metabolite) -> dict:
72
+ return {
73
+ "id": m.id, "name": m.name or "", "compartment": m.compartment or "",
74
+ "formula": m.formula or "", "charge": m.charge if isinstance(m.charge, (int, float)) else None,
75
+ "annotation": _ann_in(m.annotation), "notes": ms._notes(m.notes),
76
+ }
77
+
78
+
79
+ known_compartments = ms.known_compartments
80
+
81
+
82
+ # ----------------------------------------------------------------------------- normalizing requests
83
+
84
+ def _f(x, what: str, errors: list) -> Optional[float]:
85
+ if x is None or x == "":
86
+ return None
87
+ try:
88
+ v = float(x)
89
+ except (TypeError, ValueError):
90
+ errors.append(f"{what}: “{x}” is not a number")
91
+ return None
92
+ if math.isnan(v):
93
+ errors.append(f"{what} is NaN")
94
+ return None
95
+ return v if math.isfinite(v) else None # ±∞ = unbounded
96
+
97
+
98
+ def norm_reaction(d: dict, errors: list) -> dict:
99
+ mets = {}
100
+ for k, c in (d.get("metabolites") or {}).items():
101
+ try:
102
+ v = float(c)
103
+ except (TypeError, ValueError):
104
+ errors.append(f"coefficient of {k}: “{c}” is not a number")
105
+ continue
106
+ if not math.isfinite(v):
107
+ errors.append(f"coefficient of {k} must be a finite number")
108
+ elif v == 0:
109
+ errors.append(f"coefficient of {k} is 0 (remove the metabolite instead)")
110
+ else:
111
+ mets[str(k).strip()] = v
112
+ obj = _f(d.get("objective"), "objective coefficient", errors) or 0.0
113
+ return {
114
+ "id": str(d.get("id") or "").strip(), "name": str(d.get("name") or "").strip(),
115
+ "lb": _f(d.get("lb"), "lower bound", errors), "ub": _f(d.get("ub"), "upper bound", errors),
116
+ "subsystem": str(d.get("subsystem") or "").strip(), "gpr": " ".join(str(d.get("gpr") or "").split()),
117
+ "metabolites": mets, "annotation": _ann_in(d.get("annotation")), "notes": ms._notes(d.get("notes")),
118
+ "objective": obj,
119
+ }
120
+
121
+
122
+ def norm_metabolite(d: dict, errors: list) -> dict:
123
+ charge = d.get("charge")
124
+ if charge in ("", None):
125
+ charge = None
126
+ else:
127
+ try:
128
+ charge = float(charge)
129
+ if not math.isfinite(charge):
130
+ errors.append("charge must be a finite number")
131
+ charge = None
132
+ elif charge == int(charge):
133
+ charge = int(charge)
134
+ except (TypeError, ValueError):
135
+ errors.append(f"charge: “{d.get('charge')}” is not a number")
136
+ charge = None
137
+ return {
138
+ "id": str(d.get("id") or "").strip(), "name": str(d.get("name") or "").strip(),
139
+ "compartment": str(d.get("compartment") or "").strip(), "formula": str(d.get("formula") or "").strip(),
140
+ "charge": charge, "annotation": _ann_in(d.get("annotation")), "notes": ms._notes(d.get("notes")),
141
+ }
142
+
143
+
144
+ # ----------------------------------------------------------------------------- GPR & formulas
145
+
146
+ _GPR_TOKEN = re.compile(r"\s*(\(|\)|[^\s()]+)")
147
+
148
+
149
+ def gpr_error(rule: str) -> Optional[str]:
150
+ """Syntax check of a gene-reaction rule: gene ids combined with and / or and parentheses."""
151
+ if not rule.strip():
152
+ return None
153
+ toks = [t.lower() if t.lower() in ("and", "or") else t for t in _GPR_TOKEN.findall(rule)]
154
+ toks = ["and" if t == "&" else "or" if t == "|" else t for t in toks]
155
+ pos = 0
156
+
157
+ def expr():
158
+ nonlocal pos
159
+ term()
160
+ while pos < len(toks) and toks[pos] in ("and", "or"):
161
+ pos += 1
162
+ term()
163
+
164
+ def term():
165
+ nonlocal pos
166
+ if pos >= len(toks):
167
+ raise ValueError("the rule ends where a gene or “(” was expected")
168
+ t = toks[pos]
169
+ if t == "(":
170
+ pos += 1
171
+ expr()
172
+ if pos >= len(toks) or toks[pos] != ")":
173
+ raise ValueError("a “(” is not closed")
174
+ pos += 1
175
+ elif t in (")", "and", "or"):
176
+ raise ValueError(f"unexpected “{t}” where a gene was expected")
177
+ else:
178
+ pos += 1
179
+
180
+ try:
181
+ expr()
182
+ if pos != len(toks):
183
+ raise ValueError(f"unexpected “{toks[pos]}”")
184
+ except ValueError as e:
185
+ return str(e)
186
+ return None
187
+
188
+
189
+ _ELEM = re.compile(r"([A-Z][a-z]?)(\d*\.?\d*)")
190
+
191
+
192
+ def parse_formula(f: str) -> Optional[dict[str, float]]:
193
+ """Element counts of a flat formula (C6H12O6, C10H12N5O13P3, R groups count as 'R'); None if unparsable."""
194
+ f = (f or "").strip()
195
+ if not f:
196
+ return None
197
+ pos, out = 0, {}
198
+ for m in _ELEM.finditer(f):
199
+ if m.start() != pos:
200
+ return None
201
+ n = float(m.group(2)) if m.group(2) else 1.0
202
+ out[m.group(1)] = out.get(m.group(1), 0.0) + n
203
+ pos = m.end()
204
+ return out if pos == len(f) else None
205
+
206
+
207
+ def balance(mets: dict[str, float], info: dict[str, dict]) -> dict:
208
+ """Mass and charge balance of a stoichiometry, from the metabolites' formulas and charges."""
209
+ missing_f = [m for m in mets if parse_formula(info.get(m, {}).get("formula") or "") is None]
210
+ missing_c = [m for m in mets if info.get(m, {}).get("charge") is None]
211
+ mass = charge = None
212
+ if not missing_f:
213
+ acc: dict[str, float] = {}
214
+ for m, c in mets.items():
215
+ for el, n in parse_formula(info[m]["formula"]).items():
216
+ acc[el] = acc.get(el, 0.0) + c * n
217
+ mass = {k: round(v, 6) for k, v in sorted(acc.items()) if abs(v) > 1e-6}
218
+ if not missing_c:
219
+ charge = round(sum(c * float(info[m]["charge"]) for m, c in mets.items()), 6)
220
+ return {"mass": mass, "charge": charge, "missingFormula": missing_f, "missingCharge": missing_c}
221
+
222
+
223
+ # ----------------------------------------------------------------------------- virtual view (validation)
224
+
225
+ class View:
226
+ """The model as it will be after the operations seen so far — without modifying it."""
227
+
228
+ def __init__(self, model: cobra.Model):
229
+ self.model = model
230
+ self.rxn: dict[str, Optional[dict]] = {}
231
+ self.met: dict[str, Optional[dict]] = {}
232
+ self.comp: dict[str, Optional[str]] = {}
233
+ self._known_comp = known_compartments(model)
234
+
235
+ def has_rxn(self, i: str) -> bool:
236
+ return self.rxn[i] is not None if i in self.rxn else i in self.model.reactions
237
+
238
+ def get_met(self, i: str) -> Optional[dict]:
239
+ if i in self.met:
240
+ return self.met[i]
241
+ return snap_metabolite(self.model.metabolites.get_by_id(i)) if i in self.model.metabolites else None
242
+
243
+ def has_comp(self, c: str) -> bool:
244
+ return self.comp[c] is not None if c in self.comp else c in self._known_comp
245
+
246
+ def met_reactions(self, i: str) -> list[str]:
247
+ """Reactions using metabolite i in the view."""
248
+ out = set()
249
+ if i in self.model.metabolites:
250
+ out = {r.id for r in self.model.metabolites.get_by_id(i).reactions}
251
+ for rid, r in self.rxn.items():
252
+ if r is None or i not in r["metabolites"]:
253
+ out.discard(rid)
254
+ if r is not None and i in r["metabolites"]:
255
+ out.add(r["id"])
256
+ return sorted(x for x in out if self.has_rxn(x))
257
+
258
+
259
+ def _xrefs(ann: dict, keys=XREF_KEYS) -> set[tuple[str, str]]:
260
+ out = set()
261
+ for k, v in (ann or {}).items():
262
+ kk = str(k).lower()
263
+ if kk in keys:
264
+ for x in (v if isinstance(v, (list, tuple)) else [v]):
265
+ x = str(x).strip()
266
+ x = x.upper().replace("CHEBI:", "") if kk == "chebi" else x
267
+ out.add((kk, x.lower()))
268
+ return out
269
+
270
+
271
+ def _compact(s: str) -> str:
272
+ return re.sub(r"[^a-z0-9]+", "", (s or "").lower())
273
+
274
+
275
+ def duplicate_metabolites(model: cobra.Model, m: dict, exclude: Optional[str]) -> list[dict]:
276
+ """Existing metabolites that may be the same compound: shared identifiers or the same name."""
277
+ xs, name = _xrefs(m["annotation"]), _compact(m["name"])
278
+ out = []
279
+ for x in model.metabolites:
280
+ if x.id == exclude:
281
+ continue
282
+ shared = xs & _xrefs(_ann_in(x.annotation))
283
+ same_name = bool(name) and _compact(x.name) == name
284
+ if not shared and not same_name:
285
+ continue
286
+ reasons = [f"{k} {v}" for k, v in sorted(shared)][:3] + (["same name"] if same_name else [])
287
+ if m["formula"] and x.formula and m["formula"] == x.formula and shared:
288
+ reasons.append("same formula")
289
+ out.append({"id": x.id, "name": x.name or "", "compartment": x.compartment or "",
290
+ "sameCompartment": x.compartment == m["compartment"], "reasons": reasons})
291
+ out.sort(key=lambda d: (not d["sameCompartment"], d["id"]))
292
+ return out[:12]
293
+
294
+
295
+ def duplicate_reactions(model: cobra.Model, r: dict, exclude: Optional[str]) -> list[dict]:
296
+ """Reactions with the same participants and proportional coefficients (either direction), or a shared identifier."""
297
+ mets = r["metabolites"]
298
+ out = []
299
+ if mets:
300
+ first = next(iter(mets))
301
+ cand = model.metabolites.get_by_id(first).reactions if first in model.metabolites else []
302
+ for x in cand:
303
+ if x.id == exclude or len(x.metabolites) != len(mets):
304
+ continue
305
+ st = {m.id: c for m, c in x.metabolites.items()}
306
+ if set(st) != set(mets):
307
+ continue
308
+ ratio = st[first] / mets[first]
309
+ if all(abs(st[k] - ratio * v) <= 1e-9 * max(1.0, abs(st[k])) for k, v in mets.items()):
310
+ out.append({"id": x.id, "name": x.name or "", "reason": "same participants and coefficients" if ratio > 0 else "same participants, written in the opposite direction",
311
+ "scaled": abs(abs(ratio) - 1) > 1e-9})
312
+ xs = _xrefs(r["annotation"], RXN_XREF_KEYS)
313
+ if xs:
314
+ for x in model.reactions:
315
+ if x.id == exclude or any(d["id"] == x.id for d in out):
316
+ continue
317
+ shared = xs & _xrefs(_ann_in(x.annotation), RXN_XREF_KEYS)
318
+ if shared:
319
+ k, v = sorted(shared)[0]
320
+ out.append({"id": x.id, "name": x.name or "", "reason": f"same {k} {v}", "scaled": False})
321
+ return out[:10]
322
+
323
+
324
+ def boundary_kind(r: dict) -> Optional[str]:
325
+ if len(r["metabolites"]) != 1:
326
+ return None
327
+ sbo = str(r["annotation"].get("sbo") or "")
328
+ for k, v in SBO.items():
329
+ if sbo == v:
330
+ return k
331
+ rid = r["id"].upper()
332
+ if rid.startswith(("DM_", "R_DM_")):
333
+ return "demand"
334
+ if rid.startswith(("SK_", "SINK_", "R_SK_")):
335
+ return "sink"
336
+ if rid.startswith(("EX_", "R_EX_")):
337
+ return "exchange"
338
+ return None # a one-sided draft is not assumed to be a boundary reaction
339
+
340
+
341
+ def _check_reaction(v: View, before: Optional[dict], r: dict, errors: list, warnings: list, info: list) -> dict:
342
+ rid = r["id"]
343
+ if not rid:
344
+ errors.append("Reaction ID is required")
345
+ elif re.search(r"\s", rid):
346
+ errors.append(f"Reaction ID “{rid}” contains spaces")
347
+ elif (not before or before["id"] != rid) and v.has_rxn(rid):
348
+ errors.append(f"Reaction ID “{rid}” is already used by another reaction")
349
+ elif not SID.match(rid):
350
+ warnings.append(f"“{rid}” is not a valid SBML identifier; SBML export escapes the special characters")
351
+ if not r["metabolites"]:
352
+ errors.append("The reaction has no metabolites")
353
+ unknown = [m for m in r["metabolites"] if v.get_met(m) is None]
354
+ if unknown:
355
+ errors.append("Unknown metabolite" + ("s" if len(unknown) > 1 else "") + ": " + ", ".join(unknown[:8])
356
+ + " — add it to the model first (search a database or create it)")
357
+ lo, hi = bound_in(r["lb"], "lower"), bound_in(r["ub"], "upper")
358
+ if lo > hi:
359
+ errors.append(f"Lower bound {lo:g} is greater than the upper bound {hi:g}")
360
+ elif lo == 0 and hi == 0:
361
+ warnings.append("Bounds 0 / 0: the reaction is blocked")
362
+ if r["lb"] is None or r["ub"] is None:
363
+ info.append("An empty bound means unbounded (±∞); most models use ±1000 instead")
364
+ g = gpr_error(r["gpr"])
365
+ if g:
366
+ errors.append(f"Gene rule: {g}")
367
+ kind = boundary_kind(r)
368
+ react = [m for m, c in r["metabolites"].items() if c < 0]
369
+ prod = [m for m, c in r["metabolites"].items() if c > 0]
370
+ if r["metabolites"] and (not react or not prod) and not kind:
371
+ warnings.append("Only " + ("products" if not react else "reactants") + ": the reaction creates or removes matter (boundary-like)")
372
+ mets = {m: v.get_met(m) or {} for m in r["metabolites"]}
373
+ comps = sorted({x.get("compartment") for x in mets.values() if x.get("compartment")})
374
+ if kind == "exchange" and comps and v.model.metabolites and comps[0] not in _external(v.model):
375
+ warnings.append(f"Exchange of a metabolite in “{comps[0]}”: exchange reactions are normally associated with extracellular metabolites")
376
+ bal = balance(r["metabolites"], mets) if not unknown else {"mass": None, "charge": None, "missingFormula": [], "missingCharge": []}
377
+ if not kind and not unknown:
378
+ if bal["mass"]:
379
+ warnings.append("Mass balance: unbalanced (" + ", ".join(f"{k} {'+' if x > 0 else ''}{x:g}" for k, x in bal["mass"].items()) + ")")
380
+ if bal["charge"] not in (None, 0):
381
+ warnings.append(f"Charge balance: imbalance of {bal['charge']:+g}")
382
+ dups = duplicate_reactions(v.model, r, before["id"] if before else None) if not unknown else []
383
+ for d in dups:
384
+ warnings.append(f"Potential duplicate reaction: {d['id']} ({d['reason']})")
385
+ return {"kind": kind, "balance": bal, "duplicates": dups, "compartments": comps}
386
+
387
+
388
+ def _external(model: cobra.Model) -> set[str]:
389
+ try:
390
+ from cobra.medium import find_external_compartment
391
+ return {find_external_compartment(model)}
392
+ except Exception: # noqa: BLE001
393
+ return {"e", "e0", "ext", "extracellular", "C_e"}
394
+
395
+
396
+ def _check_metabolite(v: View, before: Optional[dict], m: dict, errors: list, warnings: list, info: list) -> dict:
397
+ mid = m["id"]
398
+ if not mid:
399
+ errors.append("Metabolite ID is required")
400
+ elif re.search(r"\s", mid):
401
+ errors.append(f"Metabolite ID “{mid}” contains spaces")
402
+ elif (not before or before["id"] != mid) and v.get_met(mid) is not None:
403
+ errors.append(f"Metabolite ID “{mid}” is already used")
404
+ elif not SID.match(mid):
405
+ warnings.append(f"“{mid}” is not a valid SBML identifier; SBML export escapes the special characters")
406
+ if not m["name"]:
407
+ errors.append("Metabolite name is required")
408
+ if not m["compartment"]:
409
+ errors.append("Compartment is required")
410
+ elif not v.has_comp(m["compartment"]):
411
+ errors.append(f"Unknown compartment “{m['compartment']}” — create it explicitly first")
412
+ if m["formula"] and parse_formula(m["formula"]) is None:
413
+ warnings.append(f"Formula “{m['formula']}” could not be parsed (use element symbols and counts, e.g. C6H12O6)")
414
+ if not m["formula"] or m["charge"] is None:
415
+ warnings.append("Mass/charge balance cannot be fully evaluated without formula and charge")
416
+ if isinstance(m["charge"], float):
417
+ warnings.append(f"Charge {m['charge']:g} is not an integer")
418
+ if before and before["id"] != mid:
419
+ n = len(v.met_reactions(before["id"]))
420
+ if n:
421
+ info.append(f"Renaming: the {n} reaction{'s' if n > 1 else ''} using {before['id']} keep pointing to it under the new ID")
422
+ if before and before["compartment"] != m["compartment"]:
423
+ warnings.append(f"Moving {before['id']} from “{before['compartment']}” to “{m['compartment']}” changes the compartment in every reaction that uses it")
424
+ dups = duplicate_metabolites(v.model, m, before["id"] if before else None)
425
+ for d in dups:
426
+ if d["sameCompartment"]:
427
+ warnings.append(f"Possible existing metabolite detected: {d['id']} ({', '.join(d['reasons'])})")
428
+ return {"duplicates": dups}
429
+
430
+
431
+ # ----------------------------------------------------------------------------- building transactions
432
+
433
+ def build(entry: registry.ModelEntry, ops: list[dict]) -> tuple[list[dict], dict]:
434
+ """Request operations -> primitive operations + validation report (never modifies the model)."""
435
+ model = entry.model
436
+ v = View(model)
437
+ prims: list[dict] = []
438
+ report = {"errors": [], "warnings": [], "info": [], "items": []}
439
+
440
+ def item(i, label, errors, warnings, info, extra=None):
441
+ report["items"].append({"op": i, "label": label, "errors": errors, "warnings": warnings, "info": info, **(extra or {})})
442
+ report["errors"] += [f"{label}: {e}" for e in errors]
443
+ report["warnings"] += [f"{label}: {w}" for w in warnings]
444
+ report["info"] += [f"{label}: {x}" for x in info]
445
+
446
+ for i, op in enumerate(ops):
447
+ kind = op.get("op")
448
+ errors: list[str] = []
449
+ warnings: list[str] = []
450
+ info: list[str] = []
451
+ if kind == "add_compartment":
452
+ cid, name = str(op.get("id") or "").strip(), str(op.get("name") or "").strip()
453
+ if not cid or re.search(r"\s", cid):
454
+ errors.append("Compartment ID is required, without spaces")
455
+ elif v.has_comp(cid):
456
+ errors.append(f"Compartment “{cid}” already exists")
457
+ if not errors:
458
+ v.comp[cid] = name or cid
459
+ prims.append({"type": "compartment", "before": None, "after": {"id": cid, "name": name or cid}})
460
+ item(i, f"Compartment {cid}", errors, warnings, info)
461
+ elif kind == "put_metabolite":
462
+ orig = op.get("id")
463
+ before = v.get_met(orig) if orig else None
464
+ if orig and before is None:
465
+ errors.append(f"Metabolite {orig} does not exist")
466
+ m = norm_metabolite(op.get("metabolite") or {}, errors)
467
+ if before and "notes" not in (op.get("metabolite") or {}):
468
+ m["notes"] = before["notes"] # the UI catalog carries no notes: keep them
469
+ extra = _check_metabolite(v, before, m, errors, warnings, info) if not (orig and before is None) else {}
470
+ if not errors:
471
+ if before and before["id"] != m["id"]:
472
+ v.met[before["id"]] = None
473
+ v.met[m["id"]] = m
474
+ if before != m:
475
+ prims.append({"type": "metabolite", "before": before, "after": m})
476
+ item(i, f"Metabolite {m['id'] or '(new)'}", errors, warnings, info, extra)
477
+ elif kind == "put_reaction":
478
+ orig = op.get("id")
479
+ before = None
480
+ if orig:
481
+ if orig in v.rxn:
482
+ before = v.rxn[orig]
483
+ elif orig in model.reactions:
484
+ before = snap_reaction(model, model.reactions.get_by_id(orig))
485
+ if before is None:
486
+ errors.append(f"Reaction {orig} does not exist")
487
+ r = norm_reaction(op.get("reaction") or {}, errors)
488
+ if before and "notes" not in (op.get("reaction") or {}):
489
+ r["notes"] = before["notes"] # the UI catalog carries no notes: keep them
490
+ extra = _check_reaction(v, before, r, errors, warnings, info)
491
+ if not errors:
492
+ if before and before["id"] != r["id"]:
493
+ v.rxn[before["id"]] = None
494
+ v.rxn[r["id"]] = r
495
+ if before != r:
496
+ prims.append({"type": "reaction", "before": before, "after": r})
497
+ item(i, f"Reaction {r['id'] or '(new)'}", errors, warnings, info, extra)
498
+ elif kind == "delete_reaction":
499
+ rid = str(op.get("id") or "")
500
+ before = v.rxn.get(rid) if rid in v.rxn else (snap_reaction(model, model.reactions.get_by_id(rid)) if rid in model.reactions else None)
501
+ if before is None:
502
+ errors.append(f"Reaction {rid} does not exist")
503
+ else:
504
+ v.rxn[rid] = None
505
+ prims.append({"type": "reaction", "before": before, "after": None})
506
+ item(i, f"Delete reaction {rid}", errors, warnings, info)
507
+ elif kind == "delete_metabolite":
508
+ mid = str(op.get("id") or "")
509
+ before = v.get_met(mid)
510
+ if before is None:
511
+ errors.append(f"Metabolite {mid} does not exist")
512
+ else:
513
+ users = v.met_reactions(mid)
514
+ if users and not op.get("cascade"):
515
+ errors.append(f"This metabolite participates in {len(users)} reaction{'s' if len(users) > 1 else ''}: "
516
+ + ", ".join(users[:8]) + ("…" if len(users) > 8 else ""))
517
+ elif users:
518
+ for rid in users:
519
+ rb = v.rxn.get(rid) if rid in v.rxn else snap_reaction(model, model.reactions.get_by_id(rid))
520
+ v.rxn[rid] = None
521
+ prims.append({"type": "reaction", "before": rb, "after": None})
522
+ warnings.append(f"Also deletes {len(users)} reaction{'s' if len(users) > 1 else ''}: " + ", ".join(users[:8]))
523
+ if not errors:
524
+ v.met[mid] = None
525
+ prims.append({"type": "metabolite", "before": before, "after": None})
526
+ item(i, f"Delete metabolite {mid}", errors, warnings, info)
527
+ else:
528
+ item(i, f"Operation {i + 1}", [f"unknown operation “{kind}”"], [], [])
529
+ if not prims and not report["errors"]:
530
+ report["info"].append("No change")
531
+ return prims, report
532
+
533
+
534
+ # ----------------------------------------------------------------------------- applying primitives
535
+
536
+ def _met(model: cobra.Model, i: str) -> cobra.Metabolite:
537
+ return model.metabolites.get_by_id(i)
538
+
539
+
540
+ def _set_reaction(model: cobra.Model, r: cobra.Reaction, s: dict) -> None:
541
+ r.name = s["name"]
542
+ r.subsystem = s["subsystem"]
543
+ r.bounds = (bound_in(s["lb"], "lower"), bound_in(s["ub"], "upper"))
544
+ cur = {m.id: c for m, c in r.metabolites.items()}
545
+ if cur != s["metabolites"]:
546
+ r.add_metabolites({m: -c for m, c in r.metabolites.items()}) # combine=True: removes them
547
+ r.add_metabolites({_met(model, k): c for k, c in s["metabolites"].items()})
548
+ if (r.gene_reaction_rule or "") != s["gpr"]:
549
+ r.gene_reaction_rule = s["gpr"]
550
+ r.annotation = dict(s["annotation"])
551
+ r.notes = dict(s["notes"])
552
+ if abs(ms.objective_coefficients(model).get(r.id, 0.0) - s["objective"]) > 0:
553
+ r.objective_coefficient = s["objective"]
554
+
555
+
556
+ def _apply(entry: registry.ModelEntry, p: dict) -> None:
557
+ model = entry.model
558
+ t, b, a = p["type"], p["before"], p["after"]
559
+ if t == "compartment":
560
+ if a:
561
+ model.compartments = {a["id"]: a["name"]}
562
+ else:
563
+ getattr(model, "_compartments", {}).pop(b["id"], None)
564
+ elif t == "metabolite":
565
+ if b is None:
566
+ m = cobra.Metabolite(a["id"], formula=a["formula"] or None, name=a["name"], charge=a["charge"], compartment=a["compartment"])
567
+ m.annotation = dict(a["annotation"])
568
+ m.notes = dict(a["notes"])
569
+ model.add_metabolites([m])
570
+ elif a is None:
571
+ m = _met(model, b["id"])
572
+ if m.reactions:
573
+ raise ValueError(f"metabolite {b['id']} is still used by reactions")
574
+ model.remove_metabolites([m])
575
+ else:
576
+ m = _met(model, b["id"])
577
+ if b["id"] != a["id"]:
578
+ m.id = a["id"]
579
+ m.name, m.formula, m.charge, m.compartment = a["name"], a["formula"] or None, a["charge"], a["compartment"]
580
+ m.annotation = dict(a["annotation"])
581
+ m.notes = dict(a["notes"])
582
+ elif t == "reaction":
583
+ if b is None:
584
+ r = cobra.Reaction(a["id"])
585
+ model.add_reactions([r])
586
+ _set_reaction(model, r, a)
587
+ elif a is None:
588
+ r = model.reactions.get_by_id(b["id"])
589
+ genes = list(r.genes)
590
+ model.remove_reactions([r], remove_orphans=False)
591
+ _drop_new_orphan_genes(entry, genes)
592
+ else:
593
+ r = model.reactions.get_by_id(b["id"])
594
+ if b["id"] != a["id"]:
595
+ r.id = a["id"]
596
+ genes = list(r.genes)
597
+ _set_reaction(model, r, a)
598
+ _drop_new_orphan_genes(entry, genes)
599
+ else:
600
+ raise ValueError(f"unknown operation type {t}")
601
+
602
+
603
+ def _drop_new_orphan_genes(entry: registry.ModelEntry, genes: list) -> None:
604
+ """Genes created by an edit (not in the file) that no reaction uses any more."""
605
+ base = getattr(entry, "base_genes", None) or set()
606
+ for g in genes:
607
+ if not g.reactions and g.id not in base and g.id in entry.model.genes:
608
+ entry.model.genes.remove(g)
609
+
610
+
611
+ def inverse(prims: list[dict]) -> list[dict]:
612
+ return [{"type": p["type"], "before": p["after"], "after": p["before"]} for p in reversed(prims)]
613
+
614
+
615
+ def _run(entry: registry.ModelEntry, prims: list[dict]) -> None:
616
+ """Apply primitives; on failure revert the completed ones (or rebuild) and re-raise."""
617
+ done: list[dict] = []
618
+ try:
619
+ for p in prims:
620
+ _apply(entry, p)
621
+ done.append(p)
622
+ except Exception as e:
623
+ try:
624
+ for p in inverse(done):
625
+ _apply(entry, p)
626
+ except Exception: # noqa: BLE001 - last resort: file + log
627
+ rebuild(entry)
628
+ raise ScienceError("The edit could not be applied", f"{type(e).__name__}: {e}. The model was left unchanged.", status=422) from e
629
+
630
+
631
+ # ----------------------------------------------------------------------------- log, persistence, refresh
632
+
633
+ def _empty_log() -> dict:
634
+ return {"version": 1, "applied": [], "undone": [], "exported": ""}
635
+
636
+
637
+ def log_of(entry: registry.ModelEntry) -> dict:
638
+ if getattr(entry, "edits", None) is None:
639
+ entry.edits = _empty_log()
640
+ return entry.edits
641
+
642
+
643
+ def _save(entry: registry.ModelEntry) -> None:
644
+ from .annotation_service import save_json
645
+ save_json(entry.id, "edits", log_of(entry))
646
+
647
+
648
+ def log_hash(log: dict) -> str:
649
+ if not log["applied"]:
650
+ return ""
651
+ return hashlib.sha256(json.dumps([t["ops"] for t in log["applied"]], sort_keys=True).encode()).hexdigest()[:12]
652
+
653
+
654
+ def refresh(entry: registry.ModelEntry) -> dict:
655
+ """After a structural change: new 'model file' baseline, catalog and search index. Returns the old catalog."""
656
+ old = entry.catalog
657
+ ms.set_baseline(entry)
658
+ entry.search = None # rebuilt on the next backend search
659
+ entry.catalog = ms.build_catalog(entry)
660
+ return old
661
+
662
+
663
+ def delta(old: Optional[dict], new: dict) -> dict:
664
+ out: dict[str, Any] = {}
665
+ for key in ("reactions", "metabolites", "genes"):
666
+ a = {x["id"]: x for x in (old or {}).get(key, [])}
667
+ b = {x["id"]: x for x in new[key]}
668
+ out[key] = {"upsert": [x for i, x in b.items() if a.get(i) != x], "remove": [i for i in a if i not in b]}
669
+ for key in ("summary", "compartments", "warnings", "medium"):
670
+ out[key] = new[key]
671
+ return out
672
+
673
+
674
+ def _describe(p: dict) -> list[str]:
675
+ t, b, a = p["type"], p["before"], p["after"]
676
+ if t == "compartment":
677
+ return [f"Added compartment {a['id']} ({a['name']})" if a else f"Removed compartment {b['id']}"]
678
+ if a is None:
679
+ return [f"Removed {t} {b['id']}"]
680
+ if b is None:
681
+ if t == "reaction":
682
+ return [f"Added reaction {a['id']}: {_eq(a)}"]
683
+ return [f"Added metabolite {a['id']} ({a['name']}, {a['compartment']})"]
684
+ out = []
685
+ if b["id"] != a["id"]:
686
+ out.append(f"Renamed {t} {b['id']} → {a['id']}")
687
+ rid = a["id"]
688
+ if t == "reaction":
689
+ fb = lambda x, s: "−∞" if x is None and s == "l" else "∞" if x is None else f"{x:g}" # noqa: E731
690
+ if b["lb"] != a["lb"]:
691
+ out.append(f"Changed {rid} lower bound: {fb(b['lb'], 'l')} → {fb(a['lb'], 'l')}")
692
+ if b["ub"] != a["ub"]:
693
+ out.append(f"Changed {rid} upper bound: {fb(b['ub'], 'u')} → {fb(a['ub'], 'u')}")
694
+ if b["metabolites"] != a["metabolites"]:
695
+ out.append(f"Changed {rid} equation: {_eq(b)} ⟶ {_eq(a)}")
696
+ for k, lbl in (("name", "name"), ("subsystem", "subsystem"), ("gpr", "gene rule")):
697
+ if b[k] != a[k]:
698
+ out.append(f"Changed {rid} {lbl}: “{b[k]}” → “{a[k]}”")
699
+ if b["objective"] != a["objective"]:
700
+ out.append(f"Changed {rid} objective coefficient: {b['objective']:g} → {a['objective']:g}")
701
+ else:
702
+ for k in ("name", "compartment", "formula", "charge"):
703
+ if b[k] != a[k]:
704
+ out.append(f"Changed {rid} {k}: “{b[k] if b[k] is not None else ''}” → “{a[k] if a[k] is not None else ''}”")
705
+ if b["annotation"] != a["annotation"]:
706
+ out.append(f"Changed {rid} annotations")
707
+ if b["notes"] != a["notes"]:
708
+ out.append(f"Changed {rid} notes")
709
+ return out or [f"Updated {t} {rid}"]
710
+
711
+
712
+ def _eq(r: dict) -> str:
713
+ def side(sign):
714
+ parts = [(f"{abs(c):g} " if abs(c) != 1 else "") + m for m, c in r["metabolites"].items() if (c > 0) == (sign > 0)]
715
+ return " + ".join(parts)
716
+ lo, hi = bound_in(r["lb"], "lower"), bound_in(r["ub"], "upper")
717
+ arrow = "<=>" if lo < 0 < hi else "<--" if hi <= 0 and lo < 0 else "-->"
718
+ return f"{side(-1)} {arrow} {side(1)}".strip()
719
+
720
+
721
+ def history(entry: registry.ModelEntry) -> dict:
722
+ log = log_of(entry)
723
+ h = log_hash(log)
724
+ return {
725
+ "count": len(log["applied"]), "hash": h, "dirty": h != log.get("exported", ""),
726
+ "items": [{"id": t["id"], "time": t["time"], "label": t["label"], "details": t.get("details", [])} for t in log["applied"]],
727
+ "redo": [{"id": t["id"], "time": t["time"], "label": t["label"]} for t in reversed(log["undone"])],
728
+ "loadErrors": getattr(entry, "edit_errors", []),
729
+ }
730
+
731
+
732
+ def _label(prims: list[dict], given: Optional[str]) -> str:
733
+ if given:
734
+ return given
735
+ lines = [d for p in prims for d in _describe(p)]
736
+ return lines[0] if len(lines) == 1 else f"{lines[0]} (+{len(lines) - 1} more)"
737
+
738
+
739
+ def _renames(prims: list[dict]) -> dict:
740
+ out: dict[str, dict[str, Optional[str]]] = {"reactions": {}, "metabolites": {}}
741
+ for p in prims:
742
+ key = "reactions" if p["type"] == "reaction" else "metabolites" if p["type"] == "metabolite" else None
743
+ if not key:
744
+ continue
745
+ if p["before"] and (p["after"] is None or p["after"]["id"] != p["before"]["id"]):
746
+ out[key][p["before"]["id"]] = p["after"]["id"] if p["after"] else None
747
+ return out
748
+
749
+
750
+ def _response(entry, old, prims) -> dict:
751
+ return {"delta": delta(old, entry.catalog), "history": history(entry), "renamed": _renames(prims)}
752
+
753
+
754
+ # ----------------------------------------------------------------------------- public operations (cobra thread)
755
+
756
+ def check(entry: registry.ModelEntry, ops: list[dict]) -> dict:
757
+ with entry.lock:
758
+ prims, report = build(entry, ops)
759
+ report["changes"] = [d for p in prims for d in _describe(p)]
760
+ return report
761
+
762
+
763
+ def commit(entry: registry.ModelEntry, ops: list[dict], label: Optional[str] = None) -> dict:
764
+ with entry.lock:
765
+ prims, report = build(entry, ops)
766
+ if report["errors"]:
767
+ raise ScienceError("The edit is not valid", "; ".join(report["errors"][:4]), status=422,
768
+ hints=["Nothing was changed."], detail=report)
769
+ if not prims:
770
+ return {**_response(entry, entry.catalog, []), "report": report}
771
+ _run(entry, prims)
772
+ log = log_of(entry)
773
+ log["applied"].append({"id": uuid.uuid4().hex[:10], "time": time.time(), "label": _label(prims, label),
774
+ "details": [d for p in prims for d in _describe(p)], "ops": prims})
775
+ log["undone"] = []
776
+ _save(entry)
777
+ old = refresh(entry)
778
+ return {**_response(entry, old, prims), "report": report}
779
+
780
+
781
+ def undo(entry: registry.ModelEntry) -> dict:
782
+ with entry.lock:
783
+ log = log_of(entry)
784
+ if not log["applied"]:
785
+ raise ScienceError("Nothing to undo", status=409)
786
+ t = log["applied"][-1]
787
+ prims = inverse(t["ops"])
788
+ _run(entry, prims)
789
+ log["undone"].append(log["applied"].pop())
790
+ _save(entry)
791
+ old = refresh(entry)
792
+ return _response(entry, old, prims)
793
+
794
+
795
+ def redo(entry: registry.ModelEntry) -> dict:
796
+ with entry.lock:
797
+ log = log_of(entry)
798
+ if not log["undone"]:
799
+ raise ScienceError("Nothing to redo", status=409)
800
+ t = log["undone"][-1]
801
+ _run(entry, t["ops"])
802
+ log["applied"].append(log["undone"].pop())
803
+ _save(entry)
804
+ old = refresh(entry)
805
+ return _response(entry, old, t["ops"])
806
+
807
+
808
+ def discard(entry: registry.ModelEntry) -> dict:
809
+ """Revert every edit: the model is the imported file again (plus the metabolite curation)."""
810
+ with entry.lock:
811
+ log = log_of(entry)
812
+ prims = [p for t in reversed(log["applied"]) for p in inverse(t["ops"])]
813
+ if prims:
814
+ _run(entry, prims)
815
+ entry.edits = _empty_log()
816
+ _save(entry)
817
+ old = refresh(entry)
818
+ return _response(entry, old, prims)
819
+
820
+
821
+ def mark_exported(entry: registry.ModelEntry) -> None:
822
+ log = log_of(entry)
823
+ log["exported"] = log_hash(log)
824
+ _save(entry)
825
+
826
+
827
+ def replay(entry: registry.ModelEntry) -> None:
828
+ """Re-apply the saved log on a freshly loaded model (called by model_service before the catalog)."""
829
+ from .annotation_service import load_json
830
+ entry.base_genes = {g.id for g in entry.model.genes}
831
+ saved = load_json(entry.id, "edits")
832
+ entry.edits = saved if saved and isinstance(saved.get("applied"), list) else _empty_log()
833
+ entry.edit_errors = []
834
+ ok = []
835
+ for t in entry.edits["applied"]:
836
+ try:
837
+ for p in t["ops"]:
838
+ _apply(entry, p)
839
+ ok.append(t)
840
+ except Exception as e: # noqa: BLE001 - reported, the remaining edits are skipped
841
+ entry.edit_errors.append(f"“{t.get('label')}” could not be re-applied: {e}")
842
+ break
843
+ if len(ok) != len(entry.edits["applied"]):
844
+ entry.edits["applied"] = ok
845
+ entry.edits["undone"] = []
846
+
847
+
848
+ def rebuild(entry: registry.ModelEntry) -> None:
849
+ """Reload the imported file (+ curation) and replay the saved log — used only if an inverse fails."""
850
+ entry.model = ms.load_base_model(entry.id, entry.filename, entry.fmt)
851
+ replay(entry)
852
+
853
+
854
+ def patch(entry: registry.ModelEntry) -> dict:
855
+ """Model patch: the transactions plus the net effect per entity (first state before → last state after)."""
856
+ log = log_of(entry)
857
+ first: dict[tuple[str, str], Optional[dict]] = {}
858
+ last: dict[tuple[str, str], Optional[dict]] = {}
859
+ for t in log["applied"]:
860
+ for p in t["ops"]:
861
+ if p["type"] == "compartment":
862
+ continue
863
+ key_b = (p["type"], p["before"]["id"]) if p["before"] else None
864
+ key_a = (p["type"], p["after"]["id"]) if p["after"] else None
865
+ if key_b and key_b not in first:
866
+ first[key_b] = p["before"]
867
+ if key_a and key_a not in first:
868
+ first[key_a] = None
869
+ if key_b:
870
+ last[key_b] = None if not key_a or key_a != key_b else p["after"]
871
+ if key_a:
872
+ last[key_a] = p["after"]
873
+ net: dict[str, list] = {f"{k}{s}": [] for k in ("reactions", "metabolites") for s in ("Added", "Removed", "Changed")}
874
+ for key, a in last.items():
875
+ b = first.get(key)
876
+ kind = "reactions" if key[0] == "reaction" else "metabolites"
877
+ if b is None and a is not None:
878
+ net[f"{kind}Added"].append(a)
879
+ elif b is not None and a is None:
880
+ net[f"{kind}Removed"].append(b["id"])
881
+ elif b is not None and a is not None and a != b:
882
+ net[f"{kind}Changed"].append({"before": b, "after": a})
883
+ return {
884
+ "format": "cobragui-model-patch", "version": 1,
885
+ "model": {"filename": entry.filename, "checksum": entry.checksum, "modelId": entry.model.id or ""},
886
+ "created": time.strftime("%Y-%m-%dT%H:%M:%S"), "hash": log_hash(log),
887
+ "summary": {k: len(v) for k, v in net.items()}, "net": net,
888
+ "transactions": log["applied"],
889
+ }
890
+
891
+
892
+ # ----------------------------------------------------------------------------- full validation
893
+
894
+ def validate(entry: registry.ModelEntry) -> dict:
895
+ """Model-wide checks (on demand, not after every click)."""
896
+ m = entry.model
897
+ kinds = ms.boundary_kinds(m)
898
+ comps = known_compartments(m)
899
+ out: list[dict] = []
900
+
901
+ def add(level, code, title, ids, detail=""):
902
+ if ids:
903
+ out.append({"level": level, "code": code, "title": title, "count": len(ids), "ids": ids[:5000], "detail": detail})
904
+
905
+ rid_seen, dup_r = set(), []
906
+ for r in m.reactions:
907
+ if r.id in rid_seen:
908
+ dup_r.append(r.id)
909
+ rid_seen.add(r.id)
910
+ add("error", "duplicate-reaction-id", "duplicate reaction IDs", dup_r)
911
+ mid_seen, dup_m = set(), []
912
+ for x in m.metabolites:
913
+ if x.id in mid_seen:
914
+ dup_m.append(x.id)
915
+ mid_seen.add(x.id)
916
+ add("error", "duplicate-metabolite-id", "duplicate metabolite IDs", dup_m)
917
+ add("error", "empty-reaction", "reactions without metabolites", [r.id for r in m.reactions if not r.metabolites])
918
+ add("error", "invalid-bounds", "reactions with lower bound > upper bound", [r.id for r in m.reactions if r.lower_bound > r.upper_bound])
919
+ add("error", "invalid-gpr", "reactions with an invalid gene rule", [r.id for r in m.reactions if r.gene_reaction_rule and gpr_error(r.gene_reaction_rule)])
920
+ add("error", "unknown-compartment", "metabolites without a compartment", [x.id for x in m.metabolites if not x.compartment])
921
+ add("warning", "orphan-metabolite", "metabolites not used by any reaction (orphans)", [x.id for x in m.metabolites if not x.reactions])
922
+ add("info", "unnamed-compartment", "compartments without a name", [c for c, n in comps.items() if not n or n == c])
923
+ add("info", "no-formula", "metabolites without a formula", [x.id for x in m.metabolites if not x.formula])
924
+ add("info", "no-charge", "metabolites without a charge", [x.id for x in m.metabolites if not isinstance(x.charge, (int, float))])
925
+ mass, charge, skipped = [], [], 0
926
+ for r in m.reactions:
927
+ if r.id in kinds or r.id in entry.original_objective:
928
+ continue
929
+ info = {x.id: {"formula": x.formula, "charge": x.charge if isinstance(x.charge, (int, float)) else None} for x in r.metabolites}
930
+ bal = balance({x.id: float(c) for x, c in r.metabolites.items()}, info)
931
+ if bal["mass"] is None:
932
+ skipped += 1
933
+ elif bal["mass"]:
934
+ mass.append(r.id)
935
+ if bal["charge"] not in (None, 0):
936
+ charge.append(r.id)
937
+ add("warning", "mass-unbalanced", "reactions are elementally unbalanced", mass,
938
+ f"Boundary and objective (biomass) reactions are excluded; {skipped} reactions with metabolites lacking a formula were not evaluated.")
939
+ add("warning", "charge-unbalanced", "reactions are charge-unbalanced", charge, "Only reactions whose metabolites all have a charge are evaluated.")
940
+ log = log_of(entry)
941
+ return {"issues": out, "edits": len(log["applied"]), "reactions": len(m.reactions), "metabolites": len(m.metabolites),
942
+ "checkedAt": time.time()}