Welcome to symbolic-compartmental-model’s documentation!

For installation instructions (for pip, docker, or the command-line interface), please see SCM Installation Guidelines.

Overview

Symbolic Compartmental Model is a python package for constructing, simulating, and fitting compartmental models. It is based on the symbolic calculations package sympy but can also perform numerical calculations.

Current features

  • Defining a CM based on the contributed turnovers (\(\mathbf{M}\)-matrix) and observed pool sizes

  • Optionally include symbolic parameters and set their bounds for later fitting

  • Several fitting functions, including single/multiple pools and mass balance constraints (optional)

  • Both numerical and symbolic outputs for dynamic parameters: age, residence time, decay rate, etc.

  • Plotting of simulated data

Getting started

  • For installing the package in your current python environment, you can simply pip install symbolic-compartmental-model or use one of the other options listed in Software.

  • For all newcomers using the package for the first time, we recommend reading the Introduction to Dynamic Labeling Analysis.

  • When you are ready to start coding, you can check out the examples below or our didactic Coding examples and API Reference pages.

  • The source code can be found on GitLab.

Quick examples

Basic Model Creation:

from symbolic_compartmental_model import SymbolicCompartmentalModel

# Create a 2-state model
cm = SymbolicCompartmentalModel(n_states=2)
cm.contributed_turnovers = [[-0.5, 0], [1.0, -1.0]]
cm.observed_pool_weights = [0.3, 0.7]

# Simulate labeling curve
import numpy as np
t = np.linspace(0, 5, 100)
f_values = cm.f()(t)

Parameter Fitting:

# Add parameters and fit to data
k1 = cm.add_parameter(symbol="k1", lb=0.1, ub=10.0)
k2 = cm.add_parameter(symbol="k2", lb=0.1, ub=10.0)
cm.contributed_turnovers = [[-k1, 0], [k2, -k2]]

# Experimental data
t_data = [1, 2, 3, 4]
y_data = [0.7, 0.4, 0.2, 0.1]

# Fit model
results = cm.fit(t_data, y_data)
print(f"Best fit: k1={results.popt[0]:.3f}, k2={results.popt[1]:.3f}")

Symbolic Analysis:

# Get symbolic expressions
mean_age_expr = cm.as_symbolic("mean_age")
residence_time_expr = cm.as_symbolic("mean_residence_time")

# Plot age distribution
cm.plot("age_pdf", x=[2.0, 1.0])  # With parameters k1=2, k2=1

Indices and tables