DERIVATIVES¶
An optional verbatim section that defines an ordinary differential equation model in a PoPy script.
The DERIVATIVES section computes s[X] state amounts at multiple time points using ordinary differential equations given initial s[X] from the STATES section and previously computed m[X] and c[X] parameters for each row in the data file.
Note the DERIVATIVES section is optional. It is possible to not have a compartment model in your script. For example you can just directly use individual m[X] variables in the PREDICTIONS section instead of generating s[X] values.
The DERIVATIVES section is available in the following scripts:-
i.e. Any script that processes PK/PD models.
Example DERIVATIVES for PK Model¶
The example below is used in Fitting a Two Compartment PopPK Model.
DERIVATIVES: |
# s[DEPOT,CENTRAL,PERI] = @dep_two_cmp_cl{dose:@bolus{amt:c[AMT]}}
d[DEPOT] = @bolus{amt:c[AMT]} - m[KA]*s[DEPOT]
d[CENTRAL] = m[KA]*s[DEPOT] - s[CENTRAL]*m[CL]/m[V1] - s[CENTRAL]*m[Q]/m[V1] + s[PERI]*m[Q]/m[V2]
d[PERI] = s[CENTRAL]*m[Q]/m[V1] - s[PERI]*m[Q]/m[V2]
The example above defines a two compartment PK model with a Depot compartment. The same model can be expressed as:-
DERIVATIVES: |
s[DEPOT,CENTRAL,PERI] = @dep_two_cmp_cl{
dose:@bolus{amt:c[AMT]},
KA: m[KA],
CL: m[CL],
V1: m[V1],
Q: m[Q],
V2: m[V2],
}
Where @dep_two_cmp_cl is a analytic compartment function. That uses the analytic solution to the ordinary differential equation instead of using a numerical ODE_SOLVER.
Note you can also write:-
DERIVATIVES: |
s[DEPOT,CENTRAL,PERI] = @dep_two_cmp_cl{ dose:@bolus{amt:c[AMT]} }
As the default values for ‘KA’, ‘CL’ etc are the equivalent m[X] variables. You still need to have all the appropriate m[X] variables defined in MODEL_PARAMS and c[AMT] defined in your data file.
PoPy also provides multiple alternative ways of formulating the d[X] equations as follows:-
DERIVATIVES: |
d[DEPOT] = @bolus{amt:c[AMT]}
d[CENTRAL] = 0.0
d[PERI] = 0.0
d[DEPOT] -= m[KA]*s[DEPOT]
d[CENTRAL] += m[KA]*s[DEPOT]
d[CENTRAL] -= s[CENTRAL]*m[CL]/m[V1]
d[CENTRAL] -= s[CENTRAL]*m[Q]/m[V1]
d[PERI] += s[CENTRAL]*m[Q]/m[V1]
d[CENTRAL] += s[PERI]*m[Q]/m[V2]
d[PERI] -= s[PERI]*m[Q]/m[V2]
The syntax above is standard Python, but makes the inputs and outputs of each compartment clear. You can also use this flow based syntax:-
DERIVATIVES: |
d[DEPOT] = @bolus{amt:c[AMT]}
d[CENTRAL] = 0.0
d[PERI] = 0.0
d[DEPOT->CENTRAL] += m[KA]*s[DEPOT]
d[CENTRAL] -= s[CENTRAL]*m[CL]/m[V1]
d[CENTRAL->PERI] += s[CENTRAL]*m[Q]/m[V1]
d[PERI->CENTRAL] += s[PERI]*m[Q]/m[V2]
This expresses the flows between compartments explicitly and avoids having to manually pair up the positive and negative flows. Note an unintentional mis-match between inputs and outputs in compartment models usually leads to mass balance issues and models that are difficult to interpret and fit.
Note a sanity check on the DERIVATIVES section is to view the compartment diagram that is automatically created by PoPy, see Fig. 52.
Fig. 52 Two compartment model with depot dosing, computed automatically from DERIVATIVES section.
All the example DERIVATIVES sections presented here generate the same diagram. If you make a mass balance error your diagram may well not look like you expect. This is a useful safety feature built into PoPy.
Example DERIVATIVES for PD Model¶
See Direct PD Model for example Tut Script, using the following DERIVATIVES section for a PD model:-
DERIVATIVES: |
d[CENTRAL] = @bolus{amt:c[AMT]} - s[CENTRAL]*c[CL]/c[V]
d[MARKER] = m[BASE]*m[KOUT] - (1+s[CENTRAL]/c[V])*m[KOUT]*s[MARKER]
As discussed in Example STATES for PD Model. The following STATES section is required to initialise the derivative model in an equilibrium state:-
STATES: |
s[CENTRAL] = 0.0
s[MARKER] = m[BASE]
Note it’s possible to split this DERIVATIVES model up into separate flows:-
DERIVATIVES: |
d[CENTRAL] = @bolus{amt:c[AMT]}
d[MARKER] = 0.0
d[CENTRAL] -= s[CENTRAL]*c[CL]/c[V]
d[MARKER] += m[BASE]*m[KOUT]
d[MARKER] -= (1+s[CENTRAL]/c[V])*m[KOUT]*s[MARKER]
It’s also possible to mix and match s[X] and d[X] variables, by using a analytic compartment function for the PK compartment:-
DERIVATIVES: |
s[CENTRAL] = @iv_one_cmp_cl{ dose:@bolus{amt:c[AMT]}, CL:c[CL], V:c[V]}
d[MARKER] = m[BASE]*m[KOUT] - (1+s[CENTRAL]/c[V])*m[KOUT]*s[MARKER]
Note in the above if you use a analytic compartment function then you need s[X] on the left hand side (see Central compartment). If you use numerical equations then you need d[X] on the left hand side and s[X] variables on the right hand side (see Marker compartment).
All of the above DERIVATIVES sections should result in the same compartment diagram as shown in Fig. 53.
Fig. 53 direct PD model, computed automatically from DERIVATIVES section.
Example DERIVATIVES using x[TIME]¶
See Sine circadian model for example Tut Script, using the following DERIVATIVES section:-
DERIVATIVES: |
conc_central = s[CENTRAL]/c[V]
circ = exp(m[AMP] * sin(2*pi*(x[TIME]-m[INT])/12))
d[CENTRAL] = @bolus{lag:0, amt:c[AMT]} - c[CL]*conc_central # PK
d[MARKER] = m[KIN]*conc_central + circ - m[KOUT]*s[MARKER] # PD
This PK model has a circadian input to the ‘MARKER’ compartment, so is in a equilibrium oscillating about a mean value, until a dose is administered in the PK compartment, which then causes an effect in the PD compartment through the ‘conc_central’ variable.
The main point of interest in this model is that the variable x[TIME] is used within the DERIVATIVES section. x[TIME] is a special variable that uses the continuous time when solving the ordinary differential equations. This is distinct from using c[TIME], which is constant at time points between data rows.
Note you can use c[TIME] as an approximation if you have lots of data rows, but generally it’s better to use x[TIME] to model explicit time dependent components such as circadian variation within the DERIVATIVES section.
The compartment diagram for this PK/PD model is as shown in Fig. 54.
Fig. 54 circadian PD model, computed automatically from DERIVATIVES section.
Rules for DERIVATIVES section¶
Like all verbatim sections the DERIVATIVES section of the config file accepts free form Python pseudocode, but there are some rules regarding which variables are allowed in a DERIVATIVES section as follows:-
- Only
d[X]and local variables can be defined on the left hand side without using Analytic Compartment Functions. s[X]variables are usually on the right hand side and must have a correspondingd[X]variables[X]variables can only be defined on the left hand side if you use a analytic compartment functions[X]variables present in DERIVATIVES but not in STATES are initialised to zero.c[X]andm[X]are only allowed on the right hand side of expressionsc[X]must be defined in the data file or PREPROCESS section in a Fit Scriptc[X]must be defined within the EFFECTS section in a Gen Script or GEN_EFFECTS section in a Tut Script.m[X]must be defined in the MODEL_PARAMSx[TIME]can be used to model continuous time, as opposed to discretec[TIME]
You can not use p[X], r[X], f[X] or t[X] etc. variables at all in this section.
Like all verbatim sections it is possible to introduce syntax errors by writing malformed Python. Any coding errors will be reported when PoPy attempts to compile or run the DERIVATIVES function as a temporary .py file.