mxlpy 0.8.0__py3-none-any.whl

mxlpy/experimental/diff.py

@@ -0,0 +1,226 @@
+"""Diffing utilities for comparing models."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+from mxlpy.model import Model
+from mxlpy.types import Derived
+
+__all__ = ["DerivedDiff", "ModelDiff", "ReactionDiff", "model_diff", "soft_eq"]
+
+
+@dataclass
+class DerivedDiff:
+    """Difference between two derived variables."""
+
+    args1: list[str] = field(default_factory=list)
+    args2: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ReactionDiff:
+    """Difference between two reactions."""
+
+    args1: list[str] = field(default_factory=list)
+    args2: list[str] = field(default_factory=list)
+    stoichiometry1: dict[str, float | Derived] = field(default_factory=dict)
+    stoichiometry2: dict[str, float | Derived] = field(default_factory=dict)
+
+
+@dataclass
+class ModelDiff:
+    """Difference between two models."""
+
+    missing_parameters: set[str] = field(default_factory=set)
+    missing_variables: set[str] = field(default_factory=set)
+    missing_reactions: set[str] = field(default_factory=set)
+    missing_surrogates: set[str] = field(default_factory=set)
+    missing_readouts: set[str] = field(default_factory=set)
+    missing_derived: set[str] = field(default_factory=set)
+    different_parameters: dict[str, tuple[float, float]] = field(default_factory=dict)
+    different_variables: dict[str, tuple[float, float]] = field(default_factory=dict)
+    different_reactions: dict[str, ReactionDiff] = field(default_factory=dict)
+    different_surrogates: dict[str, ReactionDiff] = field(default_factory=dict)
+    different_readouts: dict[str, DerivedDiff] = field(default_factory=dict)
+    different_derived: dict[str, DerivedDiff] = field(default_factory=dict)
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation of the diff."""
+        content = ["Model Diff", "----------"]
+
+        # Parameters
+        if self.missing_parameters:
+            content.append(
+                "Missing Parameters: {}".format(", ".join(self.missing_parameters))
+            )
+        if self.different_parameters:
+            content.append("Different Parameters:")
+            for k, (v1, v2) in self.different_parameters.items():
+                content.append(f"  {k}: {v1} != {v2}")
+
+        # Variables
+        if self.missing_variables:
+            content.append(
+                "Missing Variables: {}".format(", ".join(self.missing_variables))
+            )
+        if self.different_variables:
+            content.append("Different Variables:")
+            for k, (v1, v2) in self.different_variables.items():
+                content.append(f"  {k}: {v1} != {v2}")
+
+        # Derived
+        if self.missing_derived:
+            content.append(
+                "Missing Derived: {}".format(", ".join(self.missing_derived))
+            )
+        if self.different_derived:
+            content.append("Different Derived:")
+            for k, diff in self.different_derived.items():
+                content.append(f"  {k}:")
+                if diff.args1 != diff.args2:
+                    content.append(f"    Args: {diff.args1} != {diff.args2}")
+
+        # Reactions
+        if self.missing_reactions:
+            content.append(
+                "Missing Reactions: {}".format(", ".join(self.missing_reactions))
+            )
+        if self.different_reactions:
+            content.append("Different Reactions:")
+            for k, diff in self.different_reactions.items():
+                content.append(f"  {k}:")
+                if diff.args1 != diff.args2:
+                    content.append(f"    Args: {diff.args1} != {diff.args2}")
+                if diff.stoichiometry1 != diff.stoichiometry2:
+                    content.append(
+                        f"    Stoichiometry: {diff.stoichiometry1} != {diff.stoichiometry2}"
+                    )
+
+        # Surrogates
+        if self.missing_surrogates:
+            content.append(
+                "Missing Surrogates: {}".format(", ".join(self.missing_surrogates))
+            )
+        if self.different_surrogates:
+            content.append("Different Surrogates:")
+            for k, diff in self.different_surrogates.items():
+                content.append(f"  {k}:")
+                if diff.args1 != diff.args2:
+                    content.append(f"    Args: {diff.args1} != {diff.args2}")
+                if diff.stoichiometry1 != diff.stoichiometry2:
+                    content.append(
+                        f"    Stoichiometry: {diff.stoichiometry1} != {diff.stoichiometry2}"
+                    )
+        return "\n".join(content)
+
+
+def _soft_eq_stoichiometries(
+    s1: Mapping[str, float | Derived], s2: Mapping[str, float | Derived]
+) -> bool:
+    """Check if two stoichiometries are equal, ignoring the functions."""
+    if s1.keys() != s2.keys():
+        return False
+
+    for k, v1 in s1.items():
+        v2 = s2[k]
+        if isinstance(v1, Derived):
+            if not isinstance(v2, Derived):
+                return False
+            if v1.args != v2.args:
+                return False
+        elif v1 != v2:
+            return False
+
+    return True
+
+
+def soft_eq(m1: Model, m2: Model) -> bool:
+    """Check if two models are equal, ignoring the functions."""
+    if m1._parameters != m2._parameters:  # noqa: SLF001
+        return False
+    if m1._variables != m2._variables:  # noqa: SLF001
+        return False
+    for k, d1 in m1._derived.items():  # noqa: SLF001
+        if (d2 := m2._derived.get(k)) is None:  # noqa: SLF001
+            return False
+        if d1.args != d2.args:
+            return False
+    for k, r1 in m1._readouts.items():  # noqa: SLF001
+        if (r2 := m2._readouts.get(k)) is None:  # noqa: SLF001
+            return False
+        if r1.args != r2.args:
+            return False
+    for k, v1 in m1._reactions.items():  # noqa: SLF001
+        if (v2 := m2._reactions.get(k)) is None:  # noqa: SLF001
+            return False
+        if v1.args != v2.args:
+            return False
+        if not _soft_eq_stoichiometries(v1.stoichiometry, v2.stoichiometry):
+            return False
+    for k, s1 in m1._surrogates.items():  # noqa: SLF001
+        if (s2 := m2._surrogates.get(k)) is None:  # noqa: SLF001
+            return False
+        if s1.args != s2.args:
+            return False
+        if s1.stoichiometries != s2.stoichiometries:
+            return False
+    return True
+
+
+def model_diff(m1: Model, m2: Model) -> ModelDiff:
+    """Compute the difference between two models."""
+    diff = ModelDiff()
+
+    for k, v1 in m1._parameters.items():  # noqa: SLF001
+        if (v2 := m2._parameters.get(k)) is None:  # noqa: SLF001
+            diff.missing_parameters.add(k)
+        elif v1 != v2:
+            diff.different_parameters[k] = (v1, v2)
+
+    for k, v1 in m1._variables.items():  # noqa: SLF001
+        if (v2 := m2._variables.get(k)) is None:  # noqa: SLF001
+            diff.missing_variables.add(k)
+        elif v1 != v2:
+            diff.different_variables[k] = (v1, v2)
+
+    for k, v1 in m1._readouts.items():  # noqa: SLF001
+        if (v2 := m2._readouts.get(k)) is None:  # noqa: SLF001
+            diff.missing_readouts.add(k)
+        elif v1.args != v2.args:
+            diff.different_readouts[k] = DerivedDiff(v1.args, v2.args)
+
+    for k, v1 in m1._derived.items():  # noqa: SLF001
+        if (v2 := m2._derived.get(k)) is None:  # noqa: SLF001
+            diff.missing_derived.add(k)
+        elif v1.args != v2.args:
+            diff.different_derived[k] = DerivedDiff(v1.args, v2.args)
+
+    for k, v1 in m1._reactions.items():  # noqa: SLF001
+        if (v2 := m2._reactions.get(k)) is None:  # noqa: SLF001
+            diff.missing_reactions.add(k)
+        else:
+            if v1.args != v2.args:
+                rxn_diff: ReactionDiff = diff.different_reactions.get(k, ReactionDiff())
+                rxn_diff.args1 = v1.args
+                rxn_diff.args2 = v2.args
+                diff.different_reactions[k] = rxn_diff
+            if v1.stoichiometry != v2.stoichiometry:
+                rxn_diff = diff.different_reactions.get(k, ReactionDiff())
+                rxn_diff.stoichiometry1 = dict(v1.stoichiometry)
+                rxn_diff.stoichiometry2 = dict(v2.stoichiometry)
+                diff.different_reactions[k] = rxn_diff
+
+    for k, v1 in m1._surrogates.items():  # noqa: SLF001
+        if (v2 := m2._surrogates.get(k)) is None:  # noqa: SLF001
+            diff.missing_surrogates.add(k)
+        else:
+            if v1.args != v2.args:
+                rxn_diff = diff.different_surrogates.get(k, ReactionDiff())
+                rxn_diff.args1 = v1.args
+                rxn_diff.args2 = v2.args
+            if v1.stoichiometries != v2.stoichiometries:
+                rxn_diff = diff.different_surrogates.get(k, ReactionDiff())
+                rxn_diff.stoichiometry1 = dict(v1.stoichiometries)  # type: ignore
+                rxn_diff.stoichiometry2 = dict(v2.stoichiometries)  # type: ignore
+
+    return diff

mxlpy/fit.py

@@ -0,0 +1,291 @@
+"""Parameter Fitting Module for Metabolic Models.
+
+This module provides functions foru fitting model parameters to experimental data,
+including both steadyd-state and time-series data fitting capabilities.e
+
+Functions:
+    fit_steady_state: Fits parameters to steady-state experimental data
+    fit_time_course: Fits parameters to time-series experimental data
+"""
+
+from __future__ import annotations
+
+from functools import partial
+from typing import TYPE_CHECKING, Protocol
+
+import numpy as np
+from scipy.optimize import minimize
+
+from mxlpy.integrators import DefaultIntegrator
+from mxlpy.simulator import Simulator
+from mxlpy.types import (
+    Array,
+    ArrayLike,
+    Callable,
+    IntegratorProtocol,
+    cast,
+)
+
+__all__ = [
+    "InitialGuess",
+    "MinimizeFn",
+    "ResidualFn",
+    "SteadyStateResidualFn",
+    "TimeSeriesResidualFn",
+    "steady_state",
+    "time_course",
+]
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+    from mxlpy.model import Model
+
+type InitialGuess = dict[str, float]
+type ResidualFn = Callable[[Array], float]
+type MinimizeFn = Callable[[ResidualFn, InitialGuess], dict[str, float]]
+
+
+class SteadyStateResidualFn(Protocol):
+    """Protocol for steady state residual functions."""
+
+    def __call__(
+        self,
+        par_values: Array,
+        # This will be filled out by partial
+        par_names: list[str],
+        data: pd.Series,
+        model: Model,
+        y0: dict[str, float],
+        integrator: Callable[[Callable, ArrayLike], IntegratorProtocol],
+    ) -> float:
+        """Calculate residual error between model steady state and experimental data."""
+        ...
+
+
+class TimeSeriesResidualFn(Protocol):
+    """Protocol for time series residual functions."""
+
+    def __call__(
+        self,
+        par_values: Array,
+        # This will be filled out by partial
+        par_names: list[str],
+        data: pd.DataFrame,
+        model: Model,
+        y0: dict[str, float],
+        integrator: Callable[[Callable, ArrayLike], IntegratorProtocol],
+    ) -> float:
+        """Calculate residual error between model time course and experimental data."""
+        ...
+
+
+def _default_minimize_fn(
+    residual_fn: ResidualFn,
+    p0: dict[str, float],
+) -> dict[str, float]:
+    res = minimize(
+        residual_fn,
+        x0=list(p0.values()),
+        bounds=[(1e-12, 1e6) for _ in range(len(p0))],
+        method="L-BFGS-B",
+    )
+    if res.success:
+        return dict(
+            zip(
+                p0,
+                res.x,
+                strict=True,
+            )
+        )
+    return dict(zip(p0, np.full(len(p0), np.nan, dtype=float), strict=True))
+
+
+def _steady_state_residual(
+    par_values: Array,
+    # This will be filled out by partial
+    par_names: list[str],
+    data: pd.Series,
+    model: Model,
+    y0: dict[str, float] | None,
+    integrator: Callable[[Callable, ArrayLike], IntegratorProtocol],
+) -> float:
+    """Calculate residual error between model steady state and experimental data.
+
+    Args:
+        par_values: Parameter values to test
+        data: Experimental steady state data
+        model: Model instance to simulate
+        y0: Initial conditions
+        par_names: Names of parameters being fit
+        integrator: ODE integrator class to use
+
+    Returns:
+        float: Root mean square error between model and data
+
+    """
+    res = (
+        Simulator(
+            model.update_parameters(
+                dict(
+                    zip(
+                        par_names,
+                        par_values,
+                        strict=True,
+                    )
+                )
+            ),
+            y0=y0,
+            integrator=integrator,
+        )
+        .simulate_to_steady_state()
+        .get_result()
+    )
+    if res is None:
+        return cast(float, np.inf)
+    results_ss = res.get_combined()
+    diff = data - results_ss.loc[:, data.index]  # type: ignore
+    return cast(float, np.sqrt(np.mean(np.square(diff))))
+
+
+def _time_course_residual(
+    par_values: ArrayLike,
+    # This will be filled out by partial
+    par_names: list[str],
+    data: pd.DataFrame,
+    model: Model,
+    y0: dict[str, float],
+    integrator: Callable[[Callable, ArrayLike], IntegratorProtocol],
+) -> float:
+    """Calculate residual error between model time course and experimental data.
+
+    Args:
+        par_values: Parameter values to test
+        data: Experimental time course data
+        model: Model instance to simulate
+        y0: Initial conditions
+        par_names: Names of parameters being fit
+        integrator: ODE integrator class to use
+
+    Returns:
+        float: Root mean square error between model and data
+
+    """
+    res = (
+        Simulator(
+            model.update_parameters(dict(zip(par_names, par_values, strict=True))),
+            y0=y0,
+            integrator=integrator,
+        )
+        .simulate_time_course(data.index)  # type: ignore
+        .get_result()
+    )
+    if res is None:
+        return cast(float, np.inf)
+    results_ss = res.get_combined()
+    diff = data - results_ss.loc[:, data.columns]  # type: ignore
+    return cast(float, np.sqrt(np.mean(np.square(diff))))
+
+
+def steady_state(
+    model: Model,
+    p0: dict[str, float],
+    data: pd.Series,
+    y0: dict[str, float] | None = None,
+    minimize_fn: MinimizeFn = _default_minimize_fn,
+    residual_fn: SteadyStateResidualFn = _steady_state_residual,
+    integrator: Callable[[Callable, ArrayLike], IntegratorProtocol] = DefaultIntegrator,
+) -> dict[str, float]:
+    """Fit model parameters to steady-state experimental data.
+
+    Examples:
+        >>> steady_state(model, p0, data)
+        {'k1': 0.1, 'k2': 0.2}
+
+    Args:
+        model: Model instance to fit
+        data: Experimental steady state data as pandas Series
+        p0: Initial parameter guesses as {parameter_name: value}
+        y0: Initial conditions as {species_name: value}
+        minimize_fn: Function to minimize fitting error
+        residual_fn: Function to calculate fitting error
+        integrator: ODE integrator class
+
+    Returns:
+        dict[str, float]: Fitted parameters as {parameter_name: fitted_value}
+
+    Note:
+        Uses L-BFGS-B optimization with bounds [1e-12, 1e6] for all parameters
+
+    """
+    par_names = list(p0.keys())
+
+    # Copy to restore
+    p_orig = model.parameters
+
+    fn = cast(
+        ResidualFn,
+        partial(
+            residual_fn,
+            data=data,
+            model=model,
+            y0=y0,
+            par_names=par_names,
+            integrator=integrator,
+        ),
+    )
+    res = minimize_fn(fn, p0)
+
+    # Restore
+    model.update_parameters(p_orig)
+    return res
+
+
+def time_course(
+    model: Model,
+    p0: dict[str, float],
+    data: pd.DataFrame,
+    y0: dict[str, float] | None = None,
+    minimize_fn: MinimizeFn = _default_minimize_fn,
+    residual_fn: TimeSeriesResidualFn = _time_course_residual,
+    integrator: Callable[[Callable, ArrayLike], IntegratorProtocol] = DefaultIntegrator,
+) -> dict[str, float]:
+    """Fit model parameters to time course of experimental data.
+
+    Examples:
+        >>> time_course(model, p0, data)
+        {'k1': 0.1, 'k2': 0.2}
+
+    Args:
+        model: Model instance to fit
+        data: Experimental time course data as pandas DataFrame
+        p0: Initial parameter guesses as {parameter_name: value}
+        y0: Initial conditions as {species_name: value}
+        minimize_fn: Function to minimize fitting error
+        residual_fn: Function to calculate fitting error
+        integrator: ODE integrator class
+
+    Returns:
+        dict[str, float]: Fitted parameters as {parameter_name: fitted_value}
+
+    Note:
+        Uses L-BFGS-B optimization with bounds [1e-12, 1e6] for all parameters
+
+    """
+    par_names = list(p0.keys())
+    p_orig = model.parameters
+
+    fn = cast(
+        ResidualFn,
+        partial(
+            residual_fn,
+            data=data,
+            model=model,
+            y0=y0,
+            par_names=par_names,
+            integrator=integrator,
+        ),
+    )
+    res = minimize_fn(fn, p0)
+    model.update_parameters(p_orig)
+    return res

mxlpy/fns.py

@@ -0,0 +1,191 @@
+"""Module containing functions for reactions and derived quatities."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mxlpy.types import Float
+
+__all__ = [
+    "add",
+    "constant",
+    "diffusion_1s_1p",
+    "div",
+    "mass_action_1s",
+    "mass_action_1s_1p",
+    "mass_action_2s",
+    "mass_action_2s_1p",
+    "michaelis_menten_1s",
+    "michaelis_menten_2s",
+    "michaelis_menten_3s",
+    "minus",
+    "moiety_1s",
+    "moiety_2s",
+    "mul",
+    "neg",
+    "neg_div",
+    "one_div",
+    "proportional",
+    "twice",
+]
+
+
+###############################################################################
+# General functions
+###############################################################################
+
+
+def constant(x: Float) -> Float:
+    """Constant function."""
+    return x
+
+
+def neg(x: Float) -> Float:
+    """Negation function."""
+    return -x
+
+
+def minus(x: Float, y: Float) -> Float:
+    """Subtraction function."""
+    return x - y
+
+
+def mul(x: Float, y: Float) -> Float:
+    """Multiplication function."""
+    return x * y
+
+
+def div(x: Float, y: Float) -> Float:
+    """Division function."""
+    return x / y
+
+
+def one_div(x: Float) -> Float:
+    """Reciprocal function."""
+    return 1.0 / x
+
+
+def neg_div(x: Float, y: Float) -> Float:
+    """Negated division function."""
+    return -x / y
+
+
+def twice(x: Float) -> Float:
+    """Twice function."""
+    return x * 2
+
+
+def add(x: Float, y: Float) -> Float:
+    """Proportional function."""
+    return x + y
+
+
+def proportional(x: Float, y: Float) -> Float:
+    """Proportional function."""
+    return x * y
+
+
+###############################################################################
+# Derived functions
+###############################################################################
+
+
+def moiety_1s(
+    x: Float,
+    x_total: Float,
+) -> Float:
+    """General moiety for one substrate."""
+    return x_total - x
+
+
+def moiety_2s(
+    x1: Float,
+    x2: Float,
+    x_total: Float,
+) -> Float:
+    """General moiety for two substrates."""
+    return x_total - x1 - x2
+
+
+###############################################################################
+# Reactions: mass action type
+###############################################################################
+
+
+def mass_action_1s(s1: Float, k: Float) -> Float:
+    """Irreversible mass action reaction with one substrate."""
+    return k * s1
+
+
+def mass_action_1s_1p(s1: Float, p1: Float, kf: Float, kr: Float) -> Float:
+    """Reversible mass action reaction with one substrate and one product."""
+    return kf * s1 - kr * p1
+
+
+def mass_action_2s(s1: Float, s2: Float, k: Float) -> Float:
+    """Irreversible mass action reaction with two substrates."""
+    return k * s1 * s2
+
+
+def mass_action_2s_1p(s1: Float, s2: Float, p1: Float, kf: Float, kr: Float) -> Float:
+    """Reversible mass action reaction with two substrates and one product."""
+    return kf * s1 * s2 - kr * p1
+
+
+###############################################################################
+# Reactions: michaelis-menten type
+# For multi-molecular reactions use ping-pong kinetics as default
+###############################################################################
+
+
+def michaelis_menten_1s(s1: Float, vmax: Float, km1: Float) -> Float:
+    """Irreversible Michaelis-Menten equation for one substrate."""
+    return s1 * vmax / (s1 + km1)
+
+
+# def michaelis_menten_1s_1i(
+#     s: float,
+#     i: float,
+#     vmax: float,
+#     km: float,
+#     ki: float,
+# ) -> float:
+#     """Irreversible Michaelis-Menten equation for one substrate and one inhibitor."""
+#     return vmax * s / (s + km * (1 + i / ki))
+
+
+def michaelis_menten_2s(
+    s1: Float,
+    s2: Float,
+    vmax: Float,
+    km1: Float,
+    km2: Float,
+) -> Float:
+    """Michaelis-Menten equation (ping-pong) for two substrates."""
+    return vmax * s1 * s2 / (s1 * s2 + km1 * s2 + km2 * s1)
+
+
+def michaelis_menten_3s(
+    s1: Float,
+    s2: Float,
+    s3: Float,
+    vmax: Float,
+    km1: Float,
+    km2: Float,
+    km3: Float,
+) -> Float:
+    """Michaelis-Menten equation (ping-pong) for three substrates."""
+    return (
+        vmax * s1 * s2 * s3 / (s1 * s2 + km1 * s2 * s3 + km2 * s1 * s3 + km3 * s1 * s2)
+    )
+
+
+###############################################################################
+# Reactions: michaelis-menten type
+###############################################################################
+
+
+def diffusion_1s_1p(inside: Float, outside: Float, k: Float) -> Float:
+    """Diffusion reaction with one substrate and one product."""
+    return k * (outside - inside)