mxlpy 0.16.0__py3-none-any.whl → 0.18.0__py3-none-any.whl

mxlpy/__init__.py

@@ -48,6 +48,7 @@ from . import (
     fns,
     mc,
     mca,
+    npe,
     plot,
     report,
     sbml,
@@ -66,7 +67,7 @@ from .scan import (
 )
 from .simulator import Simulator
 from .symbolic import SymbolicModel, to_symbolic_model
-from .types import Derived, IntegratorProtocol
+from .types import Derived, IntegratorProtocol, unwrap
 
 with contextlib.suppress(ImportError):
     from .integrators import Assimulo
@@ -95,6 +96,7 @@ __all__ = [
     "make_protocol",
     "mc",
     "mca",
+    "npe",
     "plot",
     "report",
     "sbml",
@@ -104,6 +106,7 @@ __all__ = [
     "time_course",
     "time_course_over_protocol",
     "to_symbolic_model",
+    "unwrap",
 ]
 
 

mxlpy/fit.py

@@ -28,12 +28,16 @@ from mxlpy.types import (
 
 __all__ = [
     "InitialGuess",
+    "LossFn",
     "MinimizeFn",
+    "ProtocolResidualFn",
     "ResidualFn",
     "SteadyStateResidualFn",
     "TimeSeriesResidualFn",
+    "rmse",
     "steady_state",
     "time_course",
+    "time_course_over_protocol",
 ]
 
 if TYPE_CHECKING:
@@ -44,6 +48,21 @@ if TYPE_CHECKING:
 type InitialGuess = dict[str, float]
 type ResidualFn = Callable[[Array], float]
 type MinimizeFn = Callable[[ResidualFn, InitialGuess], dict[str, float]]
+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))))
 
 
 class SteadyStateResidualFn(Protocol):
@@ -58,6 +77,7 @@ class SteadyStateResidualFn(Protocol):
         model: Model,
         y0: dict[str, float],
         integrator: IntegratorType,
+        loss_fn: LossFn,
     ) -> float:
         """Calculate residual error between model steady state and experimental data."""
         ...
@@ -75,6 +95,27 @@ class TimeSeriesResidualFn(Protocol):
         model: Model,
         y0: dict[str, float],
         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."""
+
+    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: IntegratorType,
+        loss_fn: LossFn,
+        protocol: pd.DataFrame,
+        time_points_per_step: int = 10,
     ) -> float:
         """Calculate residual error between model time course and experimental data."""
         ...
@@ -109,6 +150,7 @@ def _steady_state_residual(
     model: Model,
     y0: dict[str, float] | None,
     integrator: IntegratorType,
+    loss_fn: LossFn,
 ) -> float:
     """Calculate residual error between model steady state and experimental data.
 
@@ -119,6 +161,7 @@ def _steady_state_residual(
         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
@@ -143,9 +186,11 @@ def _steady_state_residual(
     )
     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))))
+
+    return loss_fn(
+        res.get_combined().loc[:, cast(list, data.index)],
+        data,
+    )
 
 
 def _time_course_residual(
@@ -156,6 +201,53 @@ def _time_course_residual(
     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_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,
+    time_points_per_step: int = 10,
 ) -> float:
     """Calculate residual error between model time course and experimental data.
 
@@ -166,6 +258,9 @@ def _time_course_residual(
         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
 
     Returns:
         float: Root mean square error between model and data
@@ -177,14 +272,20 @@ def _time_course_residual(
             y0=y0,
             integrator=integrator,
         )
-        .simulate_time_course(data.index)  # type: ignore
+        .simulate_over_protocol(
+            protocol=protocol,
+            time_points_per_step=time_points_per_step,
+        )
         .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))))
+
+    return loss_fn(
+        results_ss.loc[:, cast(list, data.columns)],
+        data,
+    )
 
 
 def steady_state(
@@ -195,6 +296,7 @@ def steady_state(
     minimize_fn: MinimizeFn = _default_minimize_fn,
     residual_fn: SteadyStateResidualFn = _steady_state_residual,
     integrator: IntegratorType = DefaultIntegrator,
+    loss_fn: LossFn = rmse,
 ) -> dict[str, float]:
     """Fit model parameters to steady-state experimental data.
 
@@ -210,6 +312,7 @@ def steady_state(
         minimize_fn: 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
 
     Returns:
         dict[str, float]: Fitted parameters as {parameter_name: fitted_value}
@@ -232,6 +335,7 @@ def steady_state(
             y0=y0,
             par_names=par_names,
             integrator=integrator,
+            loss_fn=loss_fn,
         ),
     )
     res = minimize_fn(fn, p0)
@@ -249,6 +353,62 @@ def time_course(
     minimize_fn: MinimizeFn = _default_minimize_fn,
     residual_fn: TimeSeriesResidualFn = _time_course_residual,
     integrator: IntegratorType = DefaultIntegrator,
+    loss_fn: LossFn = rmse,
+) -> 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
+        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
+        loss_fn: Loss function to use for residual calculation
+
+    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,
+            loss_fn=loss_fn,
+        ),
+    )
+    res = minimize_fn(fn, p0)
+    model.update_parameters(p_orig)
+    return res
+
+
+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,
+    loss_fn: LossFn = rmse,
+    time_points_per_step: int = 10,
 ) -> dict[str, float]:
     """Fit model parameters to time course of experimental data.
 
@@ -258,12 +418,15 @@ def time_course(
 
     Args:
         model: Model instance to fit
-        data: Experimental time course data as pandas DataFrame
         p0: Initial parameter guesses as {parameter_name: value}
+        data: Experimental time course data
+        protocol: Experimental protocol
         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
+        loss_fn: Loss function to use for residual calculation
+        time_points_per_step: Number of time points per step in the protocol
 
     Returns:
         dict[str, float]: Fitted parameters as {parameter_name: fitted_value}
@@ -284,6 +447,9 @@ def time_course(
             y0=y0,
             par_names=par_names,
             integrator=integrator,
+            loss_fn=loss_fn,
+            protocol=protocol,
+            time_points_per_step=time_points_per_step,
         ),
     )
     res = minimize_fn(fn, p0)