modelbase2 0.1.79__py3-none-any.whl → 0.2.0__py3-none-any.whl

modelbase2/fit.py

@@ -0,0 +1,284 @@
+"""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
+import pandas as pd
+from scipy.optimize import minimize
+
+from modelbase2.integrators import DefaultIntegrator
+from modelbase2.simulator import Simulator
+from modelbase2.types import Array, ArrayLike, Callable, IntegratorProtocol, cast
+
+__all__ = [
+    "InitialGuess",
+    "MinimizeFn",
+    "ResidualFn",
+    "SteadyStateResidualFn",
+    "TimeSeriesResidualFn",
+    "steady_state",
+    "time_course",
+]
+
+if TYPE_CHECKING:
+    from modelbase2.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: type[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: type[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: type[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
+
+    """
+    c_ss, v_ss = (
+        Simulator(
+            model.update_parameters(
+                dict(
+                    zip(
+                        par_names,
+                        par_values,
+                        strict=True,
+                    )
+                )
+            ),
+            y0=y0,
+            integrator=integrator,
+        )
+        .simulate_to_steady_state()
+        .get_full_concs_and_fluxes()
+    )
+    if c_ss is None or v_ss is None:
+        return cast(float, np.inf)
+    results_ss = pd.concat((c_ss, v_ss), axis=1)
+    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: type[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
+
+    """
+    c_ss, v_ss = (
+        Simulator(
+            model.update_parameters(dict(zip(par_names, par_values, strict=True))),
+            y0=y0,
+            integrator=integrator,
+        )
+        .simulate_time_course(data.index)  # type: ignore
+        .get_full_concs_and_fluxes()
+    )
+    if c_ss is None or v_ss is None:
+        return cast(float, np.inf)
+    results_ss = pd.concat((c_ss, v_ss), axis=1)
+    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: type[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: type[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

modelbase2/fns.py

@@ -0,0 +1,185 @@
+"""Module containing functions for reactions and derived quatities."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from modelbase2.types import Float
+
+__all__ = [
+    "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 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)

modelbase2/integrators/__init__.py

@@ -0,0 +1,19 @@
+"""Integrator Package.
+
+This package provides integrators for solving ordinary differential equations (ODEs).
+It includes support for both Assimulo and Scipy integrators, with Assimulo being the default if available.
+"""
+
+from __future__ import annotations
+
+__all__ = ["DefaultIntegrator"]
+
+
+from .int_scipy import Scipy
+
+try:
+    from .int_assimulo import Assimulo
+
+    DefaultIntegrator = Assimulo
+except ImportError:
+    DefaultIntegrator = Scipy

modelbase2/integrators/int_assimulo.py

@@ -0,0 +1,146 @@
+"""Assimulo integrator for solving ODEs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = [
+    "Assimulo",
+]
+
+import contextlib
+import os
+from typing import TYPE_CHECKING, Literal
+
+import numpy as np
+
+with contextlib.redirect_stderr(open(os.devnull, "w")):  # noqa: PTH123
+    from assimulo.problem import Explicit_Problem  # type: ignore
+    from assimulo.solvers import CVode  # type: ignore
+    from assimulo.solvers.sundials import CVodeError  # type: ignore
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from modelbase2.types import ArrayLike
+
+
+@dataclass
+class Assimulo:
+    """Assimulo integrator for solving ODEs.
+
+    Attributes:
+        rhs: Right-hand side function of the ODE.
+        y0: Initial conditions.
+        atol: Absolute tolerance for the solver.
+        rtol: Relative tolerance for the solver.
+        maxnef: Maximum number of error failures.
+        maxncf: Maximum number of convergence failures.
+        verbosity: Verbosity level of the solver.
+
+    Methods:
+        integrate: Integrate the ODE system.
+
+    """
+
+    rhs: Callable
+    y0: ArrayLike
+    atol: float = 1e-8
+    rtol: float = 1e-8
+    maxnef: int = 4  # max error failures
+    maxncf: int = 1  # max convergence failures
+    verbosity: Literal[50, 40, 30, 20, 10] = 50
+
+    def __post_init__(self) -> None:
+        """Post-initialization method for setting up the CVode integrator with the provided parameters.
+
+        This method initializes the CVode integrator with an explicit problem defined by the
+        right-hand side function (`self.rhs`) and the initial conditions (`self.y0`). It also
+        sets various integrator options such as absolute tolerance (`self.atol`), relative
+        tolerance (`self.rtol`), maximum number of error test failures (`self.maxnef`), maximum
+        number of convergence failures (`self.maxncf`), and verbosity level (`self.verbosity`).
+
+        """
+        self.integrator = CVode(Explicit_Problem(self.rhs, self.y0))
+        self.integrator.atol = self.atol
+        self.integrator.rtol = self.rtol
+        self.integrator.maxnef = self.maxnef
+        self.integrator.maxncf = self.maxncf
+        self.integrator.verbosity = self.verbosity
+
+    def reset(self) -> None:
+        """Reset the integrator."""
+        self.integrator.reset()
+
+    def integrate(
+        self,
+        *,
+        t_end: float,
+        steps: int | None = None,
+    ) -> tuple[ArrayLike | None, ArrayLike | None]:
+        """Integrate the ODE system.
+
+        Args:
+            t_end: Terminal time point for the integration.
+            steps: Number of steps for the integration.
+            time_points: Time points for the integration.
+
+        Returns:
+            np.ndarray: Array of integrated values.
+
+        """
+        if steps is None:
+            steps = 0
+        try:
+            return self.integrator.simulate(t_end, steps)  # type: ignore
+        except CVodeError:
+            return None, None
+
+    def integrate_time_course(
+        self,
+        *,
+        time_points: ArrayLike,
+    ) -> tuple[ArrayLike | None, ArrayLike | None]:
+        """Integrate the ODE system over a time course.
+
+        Args:
+            time_points: Time points for the integration.
+
+        Returns:
+            tuple[ArrayLike | None, ArrayLike | None]: Tuple containing the time points and the integrated values.
+
+        """
+        try:
+            return self.integrator.simulate(time_points[-1], 0, time_points)  # type: ignore
+        except CVodeError:
+            return None, None
+
+    def integrate_to_steady_state(
+        self,
+        *,
+        tolerance: float,
+        rel_norm: bool,
+        t_max: float = 1_000_000_000,
+    ) -> tuple[float | None, ArrayLike | None]:
+        """Integrate the ODE system to steady state.
+
+        Args:
+            tolerance: Tolerance for determining steady state.
+            rel_norm: Whether to use relative normalization.
+            t_max: Maximum time point for the integration (default: 1,000,000,000).
+
+        Returns:
+            tuple[float | None, ArrayLike | None]: Tuple containing the final time point and the integrated values at steady state.
+
+        """
+        self.reset()
+
+        try:
+            for t_end in np.geomspace(1000, t_max, 3):
+                t, y = self.integrator.simulate(t_end)
+                diff = (y[-1] - y[-2]) / y[-1] if rel_norm else y[-1] - y[-2]
+                if np.linalg.norm(diff, ord=2) < tolerance:
+                    return t[-1], y[-1]
+        except CVodeError:
+            return None, None
+        return None, None