mgrowthctrl

A Python package for parameter inference, mechanistic microbiome modeling, and control, based on a consumer–resource model (CRM).

Detailed documentation is available at Documentation.

Key features of mgrowthctrl include:

• An API for defining and simulating ODE-based microbiome dynamics.
• A data loader that allows users to retrieve data from mGrowthDB.
• A parameter estimation backend offering both least-squares and Markov Chain Monte Carlo (MCMC) optimization.
• Built-in visualization utilities for evaluating trajectories and analyzing posteriors.
• A controller framework based on neural ODEs.
• A modular architecture designed to facilitate the extension and integration of custom models, controllers, and data processing workflows.

Features

Models

• An implementation of a CRM (CRModel).
• Scalable design supporting both single-species and multi-species systems.
• A unified engine (BaseODEModel) with NumPy and PyTorch backends.
• Extensible base classes enabling straightforward implementation of custom ODE models.

Controllers

• BaseController provides an abstract interface with simulate and fit methods.
• OpenLoopNeuralController implements time-dependent control functions.
• ClosedLoopNeuralController implements state-dependent control functions.

Fitting Backend

• Least-squares parameter optimization (crm_fit_mechanistic).
• Bayesian parameter inference through MCMC sampling (crm_fit_mcmc).

Plotting

• Tools for visualizing coupled metabolite and species population dynamics.
• Plots of empirical data, spline interpolations, and simulated trajectories.
• Integration of MCMC outputs to show credible intervals.

Code Structure

src/mgrowthctrl/
│
├── backends/
│   ├── array.py        # Array backend interfaces for NumPy and PyTorch
│   └── __init__.py
│
├── controllers/
│   ├── base.py         # BaseController interface with simulate and fit methods
│   ├── closed_loop.py  # ClosedLoopNeuralController
│   └── open_loop.py    # OpenLoopNeuralController
│
├── models/
│   ├── base.py         # ODE base class (uses dependency injection)
│   └── crm/
│       ├── fit.py      # LSQ + MCMC fitting engine
│       ├── model.py    # Mechanistic CRM using BaseODEModel
│       └── utils.py    # Shared utilities
│
├── utils/
│   ├── data.py         # Data loading functions with a public DataLoader-style API
│   ├── plot.py         # Plotting utilities
│   ├── save.py         # Saving / loading utilities
│   └── __init__.py
│
└── __init__.py