mxlpy 0.23.0__py3-none-any.whl → 0.25.0__py3-none-any.whl

mxlpy/{fit.py → fit/local_.py}

@@ -1,27 +1,39 @@
-"""Parameter Fitting Module for Metabolic Models.
+"""Parameter local 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
+This module provides functions for fitting model parameters to experimental data,
+including both steadyd-state and time-series data fitting capabilities.
 """
 
 from __future__ import annotations
 
 import logging
+from collections.abc import Callable
 from copy import deepcopy
 from dataclasses import dataclass
 from functools import partial
-from typing import TYPE_CHECKING, Protocol
+from typing import TYPE_CHECKING, Literal
 
-import numpy as np
 from scipy.optimize import minimize
 
 from mxlpy import parallel
-from mxlpy.simulator import Simulator
-from mxlpy.types import Array, ArrayLike, Callable, IntegratorType, cast
+from mxlpy.types import IntegratorType, cast
+
+from .common import (
+    Bounds,
+    CarouselFit,
+    FitResult,
+    InitialGuess,
+    LossFn,
+    MinResult,
+    ProtocolResidualFn,
+    ResidualFn,
+    SteadyStateResidualFn,
+    TimeSeriesResidualFn,
+    _protocol_time_course_residual,
+    _steady_state_residual,
+    _time_course_residual,
+    rmse,
+)
 
 if TYPE_CHECKING:
     import pandas as pd
@@ -32,60 +44,19 @@ if TYPE_CHECKING:
 LOGGER = logging.getLogger(__name__)
 
 __all__ = [
-    "Bounds",
-    "CarouselFit",
-    "FitResult",
-    "InitialGuess",
     "LOGGER",
-    "LossFn",
-    "MinResult",
-    "MinimizeFn",
-    "ProtocolResidualFn",
-    "ResidualFn",
-    "SteadyStateResidualFn",
-    "TimeSeriesResidualFn",
+    "Minimizer",
+    "ScipyMinimizer",
     "carousel_protocol_time_course",
     "carousel_steady_state",
     "carousel_time_course",
     "protocol_time_course",
-    "rmse",
     "steady_state",
     "time_course",
 ]
 
 
-@dataclass
-class MinResult:
-    """Result of a minimization operation."""
-
-    parameters: dict[str, float]
-    residual: float
-
-
-@dataclass
-class FitResult:
-    """Result of a fit operation."""
-
-    model: Model
-    best_pars: dict[str, float]
-    loss: float
-
-
-@dataclass
-class CarouselFit:
-    """Result of a carousel fit operation."""
-
-    fits: list[FitResult]
-
-    def get_best_fit(self) -> FitResult:
-        """Get the best fit from the carousel."""
-        return min(self.fits, key=lambda x: x.loss)
-
-
-type InitialGuess = dict[str, float]
-type ResidualFn = Callable[[Array], float]
-type Bounds = dict[str, tuple[float | None, float | None]]
-type MinimizeFn = Callable[
+type Minimizer = Callable[
     [
         ResidualFn,
         InitialGuess,
@@ -93,248 +64,68 @@ type MinimizeFn = Callable[
     ],
     MinResult | None,
 ]
-type LossFn = Callable[
-    [
-        pd.DataFrame | pd.Series,
-        pd.DataFrame | pd.Series,
-    ],
-    float,
-]
-
 
-def rmse(
-    y_pred: pd.DataFrame | pd.Series,
-    y_true: pd.DataFrame | pd.Series,
-) -> float:
-    """Calculate root mean square error between model and data."""
-    return cast(float, np.sqrt(np.mean(np.square(y_pred - y_true))))
 
+@dataclass
+class ScipyMinimizer:
+    """Local multivariate minimization using scipy.optimize.
 
-class SteadyStateResidualFn(Protocol):
-    """Protocol for steady state residual functions."""
+    See Also
+    --------
+    https://docs.scipy.org/doc/scipy/reference/optimize.html#local-multivariate-optimization
 
-    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] | None,
-        integrator: IntegratorType,
-        loss_fn: LossFn,
-    ) -> 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] | None,
-        integrator: IntegratorType,
-        loss_fn: LossFn,
-    ) -> float:
-        """Calculate residual error between model time course and experimental data."""
-        ...
-
-
-class ProtocolResidualFn(Protocol):
-    """Protocol for time series residual functions."""
+    tol: float = 1e-6
+    method: Literal[
+        "Nelder-Mead",
+        "Powell",
+        "CG",
+        "BFGS",
+        "Newton-CG",
+        "L-BFGS-B",
+        "TNC",
+        "COBYLA",
+        "COBYQA",
+        "SLSQP",
+        "trust-constr",
+        "dogleg",
+        "trust-ncg",
+        "trust-exact",
+        "trust-krylov",
+    ] = "L-BFGS-B"
 
     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] | None,
-        integrator: IntegratorType,
-        loss_fn: LossFn,
-        protocol: pd.DataFrame,
-    ) -> float:
-        """Calculate residual error between model time course and experimental data."""
-        ...
-
-
-def _default_minimize_fn(
-    residual_fn: ResidualFn,
-    p0: dict[str, float],
-    bounds: Bounds,
-) -> MinResult | None:
-    res = minimize(
-        residual_fn,
-        x0=list(p0.values()),
-        bounds=[bounds.get(name, (1e-6, 1e6)) for name in p0],
-        method="L-BFGS-B",
-    )
-    if res.success:
-        return MinResult(
-            parameters=dict(
-                zip(
-                    p0,
-                    res.x,
-                    strict=True,
-                ),
-            ),
-            residual=res.fun,
+        residual_fn: ResidualFn,
+        p0: dict[str, float],
+        bounds: Bounds,
+    ) -> MinResult | None:
+        """Call minimzer."""
+        res = minimize(
+            residual_fn,
+            x0=list(p0.values()),
+            bounds=[bounds.get(name, (1e-6, 1e6)) for name in p0],
+            method=self.method,
+            tol=self.tol,
         )
-
-    LOGGER.warning("Minimisation failed.")
-    return None
-
-
-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: IntegratorType,
-    loss_fn: LossFn,
-) -> 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
-        loss_fn: Loss function to use for residual calculation
-
-    Returns:
-        float: Root mean square error between model and data
-
-    """
-    res = (
-        Simulator(
-            model.update_parameters(
-                dict(
+        if res.success:
+            return MinResult(
+                parameters=dict(
                     zip(
-                        par_names,
-                        par_values,
+                        p0,
+                        res.x,
                         strict=True,
-                    )
-                )
-            ),
-            y0=y0,
-            integrator=integrator,
-        )
-        .simulate_to_steady_state()
-        .get_result()
-    )
-    if res is None:
-        return cast(float, np.inf)
-
-    return loss_fn(
-        res.get_combined().loc[:, cast(list, data.index)],
-        data,
-    )
-
-
-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] | None,
-    integrator: IntegratorType,
-    loss_fn: LossFn,
-) -> 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
-        loss_fn: Loss function to use for residual calculation
-
-    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(cast(list, data.index))
-        .get_result()
-    )
-    if res is None:
-        return cast(float, np.inf)
-    results_ss = res.get_combined()
-
-    return loss_fn(
-        results_ss.loc[:, cast(list, data.columns)],
-        data,
-    )
-
-
-def _protocol_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] | None,
-    integrator: IntegratorType,
-    loss_fn: LossFn,
-    protocol: pd.DataFrame,
-) -> 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
-        loss_fn: Loss function to use for residual calculation
-        protocol: Experimental protocol
-        time_points_per_step: Number of time points per step in the protocol
+                    ),
+                ),
+                residual=res.fun,
+            )
 
-    Returns:
-        float: Root mean square error between model and data
+        LOGGER.warning("Minimisation failed due to %s", res.message)
+        return None
 
-    """
-    res = (
-        Simulator(
-            model.update_parameters(dict(zip(par_names, par_values, strict=True))),
-            y0=y0,
-            integrator=integrator,
-        )
-        .simulate_protocol_time_course(
-            protocol=protocol,
-            time_points=data.index,
-        )
-        .get_result()
-    )
-    if res is None:
-        return cast(float, np.inf)
-    results_ss = res.get_combined()
 
-    return loss_fn(
-        results_ss.loc[:, cast(list, data.columns)],
-        data,
-    )
+_default_minimizer = ScipyMinimizer()
 
 
 def _carousel_steady_state_worker(
@@ -344,7 +135,7 @@ def _carousel_steady_state_worker(
     y0: dict[str, float] | None,
     integrator: IntegratorType | None,
     loss_fn: LossFn,
-    minimize_fn: MinimizeFn,
+    minimizer: Minimizer,
     residual_fn: SteadyStateResidualFn,
     bounds: Bounds | None,
 ) -> FitResult | None:
@@ -355,7 +146,7 @@ def _carousel_steady_state_worker(
         p0={k: v for k, v in p0.items() if k in model_pars},
         y0=y0,
         data=data,
-        minimize_fn=minimize_fn,
+        minimizer=minimizer,
         residual_fn=residual_fn,
         integrator=integrator,
         loss_fn=loss_fn,
@@ -370,7 +161,7 @@ def _carousel_time_course_worker(
     y0: dict[str, float] | None,
     integrator: IntegratorType | None,
     loss_fn: LossFn,
-    minimize_fn: MinimizeFn,
+    minimizer: Minimizer,
     residual_fn: TimeSeriesResidualFn,
     bounds: Bounds | None,
 ) -> FitResult | None:
@@ -380,7 +171,7 @@ def _carousel_time_course_worker(
         p0={k: v for k, v in p0.items() if k in model_pars},
         y0=y0,
         data=data,
-        minimize_fn=minimize_fn,
+        minimizer=minimizer,
         residual_fn=residual_fn,
         integrator=integrator,
         loss_fn=loss_fn,
@@ -396,7 +187,7 @@ def _carousel_protocol_worker(
     y0: dict[str, float] | None,
     integrator: IntegratorType | None,
     loss_fn: LossFn,
-    minimize_fn: MinimizeFn,
+    minimizer: Minimizer,
     residual_fn: ProtocolResidualFn,
     bounds: Bounds | None,
 ) -> FitResult | None:
@@ -407,7 +198,7 @@ def _carousel_protocol_worker(
         y0=y0,
         protocol=protocol,
         data=data,
-        minimize_fn=minimize_fn,
+        minimizer=minimizer,
         residual_fn=residual_fn,
         integrator=integrator,
         loss_fn=loss_fn,
@@ -421,7 +212,7 @@ def steady_state(
     p0: dict[str, float],
     data: pd.Series,
     y0: dict[str, float] | None = None,
-    minimize_fn: MinimizeFn = _default_minimize_fn,
+    minimizer: Minimizer = _default_minimizer,
     residual_fn: SteadyStateResidualFn = _steady_state_residual,
     integrator: IntegratorType | None = None,
     loss_fn: LossFn = rmse,
@@ -438,7 +229,7 @@ def steady_state(
         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
+        minimizer: Function to minimize fitting error
         residual_fn: Function to calculate fitting error
         integrator: ODE integrator class
         loss_fn: Loss function to use for residual calculation
@@ -468,7 +259,7 @@ def steady_state(
             loss_fn=loss_fn,
         ),
     )
-    min_result = minimize_fn(fn, p0, {} if bounds is None else bounds)
+    min_result = minimizer(fn, p0, {} if bounds is None else bounds)
     # Restore original model
     model.update_parameters(p_orig)
     if min_result is None:
@@ -487,7 +278,7 @@ def time_course(
     p0: dict[str, float],
     data: pd.DataFrame,
     y0: dict[str, float] | None = None,
-    minimize_fn: MinimizeFn = _default_minimize_fn,
+    minimizer: Minimizer = _default_minimizer,
     residual_fn: TimeSeriesResidualFn = _time_course_residual,
     integrator: IntegratorType | None = None,
     loss_fn: LossFn = rmse,
@@ -504,7 +295,7 @@ def time_course(
         data: Experimental time course data
         p0: Initial parameter guesses as {parameter_name: value}
         y0: Initial conditions as {species_name: value}
-        minimize_fn: Function to minimize fitting error
+        minimizer: Function to minimize fitting error
         residual_fn: Function to calculate fitting error
         integrator: ODE integrator class
         loss_fn: Loss function to use for residual calculation
@@ -533,7 +324,7 @@ def time_course(
         ),
     )
 
-    min_result = minimize_fn(fn, p0, {} if bounds is None else bounds)
+    min_result = minimizer(fn, p0, {} if bounds is None else bounds)
     # Restore original model
     model.update_parameters(p_orig)
     if min_result is None:
@@ -553,7 +344,7 @@ def protocol_time_course(
     data: pd.DataFrame,
     protocol: pd.DataFrame,
     y0: dict[str, float] | None = None,
-    minimize_fn: MinimizeFn = _default_minimize_fn,
+    minimizer: Minimizer = _default_minimizer,
     residual_fn: ProtocolResidualFn = _protocol_time_course_residual,
     integrator: IntegratorType | None = None,
     loss_fn: LossFn = rmse,
@@ -561,6 +352,8 @@ def protocol_time_course(
 ) -> FitResult | None:
     """Fit model parameters to time course of experimental data.
 
+    Time points of protocol time course are taken from the data.
+
     Examples:
         >>> time_course(model, p0, data)
         {'k1': 0.1, 'k2': 0.2}
@@ -571,7 +364,7 @@ def protocol_time_course(
         data: Experimental time course data
         protocol: Experimental protocol
         y0: Initial conditions as {species_name: value}
-        minimize_fn: Function to minimize fitting error
+        minimizer: Function to minimize fitting error
         residual_fn: Function to calculate fitting error
         integrator: ODE integrator class
         loss_fn: Loss function to use for residual calculation
@@ -602,7 +395,7 @@ def protocol_time_course(
         ),
     )
 
-    min_result = minimize_fn(fn, p0, {} if bounds is None else bounds)
+    min_result = minimizer(fn, p0, {} if bounds is None else bounds)
     # Restore original model
     model.update_parameters(p_orig)
     if min_result is None:
@@ -621,7 +414,7 @@ def carousel_steady_state(
     p0: dict[str, float],
     data: pd.Series,
     y0: dict[str, float] | None = None,
-    minimize_fn: MinimizeFn = _default_minimize_fn,
+    minimizer: Minimizer = _default_minimizer,
     residual_fn: SteadyStateResidualFn = _steady_state_residual,
     integrator: IntegratorType | None = None,
     loss_fn: LossFn = rmse,
@@ -638,7 +431,7 @@ def carousel_steady_state(
         data: Experimental time course data
         protocol: Experimental protocol
         y0: Initial conditions as {species_name: value}
-        minimize_fn: Function to minimize fitting error
+        minimizer: Function to minimize fitting error
         residual_fn: Function to calculate fitting error
         integrator: ODE integrator class
         loss_fn: Loss function to use for residual calculation
@@ -663,7 +456,7 @@ def carousel_steady_state(
                     y0=y0,
                     integrator=integrator,
                     loss_fn=loss_fn,
-                    minimize_fn=minimize_fn,
+                    minimizer=minimizer,
                     residual_fn=residual_fn,
                     bounds=bounds,
                 ),
@@ -680,7 +473,7 @@ def carousel_time_course(
     p0: dict[str, float],
     data: pd.DataFrame,
     y0: dict[str, float] | None = None,
-    minimize_fn: MinimizeFn = _default_minimize_fn,
+    minimizer: Minimizer = _default_minimizer,
     residual_fn: TimeSeriesResidualFn = _time_course_residual,
     integrator: IntegratorType | None = None,
     loss_fn: LossFn = rmse,
@@ -688,8 +481,10 @@ def carousel_time_course(
 ) -> CarouselFit:
     """Fit model parameters to time course of experimental data over a carousel.
 
+    Time points are taken from the data.
+
     Examples:
-        >>> carousel_steady_state(carousel, p0=p0, data=data)
+        >>> carousel_time_course(carousel, p0=p0, data=data)
 
     Args:
         carousel: Model carousel to fit
@@ -697,7 +492,7 @@ def carousel_time_course(
         data: Experimental time course data
         protocol: Experimental protocol
         y0: Initial conditions as {species_name: value}
-        minimize_fn: Function to minimize fitting error
+        minimizer: Function to minimize fitting error
         residual_fn: Function to calculate fitting error
         integrator: ODE integrator class
         loss_fn: Loss function to use for residual calculation
@@ -722,7 +517,7 @@ def carousel_time_course(
                     y0=y0,
                     integrator=integrator,
                     loss_fn=loss_fn,
-                    minimize_fn=minimize_fn,
+                    minimizer=minimizer,
                     residual_fn=residual_fn,
                     bounds=bounds,
                 ),
@@ -740,7 +535,7 @@ def carousel_protocol_time_course(
     data: pd.DataFrame,
     protocol: pd.DataFrame,
     y0: dict[str, float] | None = None,
-    minimize_fn: MinimizeFn = _default_minimize_fn,
+    minimizer: Minimizer = _default_minimizer,
     residual_fn: ProtocolResidualFn = _protocol_time_course_residual,
     integrator: IntegratorType | None = None,
     loss_fn: LossFn = rmse,
@@ -748,6 +543,8 @@ def carousel_protocol_time_course(
 ) -> CarouselFit:
     """Fit model parameters to time course of experimental data over a protocol.
 
+    Time points of protocol time course are taken from the data.
+
     Examples:
         >>> carousel_steady_state(carousel, p0=p0, data=data)
 
@@ -757,7 +554,7 @@ def carousel_protocol_time_course(
         data: Experimental time course data
         protocol: Experimental protocol
         y0: Initial conditions as {species_name: value}
-        minimize_fn: Function to minimize fitting error
+        minimizer: Function to minimize fitting error
         residual_fn: Function to calculate fitting error
         integrator: ODE integrator class
         loss_fn: Loss function to use for residual calculation
@@ -783,7 +580,7 @@ def carousel_protocol_time_course(
                     y0=y0,
                     integrator=integrator,
                     loss_fn=loss_fn,
-                    minimize_fn=minimize_fn,
+                    minimizer=minimizer,
                     residual_fn=residual_fn,
                     bounds=bounds,
                 ),

mxlpy/identify.py

@@ -9,8 +9,9 @@ import numpy as np
 import pandas as pd
 from tqdm import tqdm
 
-from mxlpy import fit
+from mxlpy import fit_local
 from mxlpy.distributions import LogNormal, sample
+from mxlpy.fit.common import LossFn, rmse
 from mxlpy.parallel import parallelise
 
 if TYPE_CHECKING:
@@ -26,9 +27,9 @@ def _mc_fit_time_course_worker(
     p0: pd.Series,
     model: Model,
     data: pd.DataFrame,
-    loss_fn: fit.LossFn,
+    loss_fn: fit_local.LossFn,
 ) -> float:
-    fit_result = fit.time_course(
+    fit_result = fit_local.time_course(
         model=model,
         p0=p0.to_dict(),
         data=data,
@@ -45,7 +46,7 @@ def profile_likelihood(
     parameter_name: str,
     parameter_values: Array,
     n_random: int = 10,
-    loss_fn: fit.LossFn = fit.rmse,
+    loss_fn: LossFn = rmse,
 ) -> pd.Series:
     """Estimate the profile likelihood of model parameters given data.