• Language: en

STATES

An optional verbatim section that defines initial s[X] variables for the DERIVATIVES block. The ordinary differential equation model in PoPy is typically a initial value problem. The STATES section defines the initial values.

Note the STATES section is optional. If it is not provided, then by default all s[X] variables are initialised to zero. In PK problems this is often sufficient, but a STATES section is often required for PD models.

The STATES section takes as input the previously defined m[X] and c[X] variables and computes the initial s[X] variables. The STATES function is run on the first row of each individual and for every reset row in the data file. The STATES section is available in the following scripts:-

i.e. Any script that contains a DERIVATIVES ordinary differential equation model.

Example STATES for PK Model

In Fitting a Two Compartment PopPK Model, a null states section is used:-

STATES: |

This is equivalent to just removing the STATES section altogether. It is also equivalent to writing this:-

STATES: |
    s[DEPOT] = 0.0
    s[CENTRAL] = 0.0
    s[PERI] = 0.0

The form of the STATES section is very dependent on the DERIVATIVES section that it is initialising. The s[X] variables that are defined in STATES must exist in the DERIVATIVES section.

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]

Setting all amounts to zero in the PK compartments is fairly common. As before any dose is administered no drug is expected to be present in the body.

The steady state is therefore zero. The amounts in each compartment only become positive after a dose is administered. As the drug is excreted from the body the amount of drug in each compartment converges back to zero.

Note a reset row in the data file short cuts the wash out process by removing all of the drug from the body, by calling the null STATES function above.

Example STATES for PD Model

See Direct PD Model for example Tut Script, using the following STATES and DERIVATIVES sections for a PD model:-

STATES: |
    s[CENTRAL] = 0.0
    s[MARKER] = m[BASE]

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]

In this example the s[MARKER] initial value is set to m[BASE]. This is in order to make sure that the ‘MARKER’ PD compartment is at equilibrium, when the ‘CENTRAL’ PK compartment is zero.

You can usually deduce the equilibrium conditions for a PD compartment by setting the d[X] variables to zero and solving for s[X], with the PK compartments set to zero.

For example in this case, setting d[CENTRAL] to zero:-

0.0 = -s[CENTRAL]*c[CL]/c[V]

implies:-

s[CENTRAL] = 0.0

Then setting d[MARKER] to zero:-

0.0 = m[BASE]*m[KOUT] - (1+0.0)*m[KOUT]*s[MARKER]

implies:-

s[MARKER] = m[BASE]

These equilibrium conditions ensures that the amounts in ‘CENTRAL’ and ‘MARKER’ are fixed until the system is disrupted by a drug dose being administered. As the drug is washed out of the system, the system should smoothly return back to equilibrium.

Alternatively if a reset row is encountered in the data file then the system is jolted back to the equilibrium by running the STATES function.

The non-zero equilibrium value of s[MARKER] is meant to model the endogenous amount of a substance within the body. i.e. a substance that is naturally present without drug intervention. This biological fact makes PD models inherently more complex than PK models and they usually require a more complex STATES section.

Rules for STATES section

Like all verbatim sections the STATES section of the config file accepts free form Python pseudocode, but there are some rules regarding which variables are allowed in a STATES section as follows:-

You can not use d[X], 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. Coding errors will be reported when PoPy attempts to compile or run the STATES function as a temporary .py file.

MODEL_PARAMS
DERIVATIVES
Back to Top