mxlpy 0.19.0__py3-none-any.whl → 0.21.0__py3-none-any.whl

mxlpy/fit.py

@@ -10,44 +10,80 @@ Functions:
 
 from __future__ import annotations
 
+import logging
+from copy import deepcopy
+from dataclasses import dataclass
 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 import parallel
 from mxlpy.simulator import Simulator
-from mxlpy.types import (
-    Array,
-    ArrayLike,
-    Callable,
-    IntegratorType,
-    cast,
-)
+from mxlpy.types import Array, ArrayLike, Callable, IntegratorType, cast
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+    from mxlpy.carousel import Carousel
+    from mxlpy.model import Model
+
+LOGGER = logging.getLogger(__name__)
 
 __all__ = [
+    "CarouselFit",
+    "FitResult",
     "InitialGuess",
+    "LOGGER",
     "LossFn",
+    "MinResult",
     "MinimizeFn",
     "ProtocolResidualFn",
     "ResidualFn",
     "SteadyStateResidualFn",
     "TimeSeriesResidualFn",
+    "carousel_steady_state",
+    "carousel_time_course",
+    "carousel_time_course_over_protocol",
     "rmse",
     "steady_state",
     "time_course",
     "time_course_over_protocol",
 ]
 
-if TYPE_CHECKING:
-    import pandas as pd
 
-    from mxlpy.model import Model
+@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 MinimizeFn = Callable[[ResidualFn, InitialGuess], dict[str, float]]
+type MinimizeFn = Callable[[ResidualFn, InitialGuess], MinResult | None]
 type LossFn = Callable[
     [
         pd.DataFrame | pd.Series,
@@ -75,7 +111,7 @@ class SteadyStateResidualFn(Protocol):
         par_names: list[str],
         data: pd.Series,
         model: Model,
-        y0: dict[str, float],
+        y0: dict[str, float] | None,
         integrator: IntegratorType,
         loss_fn: LossFn,
     ) -> float:
@@ -93,7 +129,7 @@ class TimeSeriesResidualFn(Protocol):
         par_names: list[str],
         data: pd.DataFrame,
         model: Model,
-        y0: dict[str, float],
+        y0: dict[str, float] | None,
         integrator: IntegratorType,
         loss_fn: LossFn,
     ) -> float:
@@ -111,7 +147,7 @@ class ProtocolResidualFn(Protocol):
         par_names: list[str],
         data: pd.DataFrame,
         model: Model,
-        y0: dict[str, float],
+        y0: dict[str, float] | None,
         integrator: IntegratorType,
         loss_fn: LossFn,
         protocol: pd.DataFrame,
@@ -124,22 +160,27 @@ class ProtocolResidualFn(Protocol):
 def _default_minimize_fn(
     residual_fn: ResidualFn,
     p0: dict[str, float],
-) -> dict[str, float]:
+) -> MinResult | None:
     res = minimize(
         residual_fn,
         x0=list(p0.values()),
-        bounds=[(1e-12, 1e6) for _ in range(len(p0))],
+        bounds=[(0, None) for _ in range(len(p0))],
         method="L-BFGS-B",
     )
     if res.success:
-        return dict(
-            zip(
-                p0,
-                res.x,
-                strict=True,
-            )
+        return MinResult(
+            parameters=dict(
+                zip(
+                    p0,
+                    res.x,
+                    strict=True,
+                ),
+            ),
+            residual=res.fun,
         )
-    return dict(zip(p0, np.full(len(p0), np.nan, dtype=float), strict=True))
+
+    LOGGER.warning("Minimisation failed.")
+    return None
 
 
 def _steady_state_residual(
@@ -290,14 +331,15 @@ def _protocol_residual(
 
 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: IntegratorType = DefaultIntegrator,
+    integrator: IntegratorType | None = None,
     loss_fn: LossFn = rmse,
-) -> dict[str, float]:
+) -> FitResult | None:
     """Fit model parameters to steady-state experimental data.
 
     Examples:
@@ -338,23 +380,30 @@ def steady_state(
             loss_fn=loss_fn,
         ),
     )
-    res = minimize_fn(fn, p0)
-
-    # Restore
+    min_result = minimize_fn(fn, p0)
+    # Restore original model
     model.update_parameters(p_orig)
-    return res
+    if min_result is None:
+        return min_result
+
+    return FitResult(
+        model=deepcopy(model).update_parameters(min_result.parameters),
+        best_pars=min_result.parameters,
+        loss=min_result.residual,
+    )
 
 
 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: IntegratorType = DefaultIntegrator,
+    integrator: IntegratorType | None = None,
     loss_fn: LossFn = rmse,
-) -> dict[str, float]:
+) -> FitResult | None:
     """Fit model parameters to time course of experimental data.
 
     Examples:
@@ -393,23 +442,33 @@ def time_course(
             loss_fn=loss_fn,
         ),
     )
-    res = minimize_fn(fn, p0)
+
+    min_result = minimize_fn(fn, p0)
+    # Restore original model
     model.update_parameters(p_orig)
-    return res
+    if min_result is None:
+        return min_result
+
+    return FitResult(
+        model=deepcopy(model).update_parameters(min_result.parameters),
+        best_pars=min_result.parameters,
+        loss=min_result.residual,
+    )
 
 
 def time_course_over_protocol(
     model: Model,
+    *,
     p0: dict[str, float],
     data: pd.DataFrame,
     protocol: pd.DataFrame,
     y0: dict[str, float] | None = None,
     minimize_fn: MinimizeFn = _default_minimize_fn,
     residual_fn: ProtocolResidualFn = _protocol_residual,
-    integrator: IntegratorType = DefaultIntegrator,
+    integrator: IntegratorType | None = None,
     loss_fn: LossFn = rmse,
     time_points_per_step: int = 10,
-) -> dict[str, float]:
+) -> FitResult | None:
     """Fit model parameters to time course of experimental data.
 
     Examples:
@@ -452,6 +511,188 @@ def time_course_over_protocol(
             time_points_per_step=time_points_per_step,
         ),
     )
-    res = minimize_fn(fn, p0)
+
+    min_result = minimize_fn(fn, p0)
+    # Restore original model
     model.update_parameters(p_orig)
-    return res
+    if min_result is None:
+        return min_result
+
+    return FitResult(
+        model=deepcopy(model).update_parameters(min_result.parameters),
+        best_pars=min_result.parameters,
+        loss=min_result.residual,
+    )
+
+
+def _carousel_steady_state_worker(
+    model: Model,
+    p0: dict[str, float],
+    data: pd.Series,
+    y0: dict[str, float] | None,
+    integrator: IntegratorType | None,
+    loss_fn: LossFn,
+    minimize_fn: MinimizeFn,
+    residual_fn: SteadyStateResidualFn,
+) -> FitResult | None:
+    model_pars = model.parameters
+
+    return steady_state(
+        model,
+        p0={k: v for k, v in p0.items() if k in model_pars},
+        y0=y0,
+        data=data,
+        minimize_fn=minimize_fn,
+        residual_fn=residual_fn,
+        integrator=integrator,
+        loss_fn=loss_fn,
+    )
+
+
+def _carousel_time_course_worker(
+    model: Model,
+    p0: dict[str, float],
+    data: pd.DataFrame,
+    y0: dict[str, float] | None,
+    integrator: IntegratorType | None,
+    loss_fn: LossFn,
+    minimize_fn: MinimizeFn,
+    residual_fn: TimeSeriesResidualFn,
+) -> FitResult | None:
+    model_pars = model.parameters
+    return time_course(
+        model,
+        p0={k: v for k, v in p0.items() if k in model_pars},
+        y0=y0,
+        data=data,
+        minimize_fn=minimize_fn,
+        residual_fn=residual_fn,
+        integrator=integrator,
+        loss_fn=loss_fn,
+    )
+
+
+def _carousel_protocol_worker(
+    model: Model,
+    p0: dict[str, float],
+    data: pd.DataFrame,
+    protocol: pd.DataFrame,
+    y0: dict[str, float] | None,
+    integrator: IntegratorType | None,
+    loss_fn: LossFn,
+    minimize_fn: MinimizeFn,
+    residual_fn: ProtocolResidualFn,
+) -> FitResult | None:
+    model_pars = model.parameters
+    return time_course_over_protocol(
+        model,
+        p0={k: v for k, v in p0.items() if k in model_pars},
+        y0=y0,
+        protocol=protocol,
+        data=data,
+        minimize_fn=minimize_fn,
+        residual_fn=residual_fn,
+        integrator=integrator,
+        loss_fn=loss_fn,
+    )
+
+
+def carousel_steady_state(
+    carousel: Carousel,
+    *,
+    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: IntegratorType | None = None,
+    loss_fn: LossFn = rmse,
+) -> CarouselFit:
+    """Fit model parameters to steady-state experimental data over a carousel."""
+    return CarouselFit(
+        [
+            fit
+            for i in parallel.parallelise(
+                partial(
+                    _carousel_steady_state_worker,
+                    p0=p0,
+                    data=data,
+                    y0=y0,
+                    integrator=integrator,
+                    loss_fn=loss_fn,
+                    minimize_fn=minimize_fn,
+                    residual_fn=residual_fn,
+                ),
+                inputs=list(enumerate(carousel.variants)),
+            )
+            if (fit := i[1]) is not None
+        ]
+    )
+
+
+def carousel_time_course(
+    carousel: Carousel,
+    *,
+    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: IntegratorType | None = None,
+    loss_fn: LossFn = rmse,
+) -> CarouselFit:
+    """Fit model parameters to time course of experimental data over a carousel."""
+    return CarouselFit(
+        [
+            fit
+            for i in parallel.parallelise(
+                partial(
+                    _carousel_time_course_worker,
+                    p0=p0,
+                    data=data,
+                    y0=y0,
+                    integrator=integrator,
+                    loss_fn=loss_fn,
+                    minimize_fn=minimize_fn,
+                    residual_fn=residual_fn,
+                ),
+                inputs=list(enumerate(carousel.variants)),
+            )
+            if (fit := i[1]) is not None
+        ]
+    )
+
+
+def carousel_time_course_over_protocol(
+    carousel: Carousel,
+    *,
+    p0: dict[str, float],
+    data: pd.DataFrame,
+    protocol: pd.DataFrame,
+    y0: dict[str, float] | None = None,
+    minimize_fn: MinimizeFn = _default_minimize_fn,
+    residual_fn: ProtocolResidualFn = _protocol_residual,
+    integrator: IntegratorType | None = None,
+    loss_fn: LossFn = rmse,
+) -> CarouselFit:
+    """Fit model parameters to time course of experimental data over a protocol."""
+    return CarouselFit(
+        [
+            fit
+            for i in parallel.parallelise(
+                partial(
+                    _carousel_protocol_worker,
+                    p0=p0,
+                    data=data,
+                    protocol=protocol,
+                    y0=y0,
+                    integrator=integrator,
+                    loss_fn=loss_fn,
+                    minimize_fn=minimize_fn,
+                    residual_fn=residual_fn,
+                ),
+                inputs=list(enumerate(carousel.variants)),
+            )
+            if (fit := i[1]) is not None
+        ]
+    )

mxlpy/fns.py

@@ -2,11 +2,6 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from mxlpy.types import Float
-
 __all__ = [
     "add",
     "constant",
@@ -36,7 +31,7 @@ __all__ = [
 ###############################################################################
 
 
-def constant(x: Float) -> Float:
+def constant(x: float) -> float:
     """Return a constant value regardless of other model components.
 
     Parameters
@@ -58,7 +53,7 @@ def constant(x: Float) -> Float:
     return x
 
 
-def neg(x: Float) -> Float:
+def neg(x: float) -> float:
     """Calculate the negation of a value.
 
     Parameters
@@ -82,7 +77,7 @@ def neg(x: Float) -> Float:
     return -x
 
 
-def minus(x: Float, y: Float) -> Float:
+def minus(x: float, y: float) -> float:
     """Calculate the difference between two values.
 
     Parameters
@@ -108,7 +103,7 @@ def minus(x: Float, y: Float) -> Float:
     return x - y
 
 
-def mul(x: Float, y: Float) -> Float:
+def mul(x: float, y: float) -> float:
     """Calculate the product of two values.
 
     Parameters
@@ -134,7 +129,7 @@ def mul(x: Float, y: Float) -> Float:
     return x * y
 
 
-def div(x: Float, y: Float) -> Float:
+def div(x: float, y: float) -> float:
     """Calculate the quotient of two values.
 
     Parameters
@@ -160,7 +155,7 @@ def div(x: Float, y: Float) -> Float:
     return x / y
 
 
-def one_div(x: Float) -> Float:
+def one_div(x: float) -> float:
     """Calculate the reciprocal of a value.
 
     Parameters
@@ -184,7 +179,7 @@ def one_div(x: Float) -> Float:
     return 1.0 / x
 
 
-def neg_div(x: Float, y: Float) -> Float:
+def neg_div(x: float, y: float) -> float:
     """Calculate the negative quotient of two values.
 
     Parameters
@@ -210,7 +205,7 @@ def neg_div(x: Float, y: Float) -> Float:
     return -x / y
 
 
-def twice(x: Float) -> Float:
+def twice(x: float) -> float:
     """Calculate twice the value.
 
     Parameters
@@ -234,7 +229,7 @@ def twice(x: Float) -> Float:
     return x * 2
 
 
-def add(x: Float, y: Float) -> Float:
+def add(x: float, y: float) -> float:
     """Calculate the sum of two values.
 
     Parameters
@@ -260,7 +255,7 @@ def add(x: Float, y: Float) -> Float:
     return x + y
 
 
-def proportional(x: Float, y: Float) -> Float:
+def proportional(x: float, y: float) -> float:
     """Calculate the product of two values.
 
     Common in mass-action kinetics where x represents a rate constant
@@ -295,9 +290,9 @@ def proportional(x: Float, y: Float) -> Float:
 
 
 def moiety_1s(
-    x: Float,
-    x_total: Float,
-) -> Float:
+    x: float,
+    x_total: float,
+) -> float:
     """Calculate conservation relationship for one substrate.
 
     Used for creating derived variables that represent moiety conservation,
@@ -328,10 +323,10 @@ def moiety_1s(
 
 
 def moiety_2s(
-    x1: Float,
-    x2: Float,
-    x_total: Float,
-) -> Float:
+    x1: float,
+    x2: float,
+    x_total: float,
+) -> float:
     """Calculate conservation relationship for two substrates.
 
     Used for creating derived variables that represent moiety conservation
@@ -369,7 +364,7 @@ def moiety_2s(
 ###############################################################################
 
 
-def mass_action_1s(s1: Float, k: Float) -> Float:
+def mass_action_1s(s1: float, k: float) -> float:
     """Calculate irreversible mass action reaction rate with one substrate.
 
     Rate = k * [S]
@@ -398,7 +393,7 @@ def mass_action_1s(s1: Float, k: Float) -> Float:
     return k * s1
 
 
-def mass_action_1s_1p(s1: Float, p1: Float, kf: Float, kr: Float) -> Float:
+def mass_action_1s_1p(s1: float, p1: float, kf: float, kr: float) -> float:
     """Calculate reversible mass action reaction rate with one substrate and one product.
 
     Rate = kf * [S] - kr * [P]
@@ -432,7 +427,7 @@ def mass_action_1s_1p(s1: Float, p1: Float, kf: Float, kr: Float) -> Float:
     return kf * s1 - kr * p1
 
 
-def mass_action_2s(s1: Float, s2: Float, k: Float) -> Float:
+def mass_action_2s(s1: float, s2: float, k: float) -> float:
     """Calculate irreversible mass action reaction rate with two substrates.
 
     Rate = k * [S1] * [S2]
@@ -463,7 +458,7 @@ def mass_action_2s(s1: Float, s2: Float, k: Float) -> Float:
     return k * s1 * s2
 
 
-def mass_action_2s_1p(s1: Float, s2: Float, p1: Float, kf: Float, kr: Float) -> Float:
+def mass_action_2s_1p(s1: float, s2: float, p1: float, kf: float, kr: float) -> float:
     """Calculate reversible mass action reaction rate with two substrates and one product.
 
     Rate = kf * [S1] * [S2] - kr * [P]
@@ -505,7 +500,7 @@ def mass_action_2s_1p(s1: Float, s2: Float, p1: Float, kf: Float, kr: Float) ->
 ###############################################################################
 
 
-def michaelis_menten_1s(s1: Float, vmax: Float, km1: Float) -> Float:
+def michaelis_menten_1s(s1: float, vmax: float, km1: float) -> float:
     """Calculate irreversible Michaelis-Menten reaction rate for one substrate.
 
     Rate = Vmax * [S] / (Km + [S])
@@ -549,12 +544,12 @@ def michaelis_menten_1s(s1: Float, vmax: Float, km1: Float) -> Float:
 
 
 def michaelis_menten_2s(
-    s1: Float,
-    s2: Float,
-    vmax: Float,
-    km1: Float,
-    km2: Float,
-) -> Float:
+    s1: float,
+    s2: float,
+    vmax: float,
+    km1: float,
+    km2: float,
+) -> float:
     """Calculate Michaelis-Menten reaction rate (ping-pong) for two substrates.
 
     Rate = Vmax * [S1] * [S2] / ([S1]*[S2] + km1*[S2] + km2*[S1])
@@ -594,14 +589,14 @@ def michaelis_menten_2s(
 
 
 def michaelis_menten_3s(
-    s1: Float,
-    s2: Float,
-    s3: Float,
-    vmax: Float,
-    km1: Float,
-    km2: Float,
-    km3: Float,
-) -> Float:
+    s1: float,
+    s2: float,
+    s3: float,
+    vmax: float,
+    km1: float,
+    km2: float,
+    km3: float,
+) -> float:
     """Calculate Michaelis-Menten reaction rate (ping-pong) for three substrates.
 
     Rate = Vmax * [S1] * [S2] * [S3] / ([S1]*[S2] + km1*[S2]*[S3] + km2*[S1]*[S3] + km3*[S1]*[S2])
@@ -649,7 +644,7 @@ def michaelis_menten_3s(
 ###############################################################################
 
 
-def diffusion_1s_1p(inside: Float, outside: Float, k: Float) -> Float:
+def diffusion_1s_1p(inside: float, outside: float, k: float) -> float:
     """Calculate diffusion rate between two compartments.
 
     Rate = k * ([outside] - [inside])

mxlpy/identify.py

@@ -1,6 +1,9 @@
 """Numerical parameter identification estimations."""
 
+from __future__ import annotations
+
 from functools import partial
+from typing import TYPE_CHECKING
 
 import numpy as np
 import pandas as pd
@@ -8,11 +11,15 @@ from tqdm import tqdm
 
 from mxlpy import fit
 from mxlpy.distributions import LogNormal, sample
-from mxlpy.model import Model
 from mxlpy.parallel import parallelise
-from mxlpy.types import Array
 
-__all__ = ["profile_likelihood"]
+if TYPE_CHECKING:
+    from mxlpy.model import Model
+    from mxlpy.types import Array
+
+__all__ = [
+    "profile_likelihood",
+]
 
 
 def _mc_fit_time_course_worker(
@@ -21,16 +28,15 @@ def _mc_fit_time_course_worker(
     data: pd.DataFrame,
     loss_fn: fit.LossFn,
 ) -> float:
-    p_fit = fit.time_course(model=model, p0=p0.to_dict(), data=data)
-    return fit._time_course_residual(  # noqa: SLF001
-        par_values=list(p_fit.values()),
-        par_names=list(p_fit.keys()),
-        data=data,
+    fit_result = fit.time_course(
         model=model,
-        y0=None,
-        integrator=fit.DefaultIntegrator,
+        p0=p0.to_dict(),
+        data=data,
         loss_fn=loss_fn,
     )
+    if fit_result is None:
+        return np.inf
+    return fit_result.loss
 
 
 def profile_likelihood(