mxlpy 0.8.0__py3-none-any.whl

mxlpy/__init__.py

@@ -0,0 +1,165 @@
+"""mxlpy: A Python Package for Metabolic Modeling and Analysis.
+
+This package provides tools for creating, simulating and analyzing metabolic models
+with features including:
+
+Key Features:
+    - Model creation and manipulation
+    - Steady state and time-series simulations
+    - Parameter fitting and optimization
+    - Monte Carlo analysis
+    - Metabolic Control Analysis (MCA)
+    - SBML import/export support
+    - Visualization tools
+
+Core Components:
+    Model: Core class for metabolic model representation
+    Simulator: Handles model simulation and integration
+    DefaultIntegrator: Standard ODE solver implementation
+    LabelMapper: Maps between model components and labels
+    Cache: Performance optimization through result caching
+
+Simulation Features:
+    - Steady state calculations
+    - Time course simulations
+    - Parameter scanning
+    - Surrogate modeling with PyTorch
+
+Analysis Tools:
+    - Parameter fitting to experimental data
+    - Monte Carlo methods for uncertainty analysis
+    - Metabolic Control Analysis
+    - Custom visualization functions
+
+"""
+
+from __future__ import annotations
+
+import contextlib
+import itertools as it
+from typing import TYPE_CHECKING
+
+import pandas as pd
+
+from . import (
+    distributions,
+    experimental,
+    fit,
+    fns,
+    mc,
+    mca,
+    plot,
+    sbml,
+    surrogates,
+)
+from .integrators import DefaultIntegrator, Scipy
+from .label_map import LabelMapper
+from .linear_label_map import LinearLabelMapper
+from .mc import Cache
+from .model import Model
+from .nn import _torch
+from .scan import (
+    steady_state,
+    time_course,
+    time_course_over_protocol,
+)
+from .simulator import Simulator
+from .symbolic import SymbolicModel, to_symbolic_model
+from .types import Derived, IntegratorProtocol
+
+with contextlib.suppress(ImportError):
+    from .integrators import Assimulo
+
+if TYPE_CHECKING:
+    from mxlpy.types import ArrayLike
+
+__all__ = [
+    "Assimulo",
+    "Cache",
+    "DefaultIntegrator",
+    "Derived",
+    "IntegratorProtocol",
+    "LabelMapper",
+    "LinearLabelMapper",
+    "Model",
+    "Scipy",
+    "Simulator",
+    "SymbolicModel",
+    "_torch",
+    "cartesian_product",
+    "distributions",
+    "experimental",
+    "fit",
+    "fns",
+    "make_protocol",
+    "mc",
+    "mca",
+    "plot",
+    "sbml",
+    "steady_state",
+    "surrogates",
+    "symbolic",
+    "time_course",
+    "time_course_over_protocol",
+    "to_symbolic_model",
+]
+
+
+def cartesian_product(parameters: dict[str, ArrayLike]) -> pd.DataFrame:
+    """Generate a cartesian product of the parameter values.
+
+    Args:
+        parameters: Dictionary containing parameter names and values.
+
+    Returns:
+        pd.DataFrame: DataFrame containing the cartesian product of the parameter values.
+
+    """
+    return pd.DataFrame(
+        it.product(*parameters.values()),
+        columns=list(parameters),
+    )
+
+
+def make_protocol(steps: list[tuple[float, dict[str, float]]]) -> pd.DataFrame:
+    """Create protocol DataFrame from a dictionary of steps.
+
+    Arguments:
+        steps: dictionary of steps, where each key is the duration of
+               the step in seconds and the value is a dictionary of all
+               parameter values during that step.
+
+    Examples:
+        >>> make_protocol([
+        ...     (1, {"k1": 1.0}),
+        ...     (2, {"k1": 2.0}),
+        ...     (3, {"k1": 1.0}),
+        ... ])
+
+        | Timedelta       |   k1 |
+        |:----------------|-----:|
+        | 0 days 00:00:01 |  1.0 |
+        | 0 days 00:00:03 |  2.0 |
+        | 0 days 00:00:06 |  1.0 |
+
+        >>> make_protocol([
+        ...     (1, {"k1": 1.0, "k2": 2.0}),
+        ...     (2, {"k1": 2.0, "k2": 3.0}),
+        ...     (3, {"k1": 1.0, "k2": 2.0}),
+        ... ])
+
+        | Timedelta       |   k1 |   k2 |
+        |:----------------|-----:|-----:|
+        | 0 days 00:00:01 |    1 |    2 |
+        | 0 days 00:00:03 |    2 |    3 |
+        | 0 days 00:00:06 |    1 |    2 |
+
+    """
+    data = {}
+    t0 = pd.Timedelta(0)
+    for step, pars in steps:
+        t0 += pd.Timedelta(seconds=step)
+        data[t0] = pars
+    protocol = pd.DataFrame(data).T
+    protocol.index.name = "Timedelta"
+    return protocol

mxlpy/distributions.py

@@ -0,0 +1,339 @@
+"""Probability Distribution Classes for Parameter Sampling.
+
+This module provides a collection of probability distributions used for parameter sampling
+in metabolic modeling and Monte Carlo simulations.
+
+Classes:
+    Distribution (Protocol): Base protocol for all distribution classes
+    Beta: Beta distribution for parameters bounded between 0 and 1
+    Uniform: Uniform distribution for parameters with simple bounds
+    LogUniform: LogUniform distribution for parameters with simple bounds
+    Normal: Normal (Gaussian) distribution for unbounded parameters
+    LogNormal: Log-normal distribution for strictly positive parameters
+    Skewnorm: Skewed normal distribution for asymmetric parameter distributions
+
+Each distribution class provides:
+    - Consistent interface through the sample() method
+    - Optional random number generator (RNG) control
+    - Reproducible results via seed parameter
+
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, cast
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+
+from mxlpy.plot import Axes, FigAx, _default_fig_ax
+from mxlpy.types import Array
+
+__all__ = [
+    "Beta",
+    "Distribution",
+    "GaussianKde",
+    "LogNormal",
+    "LogUniform",
+    "Normal",
+    "RNG",
+    "Skewnorm",
+    "Uniform",
+    "sample",
+]
+
+RNG = np.random.default_rng(seed=42)
+
+
+class Distribution(Protocol):
+    """Protocol defining interface for distribution classes.
+
+    All distribution classes must implement the sample() method.
+    """
+
+    def sample(
+        self,
+        num: int,
+        rng: np.random.Generator | None = None,
+    ) -> Array:
+        """Generate random samples from the distribution.
+
+        Args:
+            num: Number of samples to generate
+            rng: Random number generator
+
+        Returns:
+            Array of random samples
+
+        """
+        ...
+
+
+@dataclass
+class Beta:
+    """Beta distribution for parameters bounded between 0 and 1.
+
+    Args:
+        a: Alpha shape parameter (>0)
+        b: Beta shape parameter (>0)
+
+    """
+
+    a: float
+    b: float
+
+    def sample(self, num: int, rng: np.random.Generator | None = None) -> Array:
+        """Generate random samples from the beta distribution.
+
+        Args:
+            num: Number of samples to generate
+            rng: Random number generator
+
+        """
+        if rng is None:
+            rng = RNG
+        return rng.beta(self.a, self.b, num)
+
+
+@dataclass
+class Uniform:
+    """Uniform distribution for parameters with simple bounds.
+
+    Args:
+        lower_bound: Minimum value
+        upper_bound: Maximum value
+
+    """
+
+    lower_bound: float
+    upper_bound: float
+
+    def sample(self, num: int, rng: np.random.Generator | None = None) -> Array:
+        """Generate random samples from the uniform distribution.
+
+        Args:
+            num: Number of samples to generate
+            rng: Random number generator
+
+        """
+        if rng is None:
+            rng = RNG
+        return rng.uniform(self.lower_bound, self.upper_bound, num)
+
+
+@dataclass
+class LogUniform:
+    """LogUniform distribution for parameters with simple bounds.
+
+    Args:
+        lower_bound: Minimum value
+        upper_bound: Maximum value
+
+    """
+
+    lower_bound: float
+    upper_bound: float
+
+    def sample(self, num: int, rng: np.random.Generator | None = None) -> Array:
+        """Generate random samples from the loguniform distribution.
+
+        Args:
+            num: Number of samples to generate
+            rng: Random number generator
+
+        """
+        if rng is None:
+            rng = RNG
+        return cast(
+            Array,
+            stats.loguniform.rvs(
+                self.lower_bound, self.upper_bound, size=num, random_state=rng
+            ),
+        )
+
+
+@dataclass
+class Normal:
+    """Normal (Gaussian) distribution for unbounded parameters.
+
+    Args:
+        loc: Mean of the distribution
+        scale: Standard deviation
+
+    """
+
+    loc: float
+    scale: float
+
+    def sample(self, num: int, rng: np.random.Generator | None = None) -> Array:
+        """Generate random samples from the normal distribution.
+
+        Args:
+            num: Number of samples to generate
+            rng: Random number generator
+
+        """
+        if rng is None:
+            rng = RNG
+        return rng.normal(self.loc, self.scale, num)
+
+
+@dataclass
+class LogNormal:
+    """Log-normal distribution for strictly positive parameters.
+
+    Args:
+        mean: Mean of the underlying normal distribution
+        sigma: Standard deviation of the underlying normal distribution
+        seed: Random seed for reproducibility
+
+    """
+
+    mean: float
+    sigma: float
+
+    def sample(self, num: int, rng: np.random.Generator | None = None) -> Array:
+        """Generate random samples from the log-normal distribution.
+
+        Args:
+            num: Number of samples to generate
+            rng: Random number generator
+
+        """
+        if rng is None:
+            rng = RNG
+        return rng.lognormal(self.mean, self.sigma, num)
+
+
+@dataclass
+class Skewnorm:
+    """Skewed normal distribution for asymmetric parameter distributions.
+
+    Args:
+        loc: Mean of the distribution
+        scale: Standard deviation
+        a: Skewness parameter
+
+    """
+
+    loc: float
+    scale: float
+    a: float
+
+    def sample(
+        self,
+        num: int,
+        rng: np.random.Generator | None = None,  # noqa: ARG002
+    ) -> Array:
+        """Generate random samples from the skewed normal distribution.
+
+        Args:
+            num: Number of samples to generate
+            rng: The random generator argument is unused but required for API compatibility
+
+        """
+        return cast(
+            Array, stats.skewnorm(self.a, loc=self.loc, scale=self.scale).rvs(num)
+        )
+
+
+@dataclass
+class GaussianKde:
+    """Representation of a kernel-density estimate using Gaussian kernels.
+
+    Args:
+        mean: Mean of the underlying normal distribution
+        sigma: Standard deviation of the underlying normal distribution
+        seed: Random seed for reproducibility
+
+    """
+
+    kde: stats.gaussian_kde
+
+    @classmethod
+    def from_data(cls, data: Array | pd.Series) -> GaussianKde:
+        """Create a GaussianKde object from a data array.
+
+        Args:
+            data: Array of data points
+
+        """
+        return cls(stats.gaussian_kde(data))
+
+    def plot(
+        self,
+        xmin: float,
+        xmax: float,
+        n: int = 1000,
+        ax: Axes | None = None,
+    ) -> FigAx:
+        """Plot the kernel-density estimate."""
+        fig, ax = _default_fig_ax(ax=ax, grid=True, figsize=(5, 3))
+
+        x = np.geomspace(xmin, xmax, n)
+        y = self.kde(x)
+        ax.set_xlim(xmin, xmax)
+        ax.set_xscale("log")
+        ax.fill_between(x, y, alpha=0.2)
+        ax.plot(x, y)
+        ax.grid(visible=True)
+        ax.set_frame_on(False)
+        return fig, ax
+
+    def sample(
+        self,
+        num: int,
+        rng: np.random.Generator | None = None,  # noqa: ARG002
+    ) -> Array:
+        """Generate random samples from the kde.
+
+        Args:
+            num: Number of samples to generate
+            rng: Random number generator. Unused but required for API compatibility
+
+        """
+        return cast(Array, self.kde.resample(num)[0])
+
+
+def sample(
+    parameters: dict[str, Distribution],
+    n: int,
+    rng: np.random.Generator | None = None,
+) -> pd.DataFrame:
+    """Generate samples from the specified distributions.
+
+    Examples:
+        >>> sample({"beta": Beta(a=1.0, b=1.0),
+        ...         "uniform": Uniform(lower_bound=0.0, upper_bound=1.0),
+        ...         "normal": Normal(loc=1.0, scale=0.1),
+        ...         "log_normal": LogNormal(mean=1.0, sigma=0.1),
+        ...         "skewnorm": Skewnorm(loc=1.0, scale=0.1, a=5.0),},
+        ...         n=2,)
+                   beta   uniform    normal  log_normal  skewnorm
+            0  0.253043  0.682496  1.067891    2.798020  1.216259
+            1  0.573357  0.139752  1.006758    2.895416  1.129373
+
+    Args:
+        parameters: Dictionary mapping parameter names to distribution objects.
+        n: Number of samples to generate.
+        rng: Random number generator.
+
+    Returns: DataFrame containing the generated samples.
+
+    """
+    return pd.DataFrame({k: v.sample(n, rng) for k, v in parameters.items()})
+
+
+if __name__ == "__main__":
+    _ = sample(
+        {
+            "beta": Beta(a=1.0, b=1.0),
+            "uniform": Uniform(lower_bound=0.0, upper_bound=1.0),
+            "normal": Normal(loc=1.0, scale=0.1),
+            "log_normal": LogNormal(mean=1.0, sigma=0.1),
+            "skewnorm": Skewnorm(loc=1.0, scale=0.1, a=5.0),
+        },
+        n=1,
+    )

mxlpy/experimental/__init__.py

@@ -0,0 +1,12 @@
+"""Experimental features for mxlpy.
+
+APIs should be considered unstable and may change without notice.
+"""
+
+from __future__ import annotations
+
+from .diff import model_diff
+
+__all__ = [
+    "model_diff",
+]