Welcome to `pysb-pkpd`'s Documentation

pysb-pkpd: program and simulate dynamic PK/PD and QSP models in Python using the PySB modeling framework

Overview

pysb-pkpd is a domain-specific extension to the PySB modeling framework that facilitates programming and simulating dynamic pharmacokinetic/pharmacodynamic (PK/PD) and quantitative systems pharmacology (QSP) models in Python.

Key Features

pysb-pkpd has the following key features:

Domain-specific PySB macros - set of domain-specific PySB macros that facilitate the efficient and descriptive programmatic construction of compartmental PK/PD models.
Standard one-, two-, and three-compartment model generators - functions to quickly and easily construct standard one-, two-, and three-compartment PK/PD models.

Why Use `pysb-pkpd`?

Built on PySB, a powerful programmatic and rule-based framework for biochemical modeling, pysb-pkpd offers a variety of benefits, including:

Programmatic Modeling – Enables automated workflows, reproducibility (e.g., version control and automated testing), customization, and creation of reusable functions for pharmacological and biochemical processes.
Built-in Support for Mechanistic Modeling – Leverage PySB's mechanistic modeling framework to incorporate additional biochemical mechanisms and build customized mechanistic PK/PD and QSP/QST models.
Rule-Based Approach – Encode complex pharmacological and biochemical processes using intuitive rule-based modeling. No need to enumerate all reactions/molecular species or manually encode the corresponding network of differential equations.
Python-Based – Seamlessly integrates with Python’s scientific computing ecosystem, supporting advanced simulations, data analysis, and visualization.
Arbitrary Number of Compartments – Specify any number of compartments to build custom multi-compartment models, including complex drug distribution and physiologically-based pharmacokinetic (PBPK) models.

Installation

Install PySB using conda or mamba:

conda install -c alubbock pysb

OR

mamba install -c alubbock pysb

Install pysb-pkpd with pip:
```
pip install pysb-pkpd
```
Ensure you have Python 3.11.3+ and PySB 1.15.0+ installed.

Quick-start Example

1. Using model generator function (quick and easy standard model construction)

Here’s a simple workflow to define and simulate a one-compartment PK model with an Emax PD function using the model generator functions:

from pysb.pkpd import standard, util

# Define a simple one-compartment model
model = standard.one_compartment_model(dose_amount=100,
                                       dose_route='iv-bolus',
                                       volume_distribution=10.,
                                       clearance=0.5,
                                       pd_model={'emax':
                                           {'emax':2.2,
                                            'ec50': 225.8}
                                       }
                                       )
# Simulate concentration over time
simulation_results = util.simulate(model, 
                                   tspan=list(range(100)),
                                  )

2. Using PK/PD model macros (flexible and customizable programmatic model definition)

Here’s a simple workflow to define and simulate the same one-compartment PK model with an Emax PD function (same as above) using the PK/PD macros inside a model module file:

Define model.py with the following code (the model is a Python module in this case):

from pysb import Model
import pysb.pkpd as pkpd

# Initialize the PySB model:
Model()

# Add a Monomer for the drug:
pkpd.drug_monomer(name='Drug')

# Add the compartment for a one-compartment model:
pkpd.one_compartment(c1_name="CENTRAL",
                             c1_size=10.)

# Add a dose of the drug using an 
# instantaneous 'bolus' dose in the central
# compartment (initial amount of drug at time zero).
#   Note that dose is an amount such as weight, mass, or moles,
#     which will be converted automatically to an initial concentration
#     as: 
#         [Drug]_0 = dose / V_CENTRAL , 
#     where V_CENTRAL is the size (i.e., volume) of the central compartment.
pkpd.dose_bolus(Drug, CENTRAL, dose=100.)

# Include (linear) systemic clearance of Drug from the central compartment.
pkpd.clearance(Drug, CENTRAL, cl=0.5)

# Add the Emax PD function for Drug in the
# central compartment:
pkpd.emax(Drug, CENTRAL, emax=2.2,
                         ec50=225.8)

Import and simulate the model:

from model import model
from pysb.pkpd import util

# Simulate concentration over time
simulation_results = util.simulate(model, 
                                   tspan=list(range(100)),
                                  )

Acknowledgements

Special thanks for Martin Breuss's MkDocs tuorial.

Welcome to pysb-pkpd's Documentation