Action_code

Action code

This section discusses action code and what it does. Some basic action code statements include dobefore, doafter, sequence, and sleep.

First, the framework within which action code works must be explained.

A PML model either is or is not truly time-based. A model is truly time-based if:

It contains a deriv or a urinecpt statement.

It implicitly contains a deriv statement, such as an event or count statement, which causes the model to calculate a hidden differential equation that accumulates, or integrates, the hazard rate.

It contains a cfMicro or a cfMacro statement.

If a model is truly time-based, then it automatically contains a variable called t, and time is assumed to be the independent variable. The model’s input dataset must contain columns for time values and for any covariate values. Only truly time-based models can use multiple dose inputs.

If a model is not truly time-based, then covariates are its only inputs. Since the model does not automatically know what the independent variable is, it must be specified via syntax in the observe statement, such as:

   observe(EObs(C)=…)

where the (C) tells the model that C is the independent variable.

In a non-time-based model, there is no default variable for time (t) as there is for a time-based model. To include this variable, do one of the following:

Change the model into a time-based model by including a statement such as:
deriv(foo=0)

Make t a covariate (e.g., covariate(t), be sure to map t and include the following statement to indicate the independent variable:
observe(CObs(t)=C+CEps)

Make Time a covariate (e.g., covariate(Time)), then replace t with Time in the model, and check the mapping.

Note: If C is not given on the same data row as EObs, that observation is ignored. If the independent variable is not specified in the observe statement, as for example observe(EObs=E*exp(eps)), observations of EObs are processed regardless, even though they are not associated with a corresponding independent variable.

If a model is truly time-based, it executes in a recursive fashion. That means model execution consists of a series of continuous simulation intervals, with stops between each interval.

In a continuous simulation interval, the state of the model evolves forward through time under control of an ODE solver such as Matrix Exponent, Runge-Kutta (non-stiff), Gear (stiff, analytic, and finite difference Jacobian), Closed-Form (no ODE solver used), or a combination of these four.

Discontinuous actions can occur during a stop between continuous simulation intervals. Discontinuous actions include:

delivering a dose into a compartment all at once as opposed to spreading the delivery over time

start of an infusion

end of an infusion

taking of an observation

setting a covariate value

actions associated with an observation or dose, when they are specified with a dobefore or doafter action block

actions specified with any sequence block.

Variables in a model fall into categories, depending on whether they can or cannot be modified when the model is stopped.

Integrator variables (variables on the left side of deriv statements) such as compartment amounts, can be modified when the model is stopped. When the model is simulating, these variables are controlled by the ODE solver.

Variables introduced with the real keyword, such as real(G), can be modified when and only when the model stops running.

Variables introduced with only an assignment statement, such as C=A/V, cannot be modified when the model is stopped. The variables are considered to only be functions of the continuous model state.

It is allowable to have multiple assignment statements assigned to the same variable, in which case the order between them matters. For example: E=E0; E=E+E1; etc. This statement is a single assignment statement because all assignments could all be collapsed into one assignment statement. Note that variables on the right-side of assignment statements must be defined prior to their use.

The sequence statement, of the form sequence{…}, specifies a sequence of actions to be performed when the model is stopped. This sequence acts like a typical programming language sequence in that order matters because the sequence statements are performed one at a time, in order.

Note: In PML models, sequence and assignment statements are the only statements in which order matters.

For all other statements in PML models, the order of the statements does not matter. This means that the statements inside a sequence block are very different from other statements in PML models. The sequence statements consist of:

Assignments (only for variables that can be modified when the model is stopped)

if(test-expression) statement-or-block [else statement-or-block]

while(test-expression) statement-or-block

sleep(duration-expression)

function calls

These statements only run when the model is stopped. The model is “stopped” before it is executed. This means that sequence statements are executed before the model is “started,” and run until a sleep statement is encountered.

When a sleep statement is encountered, its argument, which is a delta-time, is calculated and then the sequence stops executing. The sequence is then put into a queue until it is used at a future time. At that time, the model stops, and the sequence block commences executing where it left off.

A model can contain multiple sequence blocks, and they are executed in a nearly parallel manner. If there are multiple sequence blocks, no assumptions should be made about which block is executed first. See “The sequence and sleep statements” for more information.

Because model execution stops for dose and observation events, actions can be performed at those times. For example:

   observe(CObs=C+eps, doafter={A=0;})

In this example, immediately after CObs is observed, variable A is set to 0 (zero), where A could be the drug amount in a compartment. The action block consists of curly brackets {…} containing zero or more statements. The statements can be optionally separated by semicolons.

Note: The statements allowed in the observe statement as the same as those allowed in the sequence statement, except that sleep is not allowed in the observe statement.