blakeaw/pysb-pkpd

PySB add-on providing domain-specific macros and models for empirical and mechanistic PK/PD modeling.

pysb-pkpd

pysb-pkpd is an add-on for the PySB modeling framework that provides domain-specific macros and pre-constructed models for compartmental and mechanistic PK/PD modeling. pysb-pkpd could also be used in conjuction with core PySB features to help build and execute quantitative systems pharmacology/toxicology (QSP/QST) models.

Table of Contents

1. Install
   1. Dependencies
   2. pip install
   3. Manual install
2. License
3. Change Log
4. Documentation and Usage
   1. Quick Overview
   2. Example
   3. List of macros
   4. Preconstructed models
5. Contact
6. Citing
7. Other Useful Tools

---

Install

! Note
psyb-pkpd is still in version zero development so new versions may not be backwards compatible.

pysb-pkpd installs as the pysb.pkpd Python (namespace) package. It is has been developed with Python 3.11.3 and PySB 1.15.0.

Dependencies

Note that pysb-pkpd has the following core dependencies:

• PySB - developed using PySB version 1.15.0

pip install

You can install pysb-pkpd version 0.2.1 with pip sourced from the GitHub repo:

with git installed:

Fresh install:

pip install git+https://github.com/blakeaw/[email protected]

Or to upgrade from an older version:

pip install --upgrade git+https://github.com/blakeaw/[email protected]

without git installed:

Fresh install:

pip install https://github.com/blakeaw/pysb-pkpd/archive/refs/tags/v0.2.1.zip

Or to upgrade from an older version:

pip install --upgrade https://github.com/blakeaw/pysb-pkpd/archive/refs/tags/v0.2.1.zip

Manual install

First, download the repository. Then from the pysb-pkpd folder/directory run

pip install .

---

License

This project is licensed under the BSD 2-Clause License - see the LICENSE file for details

---

Change Log

See: CHANGELOG

---

Documentation and Usage

Quick Overview

The key feature of pysb-pkpd is a set of domain specific PySB macros for PK/PD modeling that can be used to programatically construct models in Python via the PySB framework:

Example

Building a two-compartment PK model with a sigmoidal Emax PD function:

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 compartments for a two-compartment model:
pkpd.two_compartments(c1_name="CENTRAL",
                             c1_size=2.0,
                             c2_name="PERIPHERAL",
                             c2_size=1.0)


# 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.)

# Add (1st order) distribution and re-distribution between the 
# central and peripheral compartments:
#    Note that klist is [k_distribute, k_redistribute]
pkpd.distribute(Drug, CENTRAL, PERIPHERAL, klist=[1.0, 1e-1])

# Include linear elimination of Drug from the central compartment 
# by processes like metabolism and renal excretion.
pkpd.eliminate(Drug, CENTRAL, kel=1e-2)

# Add the sigmoidal Emax PD function for Drug in the
# central compartment:
pkpd.sigmoidal_emax(Drug, CENTRAL, emax=1.,
                                   ec50=10.,
                                   n=1.7)
               

PKRO Example

See this notebook for another example using PySB with the psyb-pkpd add-on to build a simple semi-mechanistic pharmacokinetic and receptor occupancy (PKRO) model.

List of macros

The pysb.pkpd.macros module currently defines the following macros encoding PK, PD, and dosing functions:

PK functions:

• drug_monomer - adds a simple monomer species for the drug to the model. If the drug needs binding sites or other state variables then you should directly use the PySB Monomer class instead.
• one_compartment - adds one compartment to the model for a one-comaprtment PK model. Alternatively, it could be used to add a new compartment to a multi-compartment model.
• two_compartments - adds two compartments to the model for a two-comaprtment PK model.
• three_compartments - adds three compartments to the model for a three-compartment PK model.
• eliminate - adds linear (1st-order) elimination of the specified drug/species from a compartment.
• eliminate_mm - add non-linear, Michaelis-Menten, elimination of the specified drug/species from a compartment.
• clearance - adds linear (1st-order) elimination of the specified drug/species from a compartment by systemic clearance.
• distribute - adds distribution/redistribution of the specified drug/species between two compartments.
• transfer - adds one-way transfer (distribution with no redistribution) of the specified drug/species from one compartment to another.

PD functions:

• emax - Adds an Emax model expression for the specified drug/species in a given compartment. Generates a PySB Expression with name: 'Emax_expr_DrugName_CompartmentName'
• sigmoidal_emax - Adds a sigmoidal Emax model expression for the specified drug/species in a given compartment. Generates a PySB Expression with name: 'Emax_expr_DrugName_CompartmentName'
• linear_effect - Adds a linear effect model expression for the specified drug/specis in a given compartment. Generates a PySB Expression with name: 'LinearEffect_expr_DrugName_CompartmentName'

Dosing functions:

• dose_bolus - adds an instantaneous bolus dose of the specified drug/species which defines the initial concentration at time zero; e.g., to model IV bolus.
• dose_infusion - adds a continous (zero-order) infusion of the specified drug/species; e.g., to model continuous IV infusion.
• dose_absorbed - adds a dose of the specified drug which is absorbed into the specified compartment via first-order kinetics, including a bioavailibity factor; e.g., to model oral dosing or a subcutaneous depot.

Preconstructed models

Another feature of pysb-pkpd are a limited set of pre-constructed two-compartment and three-compartment models which can be used for empirical fitting of PK data or as base models for more complex semi-mechanistic PK/PD mdoels.

PK/PD models

Two-compartment and three-compartment PK models with Emax PD function for the drug in the central compartment:

from pysb.pkpd.models import twocomp_emax, threecomp_emax

PK-only models

Two-compartment and three-compartment PK models:

from pysb.pkpd.pk_models import twocomp, threecomp

---

Contact

Please open a GitHub Issue to report any problems/bugs or make any comments, suggestions, or feature requests.

---

Citing

If this package is useful in your work, please cite this GitHub repo: https://github.com/blakeaw/pysb-pkpd

---

Other Useful Tools

Parameter estimation

Please see packages such as simplePSO, PyDREAM, Gleipnir, or GAlibrate for tools to do PySB model parameter estimation using stochastic optimization or Bayesian Monte Carlo approaches.

PD response models

If you want to separately fit response data independetly of PK data, then the pharmacodynamic-response-models package may also be useful.

PySB model visualization

pyvipr can be used for static and dynamic PySB model visualizations.

---

pysb-pkpd's Issues

Compartmental model schematic generator

It may be nice to implement a function that can parse a model and generate a compartmental model schematic like that in https://github.com/blakeaw/pysb-pkpd/blob/main/example-notebooks/1_simple-PKRO.ipynb.

Although there are some existing tools in PySB to render reactions and species visualization (https://pysb.readthedocs.io/en/stable/modules/tools/render.html), as well as other tools like pyvipr, it might be nice to have something more PK/PD focused and generate the type of schematic used more commonly to show one-, two-, and three-compartment models with the dosing, PK processes, and PD function: similar to the one in https://github.com/blakeaw/pysb-pkpd/blob/main/example-notebooks/1_simple-PKRO.ipynb.

Maybe something that directly renders a schematic as a matplotlib graph? That should at least make it easy to use in notebooks.

Make the macros module into a subpackage

Maybe it would be cleaner or easier to understand if the macros were organized into their own type-specific modules. Something like macros.pk, macros.pd, and macros.dose for PK, PD, and dosing functions respectively.

In this case, the current macros module under pysb.pkpd.macros would be converted into a sub-package. The modules inside that sub-package could then be imported in the pkpd level __init__.py to give a shortcut where they could be imported like from pysb.pkpd import pk, pd, dose. Then users could call those like pk.clearance(...), pd.emax(...), or dose.bolus(...) when building their own model, which may make it more readable and easier to differentiate the PD and dose functions from the PK ones.

Function to abstract setting up and running the ScipyOdeSimulator with PK/PD models

I think in typical cases the PK/PD models will be executed using ODEs. Therefore, a default function, such as simulate or run_model, that abstracts setting up and pulling results from PySB's ScipyOdeSimulator might be useful.

Instead of having to do something like:

sim = ScipyOdeSimulator(model)
simres = sim.run(tspan=tspan)
simtraj = simres.all

You could just do something like:

simtraj = pkpd.simulate(model, tspan)

Idea: Auto fitting functionality/parameter estimation

It might be nice if the package included/added some functionality to abstract away fitting a PK/PD model to data and estimate the associated model parameters. Maybe something akin to the sklearn style .fit function where you could call something like model.fit(observable, data) and the PK/PD model would train to fit the data.

Baseline effect for the linear effect model macro

Consider adding the option to specify a baseline effect $E_0$ (i.e., intercept) for the linear_effect PD macro.

Problem with the dose_absorbed macro.

I'm pretty sure the current version of the dose_absorbed macro doesn't work as expected, particularly when there are other processes that affect the free drug concentration. As is, the generated rule would add or remove drug in a way that the model would have a steady-state around the given dose.

I think a better way to handle this is probably to create a pre-cursor monomer and then have a first-order reaction that converts the pre-cursor to free drug in the designated compartment.

Units module to help standardize the units

I think it could be helpful to implement a units module similar to the one in PARM: https://github.com/NTBEL/PARM/blob/main/parm/units.py

This could be used to define a standard set of units that could be applied to quantities similar to the way NEURON rxd handles units. This should help users keep up with the units a little easier and would help with consistent conversion to pre-defined set of units.

PD macro for the Log-linear effect model

Add a new macro for the log-linear effect PD model:
$E = m \times log(C) + b$
for drug concentration $C$.

PD macro encoding a Fixed-effect model

Add a new macro for the fixed-effect PD model:
$E = E_{fixed}$ , $C < C_{threshold}$
$E = 0$, $C < C_{threshold}$
for drug concentration $C$.

Way to simulate multiple doses

I think it would be nice to have a feature that facilitates executing simulations with multiple doses over time (i.e., dosage).

Implementation ideas

i. One way to do this might be to wrap a PySB simulator, such as the ScipyOdeSimulator, and have the dosage simulator execute multiple runs of the simulator and then stitch together the multiple trajectories; for each run, you would adjust the initials/parameters to implement another dose.

ii. I guess it might also be possible to use complex Expression(s) to implement a dosage macro that periodically adjusts the drug concentration during the simulation to implement multiple dosages.