For each observation (or at any time other than an observation time for which a prediction is needed), PREDPP computes a prediction available to the ERROR routine. Associated with each observation is an observation compartment. The amount A in the observation compartment at the time of observation, divided by the value of a parameter S, is used as the prediction. The parameter S is called a scaling parameter. There is one such parameter associated with every compartment of the kinetic model (including the output compartment). If omitted, scaling parameters defaul to 1.0.

The variable S0 may be used instead of Sn, where n is the number of the output compartment. The variable SC may be used to mean the scaling parameter with the central compartment.

(See also PK.)

With each possible dose compartment of the kinetic model (the output compartment is not a possible dose compartment), there is associated one bioavailability fraction parameter Fn.

If the amount on a dose record is A, and the bioavailability fraction is F, only the fraction F of A actually appears in the dose compartment (either instantaneously at the time the dose enters the compartment - with a bolus dose, or over a period of time - with a regular infusion; the bioavailability fraction does not apply to a steady-state infusion).

Bioavailability fractions are optional such that bioavailability fractions associated with compartments never used as dose compartments may be ignored. The default values is 1.

When additional doses are specified on a dose event record, the bioavailability fraction applies to the dose and to all the additional doses. When a steady-state dose is specified on a dose event record, the bioavailability fraction applies to the dose and to all implied doses leading to the steady-state.

(See CMT, PK, default compartment).

With any of the kinetic models a (peripheral) output compartment is always present. Associated with this compartment is a PK parameter, the output fraction. Of the entire amount, Ao, of drug introduced into the system by various dosage patterns and then eliminated from the system during a given time interval, a fraction FO of AO goes into this output compartment.

If the output compartment is not used, the output fraction is ignored. The default value is 1.

The use of FO depends on the assumption that the rate of change of drug amount in the output compartment is linear in the other compartment amounts. Other than this linearity restriction, the system can be nonlinear.

Tyically, the output compartment is used for urine observations, and the central for plasma observations, with any ADVAN.

(See CMT, PK, default compartment).

There is one rate parameter associated with every possible dose compartment of the kinetic model (the output compartment is not a possible dose compartment) and the rate parameter used for a given dose is that one associated with the compartment into which the dose is given (the dose compartment).

A rate-modeled zero-order bolus dose is actually an infusion, but one whose rate is given by the rate parameter computed by the PK routine.

Rate parameters are optional in the sense that rate parameters associated with compartments never receiving rate-modeled zero-order bolus doses or rate-modeled steady-state infusions may be ignored. However, if the RATE data item on some dose event record contains the value -1, then a rate parameter for the dose compartment must be computed in the PK routine.

Rate parameters act continuously. PREDPP obtains the value of a rate parameter, holding over the state-interval ( t1 , t2 ), from a call to PK with the record associated with t2, even if the dose event time occurs before t2. Therefore, if there are state times (e.g. t2) falling within the time interval over which a zero-order bolus dose appears in the system, there exists the possibility that the rate of drug input can change during the interval. For this to occur, the rate parameter would need to be modeled in terms of time varying covariates. As a result, a zero-order bolus dose where the rate is modeled might be better described as a piecewise zero-order process.

When additional doses are specified on a dose event record the rate parameter applies to the dose and to all the additional doses.

(See CMT, RATE, PK, default compartment).

(See exogenous supplementation example).

There is one duration parameter associated with every possible dose compartment of the kinetic model (the output compartment is not a possible dose compartment) and the duration parameter used for a given dose is that one associated with the compartment into which the dose is given (the dose compartment).

A duration-modeled zero-order bolus dose is actually an infusion, but one whose duration is given by the rate parameter computed by the PK routine.

Duration parameters are optional in the sense that duration parameters associated with compartments never receiving duration-modeled zero-order bolus doses may be ignored. However, if the RATE data item on some dose event record contains the value -2, then a duration parameter for the dose compartment must be computed in the PK routine.

A duration parameter is computed by the PK routine using, if needed, information in the dose record. Therefore, its value for the given dose is constant over time.

When additional doses are specified on a dose event record the duration parameter applies to the dose and to all the additional doses.

(See CMT, RATE, PK, default compartment).

(See multiple dose example).

There is one absorption lag time (parameter) associated with every possible dose compartment of the kinetic model (the output compartment is not a possible dose compartment) and the absorption lag time used for a given dose is that one associated with the compartment into which the dose is given (the dose compartment).

The event time t on a dose record refers to the recorded time the dose was administered. In the case of a regular infusion, t is the time the infusion was initiated. An absorption lag time is an increment of time L such that the time that the dose is regarded (by PREDPP) as entering (or starting to enter) the system is t+L.

Absorption lag times are optional in the sense that absorption lag times associated with compartments never used as dose compartments may be ignored. The values of absorption lag times that are not computed in PK are always understood to be 0.

An absorption lag time for a dose is computed by the PK routine using, if needed, information in the dose record. When additional doses are specified on a dose event record, the absorption lag time applies to the dose and to all the additional doses. With a steady-state multiple dose the absorption lag time applies not only to this dose, but also to all the preceding implied doses. With a steady-state dose, the lag time should be less than the interdose interval.

(See cmt, PK, default compartment).

If a time scale parameter is modeled by PK, then time itself may be scaled differently between individuals. There is a single time scale parameter that multiplies all rate constants. The parameter acts continuously (and could therefore theoretically itself vary with time measured on an external clock). It can only be used with linear kinetic models. If it is not used, it can be ignored. If the value of the time scale parameter is not computed in PK, it is always under- stood to be 1.

The time scale parameter does not scale the duration parameter D of a duration-modeled zero-order bolus dose.

TSCALE may be written as XSCALE.

PREDPP ignores the time scale parameter with general nonlinear models (ADVAN6, 8, 9, 13,14,15,16,17,18).

(See PK).

See MTIME.

Array elements A_0(1), …, A_0(n) may be used on the left-hand to assign initial values to compartments. A reserved right-hand variable, A_0FLAG, is set to 1 by PREDPP when PK may initialize compartments to specific amounts. For example,

1
2
3

  IF (A_0FLG.EQ.1) THEN
  ! compartment initialization block to specify A_0(n)=....
  ENDIF

This specifies the initial amount for compartment n. A_INITIAL(n) is a synonym for A_0(n). The above code fragment is an explicit compartment initialization block. A_0(n) may also be assigned a value with an unconditional statement. This defines an implicit compartment initialization block. NMTRAN inserts "IF (A_0FLG.EQ.1) …" before the statement and "ENDIF" after it. Indicator variables may be used to avoid conditional assignment statements.

See Compartment Initialization Block.

Reserved left-hand variable I_SS may be set to the same values as the I_SS option of $MODEL record. This allows initial steady-state to be set conditionally, e.g., if some subjects are at steady-state and others are not.

(See ADVAN6/8/9, $MODEL)

(See Initial Steady State: I_SS,ISSMOD).

Same as the NEWIND argument passed by NONMEM to PREDPP.

• NEWIND=0: PK is called with the first record of the data set. THETA value may differ from value at last call with this record.
• NEWIND=1: PK is called with the first event record of the second or subsequent individual record. THETA value does not differ from value at last call with this record, and PRED is nonrecursive (see I_REC), or, First record of a subsequent individual record.
• NEWIND=2: PK is called with the second or subsequent data record of an individual record.

Same as the ICALL argument passed by NONMEM to PREDPP.

• ICALL=1: Initialization.
• ICALL=2: Normal call.
• ICALL=3: Finalization.
• ICALL=4: regular call in simulation.
• ICALL=5: Expectation. Call to PK occurs when expectations are being computed (the marginal data item MRG_ has a non-zero value for some records).
• ICALL=6: Raw data averages.
• Special rules apply to blocks of abbreviated code that are executed when ICALL is not 2. (See Initialization-Finalization block, Simulation block, Expectation block, Data average block).

NM-TRAN will move abbreviated code that tests for ICALL=0, ICALL=1, or ICALL=3 in the $PK block to the INFN routine as part of an $INFN block. With verbatim code in the FIRST block, ICALL will never have the value 0 or 3. ICALL has the value 1 if the call to PK is the first call to PK in the problem. At this call, the THETA’s are the initial estimates; the ETA’s are undefined. Verbatim code is not moved to the INFN routine.

If COMRES=1 is not present in $ABBREVIATED or $PK records, then PK-defined variables are listed in NMPRD4 and may be used in other routines and blocks of abbreviated code. The symbol COM(n) may be used on the left or the right if n refers to a reserved position in MODULE NMPRD4. Variables defined in $INFN and listed in MODULE PRINFN are also global and may be used in $PK and other blocks of abbreviated code, on the left and on the right. Variables defined by $ABBREVIATED DECLARE records are also global and may be used in $PK and other blocks of abbreviated code.

• If PK is not being called at an additional or lagged dose time, then DOSTIM = 0 and all elements of DOSREC are 0.
• If PK is called at an additional or lagged dose time t, then DOSTIM=t.
• DOSREC contains a copy of the dose event record which initiated the additional or lagged dose (actually, only of the final row: EVTREC(NVNT,*)). Data items may be referred to by position or by label, e.g., DOSREC(1) or DOSREC(ID). In DOSREC, TIME and all user (concomitant) data items have values from the next event record. All other NONMEM/PREDPP reserved data items have values from the initiating dose event record. (The $BIND record may be used to override this.)

A(n) are the latest computed compartment amounts, and TSTATE is the time at which they were computed. That is, A(n) are the amounts at the previous event time, or if at a later time, but before the time for which PK is being called, a lagged or additional dose was given, or a regular infusion was terminated, or a modeled event occurred, then A(n) are the amounts at the latest such time. If there are population ETAs, and A(n) are used in the $PK abbreviated code, then any $OMEGA records referring to ETAs explicitly used in this code should precede the $PK record, or if an $MSFI record is used, it should precede the $PK record and include the option NPOP=m. Note: If there is no verbatim code and no explicit use of a sub- scripted variable A in the $PK record, then the symbol A can be used as a data item label or as a name of a PK-defined item.

Signals a record with which it is possible to initialize a compartment amount. See Compartment Initialization Block, and A_UFLG below.

Before NM75, the amounts in compartments could be set by the use of the A_0() array only when EVID=3, EVID=4, or for the first record of an individual, that is, only at the “initial” state. The A_0FLG is set to 1 by PREDPP at those times, which then executes code that sets the A_0() values. For example:

1
2
3
4

$PK
If (A_0FLG==1) then
A_0(3)=k03/k30
Endif

Any A_0(x) not explicitly defined are set to 0. However, the A_0FLG may not set by the user in the $PK record, preventing the user from updating compartment amounts at any time. As of nm75, the modeler may update the compartment values at any time, using the flag A_UFLG (the ending U stands for update) with the desired compartment values set in the array A_U(). By use of MTIME to designate a variable time position at which an abrupt change in compartment amounts occurs, one could input a dose as follows:

1
2
3
4
5
6
7
8
9

MTIME(1)=wtime
MTDIFF=1
AZTEST=A_0FLG
IF(TSTATE==MTIME(1).AND.AZTEST==0) A_UFLG=1
IF(A_UFLG==1) THEN
A_U(1)=A(1)+wdose
A_U(2)=A(2)
A_U(3)=A(3)
ENDIF

The IF(A_UFLG==1) block is optional, as NMTRAN will insert one if not present. So the code could also be written as:

1
2
3
4
5
6
7

MTIME(1)=wtime
MTDIFF=1
AZTEST=A_0FLG
IF(TSTATE==MTIME(1).AND.AZTEST==0) A_UFLG=1
A_U(1)=A(1)+wdose
A_U(2)=A(2)
A_U(3)=A(3)

The A_UFLG event must be triggered with an IF(TSTATE==MTIME()) condition as indicated in the above example. Care should be taken that all the A_U(x) for all compartments x be properly defined. NMTRAN converts A_U() to A_0() during FSUBS code construction. You may wish to ensure A_0FLG is 0 whenever A_UFLG is set to 1, as shown in the example above ("examples/a_uflg").