equilibrator-pathway-core 0.1.0__py3-none-any.whl

equilibrator_pathway_core/__init__.py

@@ -0,0 +1,41 @@
+"""Max-min driving force and enzyme cost minimization, without a compound database.
+
+This is the database-free lower layer of equilibrator-pathway. It analyses
+*fully specified* pathway models -- SBtab files that already carry the
+stoichiometry, bounds, fluxes and standard Gibbs energies -- and never predicts
+or looks anything up. It is shared by equilibrator-pathway (which adds identifier
+resolution, dG'0 prediction and a pint-based API on top) and by the in-browser
+pathway client.
+
+Everything here works on plain floats in the canonical units documented in
+:mod:`equilibrator_pathway_core.constants`.
+"""
+
+from __future__ import annotations
+
+from .constants import (
+    DEFAULT_RT,
+    DEFAULT_T,
+    PHYSIOLOGICAL_CONCENTRATION,
+    STANDARD_CONCENTRATION,
+    R,
+)
+from .ecm import ECF_DEFAULTS, EnzymeCostFunction
+from .errors import ModelError, SolverFailure
+from .mdf import MdfResult, mdf_analysis
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_RT",
+    "DEFAULT_T",
+    "ECF_DEFAULTS",
+    "PHYSIOLOGICAL_CONCENTRATION",
+    "STANDARD_CONCENTRATION",
+    "EnzymeCostFunction",
+    "MdfResult",
+    "ModelError",
+    "R",
+    "SolverFailure",
+    "mdf_analysis",
+]

equilibrator_pathway_core/configuration.py

@@ -0,0 +1,293 @@
+"""The editable Configuration table: its schema, and applying edits to it.
+
+The web form that lets the user tweak a model's `Configuration` table is built
+from the schema here rather than from a hand-written list in the JavaScript, so
+that the offered choices cannot drift away from what the optimization actually
+accepts (`ECF_DEFAULTS` and the branches of `EnzymeCostFunction`).
+
+Three kinds of options:
+
+* `select`  -- a fixed set of choices (`algorithm`, `denominator`, ...)
+* `number`  -- a numeric parameter (`stdev_factor`, `ln_conc_confidence`, ...)
+* `display` -- shown but not editable: the aqueous conditions, because the ΔG'°
+  values stored in the model were already transformed for exactly those
+  conditions. Changing the pH here would not re-transform them -- that needs
+  Component Contribution, i.e. the compound database this app deliberately does
+  without.
+
+Moved here from the browser client (``pathway_client/configuration.py``), step 4
+of CORE_EXTRACTION_PLAN.txt: the schema is a capability the library lacked, and
+keeping it next to the code that consumes the options is what stops the two
+drifting apart. The notes are user-facing text, written for the browser's form.
+"""
+
+from sbtab.SBtab import SBtabDocument, SBtabTable
+
+from .errors import ConfigurationError
+from .model import read_sbtab
+
+__all__ = [
+    "DISPLAY",
+    "NUMBER",
+    "OPTION_SCHEMA",
+    "SELECT",
+    "ConfigurationError",
+    "apply_overrides",
+    "describe_configuration",
+]
+
+SELECT = "select"
+NUMBER = "number"
+DISPLAY = "display"
+
+# Applies to: which algorithm an option has an effect on ("MDF", "ECM" or
+# "both"), so the form can say so.
+OPTION_SCHEMA = {
+    "algorithm": {
+        "kind": SELECT,
+        "choices": ["MDF", "ECM"],
+        "label": "Algorithm",
+        "applies_to": "both",
+        "note": "Which optimization to run. An ECM model also needs a "
+        "'Parameter' table with kcat, KM and molecular masses.",
+    },
+    "version": {
+        "kind": SELECT,
+        "choices": ["1", "2", "3", "4"],
+        "label": "Enzyme cost function level",
+        "applies_to": "ECM",
+        "note": "1 = capacity only, 2 = + thermodynamics, 3 = + saturation, "
+        "4 = + allosteric regulation.",
+    },
+    "kcat_source": {
+        "kind": SELECT,
+        "choices": ["gmean", "fwd"],
+        "label": "kcat source",
+        "applies_to": "ECM",
+        "note": "'gmean' distributes the geometric-mean kcat over both "
+        "directions using the Haldane relationship; 'fwd' takes kcat in the "
+        "direction of the flux as given.",
+    },
+    "denominator": {
+        "kind": SELECT,
+        "choices": ["S", "1S", "SP", "1SP", "CM"],
+        "label": "Rate law denominator",
+        "applies_to": "ECM",
+        "note": "The saturation term of the rate law; 'CM' is the common "
+        "modular rate law.",
+    },
+    "regularization": {
+        "kind": SELECT,
+        "choices": ["volume"],
+        "label": "Regularization",
+        "applies_to": "ECM",
+        "note": "Only 'volume' is implemented: support for the other options "
+        "was dropped when equilibrator-pathway moved to CVXPY.",
+    },
+    "objective": {
+        "kind": SELECT,
+        "choices": ["enzyme", "enzyme + metabolite"],
+        "label": "Objective",
+        "applies_to": "ECM",
+        "note": "Minimize the enzyme weight alone, or the enzyme plus "
+        "metabolite weight.",
+    },
+    "ln_conc_confidence": {
+        "kind": NUMBER,
+        "label": "Log-concentration confidence",
+        "applies_to": "both",
+        "minimum": 0.0,
+        "maximum": 0.999999,
+        "note": "The confidence level of the concentration bounds (default "
+        "0.95). Lowering it narrows the allowed concentration range.",
+    },
+    "dg_confidence": {
+        "kind": NUMBER,
+        "label": "ΔG'° confidence",
+        "applies_to": "MDF",
+        "minimum": 0.0,
+        "maximum": 0.999999,
+        "note": "Has no effect on an uploaded model: it widens the ΔG'° "
+        "bounds using the uncertainty covariance, which a model SBtab does "
+        "not store (dg_sigma is None).",
+    },
+    "stdev_factor": {
+        "kind": NUMBER,
+        "label": "Standard deviation factor",
+        "applies_to": "both",
+        "note": "Currently unused by the optimization -- in "
+        "equilibrator-pathway it is still a TODO in ecm_model.py, so changing "
+        "it will not change the results.",
+    },
+    "solver": {
+        "kind": DISPLAY,
+        "label": "Solver",
+        "applies_to": "both",
+        "note": "CLARABEL is the only solver available in the browser (it is "
+        "also eQuilibrator's default).",
+    },
+    "p_h": {
+        "kind": DISPLAY,
+        "label": "pH",
+        "applies_to": "both",
+        "note": "The ΔG'° values in this model were transformed for these "
+        "conditions; re-transforming them needs the compound database.",
+    },
+    "p_mg": {"kind": DISPLAY, "label": "pMg", "applies_to": "both"},
+    "ionic_strength": {
+        "kind": DISPLAY,
+        "label": "Ionic strength",
+        "applies_to": "both",
+    },
+    "temperature": {"kind": DISPLAY, "label": "Temperature", "applies_to": "both"},
+    "e_potential": {
+        "kind": DISPLAY,
+        "label": "Electrostatic potential",
+        "applies_to": "both",
+    },
+}
+
+
+def _configuration_table(document: SBtabDocument) -> SBtabTable:
+    table = document.get_sbtab_by_id("Configuration")
+    if table is None:
+        raise ConfigurationError("Missing 'Configuration' table")
+    if "Option" not in table.column_names or "Value" not in table.column_names:
+        raise ConfigurationError(
+            "The Configuration table must have an Option and a Value column"
+        )
+    return table
+
+
+def describe_configuration(text: str, filename: str = "pathway.tsv") -> dict:
+    """Describe the Configuration table of a model, for the edit form.
+
+    Returns the options in the order they appear in the file, each with its
+    current value and how it may be edited. Options that are not in the schema
+    are reported as `display`, so an unknown option is shown but never silently
+    changed.
+    """
+    document = read_sbtab(text, filename)
+    table = _configuration_table(document)
+
+    options = []
+    for row in table.to_dict_rows():
+        name = row.get("Option", "").strip()
+        if not name:
+            continue
+        value = row.get("Value", "").strip()
+        schema = OPTION_SCHEMA.get(name, {})
+        option = {
+            "name": name,
+            "value": value,
+            "kind": schema.get("kind", DISPLAY),
+            "label": schema.get("label", name),
+            "applies_to": schema.get("applies_to", "both"),
+            "note": schema.get("note"),
+            "comment": (row.get("Comment") or "").strip(),
+        }
+        if option["kind"] == SELECT:
+            choices = list(schema["choices"])
+            # keep whatever the file says as a choice, even when it is not one
+            # we know about, so that opening the form cannot alter the model
+            if not any(choice.lower() == value.lower() for choice in choices):
+                if value:
+                    choices.append(value)
+            else:
+                # normalize to the schema's spelling of the current value
+                option["value"] = next(
+                    choice for choice in choices if choice.lower() == value.lower()
+                )
+            option["choices"] = choices
+        elif option["kind"] == NUMBER:
+            for key in ("minimum", "maximum"):
+                if key in schema:
+                    option[key] = schema[key]
+        options.append(option)
+
+    return {
+        "filename": filename,
+        "options": options,
+        "algorithm": next(
+            (
+                option["value"].upper()
+                for option in options
+                if option["name"] == "algorithm"
+            ),
+            None,
+        ),
+    }
+
+
+def apply_overrides(
+    document: SBtabDocument, overrides: dict[str, str] | None
+) -> list[str]:
+    """Apply edited Configuration values to a document, in place.
+
+    Returns a list of human-readable descriptions of what changed, for the
+    result page. Raises `ConfigurationError` if an override names an option
+    that is absent or not editable, or gives a value the code would not accept.
+    """
+    if not overrides:
+        return []
+
+    table = _configuration_table(document)
+    # the rows are copies, so edits go back through `change_value`, by position
+    # (1-based): the Option column need not come first, which rules out
+    # `change_value_by_name`
+    value_column = table.column_names.index("Value") + 1
+    rows_by_name = {}
+    for position, row in enumerate(table.to_dict_rows(), start=1):
+        name = row.get("Option", "").strip()
+        if name:
+            rows_by_name.setdefault(name, (position, row))
+
+    changes = []
+    for name, new_value in overrides.items():
+        if name not in rows_by_name:
+            raise ConfigurationError(
+                f"The Configuration table of this model has no option '{name}'"
+            )
+
+        position, row = rows_by_name[name]
+        schema = OPTION_SCHEMA.get(name, {})
+        kind = schema.get("kind", DISPLAY)
+        new_value = str(new_value).strip()
+
+        if kind == DISPLAY:
+            raise ConfigurationError(f"The option '{name}' cannot be edited")
+        if kind == SELECT:
+            choices = schema["choices"]
+            match = next(
+                (choice for choice in choices if choice.lower() == new_value.lower()),
+                None,
+            )
+            if match is None:
+                raise ConfigurationError(
+                    f"'{new_value}' is not a valid value for '{name}' "
+                    f"(choose one of: {', '.join(choices)})"
+                )
+            new_value = match
+        elif kind == NUMBER:
+            try:
+                number = float(new_value)
+            except ValueError:
+                raise ConfigurationError(
+                    f"The option '{name}' must be a number, not '{new_value}'"
+                )
+            minimum, maximum = schema.get("minimum"), schema.get("maximum")
+            if minimum is not None and number < minimum:
+                raise ConfigurationError(
+                    f"The option '{name}' must be at least {minimum}"
+                )
+            if maximum is not None and number > maximum:
+                raise ConfigurationError(
+                    f"The option '{name}' must be at most {maximum}"
+                )
+
+        old_value = row.get("Value", "").strip()
+        if old_value != new_value:
+            table.change_value(position, value_column, new_value)
+            changes.append(f"{name}: '{old_value}' → '{new_value}'")
+
+    return changes

equilibrator_pathway_core/constants.py

@@ -0,0 +1,52 @@
+"""Physical constants, as plain floats in the core's canonical units.
+
+The core does all its arithmetic on unitless numbers in one fixed set of units:
+
+    concentration   M
+    energy          kJ/mol
+    temperature     K
+    rate constant   1/s
+    molecular mass  Da
+
+Units are attached, if at all, at the boundary: equilibrator-pathway wraps these
+in pint quantities for its public API, and the browser client parses unit
+strings straight into these units. Nothing in here may import pint.
+
+These are *defined* here rather than imported from
+``equilibrator_cache.thermodynamic_constants``. Importing that module executes
+``equilibrator_cache/__init__.py``, which pulls in sqlalchemy, pandas, pooch and
+rapidfuzz -- the dependency chain this package exists to avoid. The values are
+held equal to equilibrator-cache's by ``tests/test_constants.py``.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "DEFAULT_RT",
+    "DEFAULT_T",
+    "PHYSIOLOGICAL_CONCENTRATION",
+    "STANDARD_CONCENTRATION",
+    "R",
+]
+
+#: Gas constant, kJ/(mol*K).
+#:
+#: Note: 8.31e-3, *not* CODATA's 8.314462618e-3. This is the value
+#: equilibrator-cache has always used, and every published eQuilibrator number
+#: -- and every golden result this package is tested against -- was computed
+#: with it. "Correcting" it would move every driving force by ~0.05%, which the
+#: golden tests would (rightly) report as a regression. Change it, if ever, in
+#: equilibrator-cache first and here second.
+R: float = 8.31e-3
+
+#: Default temperature, K.
+DEFAULT_T: float = 298.15
+
+#: R * DEFAULT_T, kJ/mol.
+DEFAULT_RT: float = R * DEFAULT_T
+
+#: Standard-state concentration for a solute, M.
+STANDARD_CONCENTRATION: float = 1.0
+
+#: Reference concentration for "physiological" (1 mM) Gibbs energies, M.
+PHYSIOLOGICAL_CONCENTRATION: float = 1.0e-3