Welcome to the PK Model documentation!

We hope that you will find this page helpful as you learn to use the PKModel library! You can use the functions we provided to specify, solve, and visualise the absorption, distribution, metabolism and clearance of a drug. The body is here modelled as a group of homogeneous compartments.

Below you can find documentation on all the methods and functions you might want to use:

  • The Model class lets you specify the parameters of your pharmacokinetic model, for example the volumes and clearance rates of the central and peripheral compartments.

  • The Protocol class lets you define how the drug is administered, the size of the initial dose and the time span over which to simulate the metabolism of the drug.

  • The Solution Class allows you to solve the model using a SciPy ODE solver and visualise the amount of the drug in the central compartment over time using MatPlotLib.

Join our GitHub Repo to work with us on this library!

Contents

Documentation

class pkmodel.model.Model(delivery_mode: str, V_c=1.0, CL=1.0, Ka=1.0)

The Model class holds the pharmacokinetic parameters chosen for the model. The delivery method can be specified, including options for intravenous or subcutaneous dosing. The Ka property is an absorption rate relevant for non-intravenous dosing.

add_compartment(V_p_new: float, Q_p_new: float)

Receives V_p and Q_p for the desired additional compartment and adds these to the V_p and Q_p class attributes.

Args:

V_p_new (float): the volume of the compartment to be added [mL] Q_p_new (float): the transition rate between the central

compartment and the peripheral compartment being added [mL/h]

property cl

float: the value of CL for this model

property delivery_mode

str: returns either ‘iv’ or ‘sc’ for the delivery_mode

property ka

float: the value of Ka for this model

list_compartments()

Returns list of lists with a list of [V_p, Q_p] for each compartment.

property name

str: name is a property constructed from the model parameters. This protects data integrity by tying results to an immutable label.

remove_compartment(index: int)

Removes peripheral compartment at given index. Index refers to the compartment’s position given in model.list_compartments().

Args: index (int): the index of the compartment to be removed,

referring to V_p[index] and Q_p[index]; non-negative

property v_c

float: the value of V_c for this model

class pkmodel.protocol.Protocol(initial_dose: float = 1.0, time_span: float = 1.0)

The Protocol class holds the pharmacokinetic parameters related to the dose and time span of the dose. It contains a method to return a dose function for the chosen parameters.

add_dose_function(func=None)

Allows the user to specify the function describing rate of drug input over time

func: function, function describing the rate of drug input over time, set to None by default

dose(t, y): function

property dose

Returns the function describing rate of drug input over time

property initial_dose

Access the initial dose. Args:

None

Returns:

the initial dose (float)

property name

The name is a property constructed from the protocol parameters. This protects data integrity by tying results to an immutable label.

Args:

None

Returns:

name (string)

property time_span

Access the time span. Args:

None

Returns:

time span (float) [hours]

class pkmodel.solution.Solution

The Solution class structures access to the SciPy ODE solver. It also contains methods to visualise the solutions for the central compartment, in side-by-side or overlay views. The user can add or remove the models and protocols to be solved.

add(model, protocol)

Adds a pair of model and protocol objects to the solution object. The attributes and methods of the Model and Protocol classes can be found in their documentation.

Args:

model (pkmodel Model): the model object containing the parameters for the ODE solver. protocol (pkmodel Protocol): the protocol object containing the parameters of the dose and time span for the ODE solver

property list_compartments

Returns a list of tuples of (model, protocol) combinations in the solution object.

Args:

None

ode_system(q, t, model, protocol)

Takes as input an array-like list of variables q, a float time t, a Model object and a Protocol object, then returns the system of ODEs for this pair.

Args:

q (array-like object of variables q) t (float): time [hours] model (Model object) protocol (Protocol object)

Returns:

1-D list of functions of ordinary differential equations

ode_system_validation(q, t, model, protocol)

Performs validation on the ode_system input.

Args:

q (array-like object of variables q) t (float): time [hours] model (Model object) protocol (Protocol object)

Returns:

Boolean

remove(index: int)

Removes a model and protocol pair from the models and protocols lists in the solution class. Choose which pair to remove by finding its index in Solution.list_compartments(). Pair should have the same index as they can only be added together.

Args:

index (int): the index of the model and protocol pair to be removed.

As given in Solution.list_compartments().

solution(model, protocol, time)

Calcuates the ODE solution for a specific model and protocol using SciPy .solve_ivp().

Args:

model (Model object) protocol (Protocol object) time (list): t0 start of the integration and tmax the end [hours]

Returns:

numpy (ndarray): the numerical solutions to the system

visualise(layout='overlay', time_res=1000)

Plots the ODE solutions of the model using Matplotlib. Layout can be chosen to be overlay or side-by-side. Currently supports up to two side-by-side plots. Time resolution defaults to 100 time steps but can be changed by the user as desired.

Args:
layout (str): either ‘overlay’ or ‘side_by_side,’ defaults

to ‘overlay.’ Specifies if the solutions are shown overlaying each other on one plot or as independent subplots side by side.

time_res (int): the time resolution, specified as the number of

elements in the time and ODE solution array used for plotting. Default is 100 elements.

Indices and tables