NONMEM Users Guide Part IV - NM-TRAN - Chapter V

V. NM-TRAN with PREDPP

V.A. Introduction

NM-TRAN is designed to facilitate the use of PREDPP. This chapter addresses special considerations regarding the use of NM-TRAN with PREDPP.

Here follows an example of an NM-TRAN control stream; it is meant to be used with PREDPP along with the NM-TRAN data set shown in Appendix VI. This NM-TRAN control stream is recorded on the NONMEM distribution medium; see Guide III. The control stream and data set are constructed so to accomplish the same things as do the control stream and data set considered in chapter I, but they are constructed on the assumption that PREDPP is to be used. NM-TRAN will translate the data set and control stream to a NONMEM data set, a NONMEM control stream, and completely coded PK and ERROR subroutines. These NM-TRAN outputs are given in Appendix VII. The effect of using them as inputs to a NONMEM run will be to produce essentially the same output obtained from using the NONMEM control stream and PK and ERROR subroutines shown in Appendix II of Guide VI.

$PROB  THEOPHYLLINE   POPULATION DATA
$INPUT      ID DOSE=AMT TIME CP=DV WT
$DATA       THEOPP

$SUBROUTINES  ADVAN2

$PK
;THETA(1)=MEAN ABSORPTION RATE CONSTANT (1/HR)
;THETA(2)=MEAN ELIMINATION RATE CONSTANT (1/HR)
;THETA(3)=SLOPE OF CLEARANCE VS WEIGHT RELATIONSHIP (LITERS/HR/KG)
;SCALING PARAMETER=VOLUME/WT SINCE DOSE IS WEIGHT-ADJUSTED
   CALLFL=1
   KA=THETA(1)+ETA(1)
   K=THETA(2)+ETA(2)
   CL=THETA(3)*WT+ETA(3)
   SC=CL/K/WT

$THETA (.1,3,5) (.008,.08,.5) (.004,.04,.9) $OMEGA BLOCK(3) 6 .005 .0002 .3 .006 .4

$ERROR

   Y=F+EPS(1)

$SIGMA .4

$EST MAXEVAL=450 PRINT=5 $COV $TABLE ID DOSE WT TIME $SCAT (RES WRES) VS TIME BY ID

V.B. Data Set Translation with PREDPP

When PREDPP is used, EVID and MDV data items are required in the NONMEM data set. When PREDPP is used, MDV data items need not be included in the NM-TRAN data set; NM-TRAN can automatically include them in the NONMEM data set. Such MDV data items are called generated MDV data items

Under certain circumstances, NM-TRAN can also automatically include EVID data items in the NONMEM data set. Such EVID data items are called generated EVID data items

If EVID data items are not included in the NM-TRAN data set, they are generated as follows: If each of the AMT and RATE data items in an event record is either 0, or is represented by a NM-TRAN null data item, or is missing, then the generated EVID data item is 0 (meaning that the event is an observation event). Otherwise, the generated EVID data item is 1 (meaning that the event is a dose event). If there are other-type, or reset, or reset-dose events in the data set, then the user himself should supply EVID data items.

If MDV data items are not included in the NM-TRAN data set, they are generated as follows: If the data record is the last record of an event record, then the generated MDV data item is 0 or 1 according as the EVID data item (generated or user-supplied) is 0 or not 0. If the data record is not the last record of an event record, then the generated MDV data item is 1.

With PREDPP, interdose interval (II) data items may appear. NM-TRAN can translate II data items expressed in the form hr:min to II data items expressed in the form hr.fr, where min (minutes) can be any two-digit integer from 00 to 59, and fr is a decimal fraction of the hour to two digits. Here hr (hours) can be any nonnegative integer. Examples of II data item translation are these: 1:30 @->@ 1.50; 1.30 @->@ 1.30. Note that if the data item has a colon, it is translated; otherwise, it is left unchanged. It is the user’s responsibility to make sure that the units of the TIME data items and the II data items are consistent. For example, suppose that TIME data items in the NM-TRAN data set are expressed as relative times in minutes; they are then left unchanged by NM-TRAN. II data items in the NM-TRAN data set should then also be expressed in minutes, and they should not contain colons so that NM-TRAN leaves them unchanged.

When continuation (CONT) data items appear, data items in both the TIME and II positions of data records with CONT data item equal to 1 are left unchanged by NM-TRAN.

V.C. Control Records with PREDPP

There are a few control records which are specific to the use of PREDPP. These are described in the following subsections, along with details concerning the nonspecific control records which are pertinent to the use of PREDPP only. A listing of NM-TRAN control records and options which should be used with PREDPP is given in Appendix V.

V.C.1. $INPUT Record

The $INPUT record is described in detail in section III.B.2.

NM-TRAN recognizes these PREDPP-specific reserved labels: EVID, TIME, AMT, RATE, SS, II, ADDL, CMT, PCMT, CALL, CONT. By using any one of these labels in an item of the $INPUT record, the user defines the PREDPP data item type whose name corresponds to the label. When PREDPP is not used, any of these labels can be used, but with the exception of TIME, they have no special significance.

Ignoring items with the DROP or SKIP labels, the total number of items in a NM-TRAN data record cannot exceed 20, including generated EVID data items, generated MDV data items, and, if the data set is single-subject, generated ID data items (all of which actually do not appear in the NM-TRAN data set). Generated EVID data items are assigned the label EVID, and generated MDV data items are assigned the label MDV. These labels can be used in subsequent NM-TRAN control records of the problem specification.

V.C.2. $BIND Record

$BIND  @value sub 1@ @value sub 2@ ... @value sub n@

E.g.
$INPUT      ID    DOSE=AMT    TIME    CP=DV    WT   PREP
$BIND       -     -           -       -        NEXT DOSE

This record is used in conjunction with the $INPUT record to further define the meaning of certain data items occuring as right-hand quantities in an abbreviated code for PK when PK is called at nonevent dose times (see below and Guide VI, section III.B.2). (Normally, PK is not called at these times.) At such calls, PK has access to several different data items of the same type, from several different event records. The definitions in the $BIND record precisely determine which of these data items are represented by the label for the data item type used in the abbreviated code.

This record is optional. If it appears, it must be with the first problem specification, and only with this problem specification. It can only be used when an abbreviated code for PK is also used.

There appear n values, where n should not exceed the total number of labels listed on the $INPUT record, including all DROP and SKIP labels. The ith value corresponds to the ith label.

A nonevent dose time is a time that a lagged dose or additional dose enters, or starts to enter, the system. It is some time after the event time occuring on the dose record. When PK is called at such a time, information from three event records is available. These are the dose record itself, the last event record, and the next event record. The last event record is the last event record with event time occuring before the nonevent dose time. The next event record is the first event record with event time occuring after the nonevent dose time. This event record is also called the argument record (see Guide VI, section III.B.2). PK is called at nonevent dose times only if a certain PK calling-protocol is requested (see section C.5).

Some data item types are NONMEM data item types: ID, L2, MDV, DV, and these are not affected by the $BIND definitions. At a nonevent dose time, these labels always represent the data items from the dose record; this is the mandatory representation. Some data items types are PREDPP data item types: AMT, RATE, SS, ADD, II, MT, CMT, CALL, EVID, and these are not affected by the $BIND definitions. These labels also always represent the data items from the dose record; this is the mandatory representation. The TIME data item type is a PREDPP data item type, and it is not affected by the $BIND definition; the label always represents the time data item from the next event record. The other data item types (labeled WT and PREP in the above example) are only recognized and responded to by the user’s PK routine. With the $BIND record the user may define the label of such a data item type to represent the data item from the dose record, the last event record, or the next event record. If a label definition for a data item type is not given explicitly, then by default the label represents the data item from the next event record.

If the value is (explicitly) DOSE, LAST, or NEXT, the label represents the item from the dose record, the last event record, or the next event record, respectively. If one of these values is used, it should not contradict the mandatory representation for the label (of a NONMEM or PREDPP data item). The value ’-’ serves as a place holder; a value is assumed that corresponds to the mandatory or default representation. If the number n is less than the total number of labels listed on the $INPUT record, the values corresponding to the remaining labels are taken to correspond to the respective mandatory and default representations. If the $BIND record is not used, the values corresponding to all labels are taken to correspond to the respective mandatory and default representations.

In the above example, in abbreviated PK code the variable PREP denotes the preparation indicator on the dose record describing the dose entering the system at a nonevent dose time. If the $BIND record is not used, the variable denotes the preparation indicator on the next event record, which may not even be a dose record. The variable WT denotes the weight on the next event record, which is the default representation.

If the label in the $INPUT record is DROP or SKIP, the issue of label representation is moot and is ignored. In this case the value can be ’-’, or it can be DROP or SKIP.

$INPUT and $BIND records may be interleaved to help maintain a perspicuous visual relationship in the control stream. The above example might have been written thusly:

$INPUT      ID    DOSE=AMT    TIME    CP=DV
$BIND       -     -           -       -

$INPUT      WT   PREP
$BIND       NEXT DOSE

The $BIND record may be used with either generated or NM-TRAN library routines. However, as with changes to the $INPUT record, changes to the $BIND record can cause changes to the generated code for PK, and in this case the previous load module should not be reused.

Even when a value is LAST or NEXT, it is still possible for an abbreviated code for PK to access the data item in the dose record; see section C.5.

V.C.3. $SUBROUTINES Record

$SUBROUTINES  [@subname sub 1 = name sub 1@] [@subname sub 2 = name sub 2@] ...
              [SUBROUTINES=kind] [TOL=@n sub 1@]

E.g.
$SUBROUTINES    ADVAN=ADVAN8 TOL=4

NM-TRAN recognizes these additional subnames: ADVAN, SS, TRANS, PK, ERROR, DES, AES, INFN, TOL, MODEL.

The first two subnames, ADVAN and SS, are not generic names of subroutines which can be user-supplied, in contrast to all other possible subnames which can appear in the $SUBROUTINES record. Rather, they are generic names of subroutines from the PREDPP Library. With PREDPP the subname ADVAN must appear and be set equal to one of the names: ADVAN1, ADVAN2, ..., whichever specific ADVAN routine is chosen from the Library. The subname SS need appear only if steady-state data items are included in the data set. Even then, if subroutine ADVANk is chosen, it will be assumed that subroutine SSk is also chosen, and the subname-name pair SS=SSk need not appear. (If ADVAN8 or ADVAN10 is chosen, it will be assumed that subroutine SS6 is also chosen.)

The third subname, TRANS, is a generic name of a subroutine which can come from the PREDPP Library or be user-supplied. If the subroutine comes from the Library, the name must be either TRANS1, or TRANS2, etc. If the subroutine is user-supplied, the name must be different from any name of a TRANS routine in the Library. A subname-name pair for the TRANS routine need not be given; then TRANS=TRANS1 is "understood".

If the PK subroutine is not user-supplied, so that PK is not used as a subname, then an abbreviated code must be given for PK. If the ERROR subroutine is not user-supplied so that ERROR is not used as a subname, then an abbreviated code must be given for ERROR. Abbreviated codes may be given for neither routine, or for only one of them, or for both of them.

Whether the DES routine is used depends on the ADVAN routine used. Similarly, whether the AES routine is used depends on the ADVAN routine used. If the DES (AES) routine is required by the ADVAN routine, and if it is not user-supplied, so that DES (AES) is not used as a subname, then an abbreviated code for DES (AES) must be given. Abbreviated code for the AES routine is actually given by two abbreviated codes; see sections C.8 and C.9.

If an abbreviated code is given for PK, ERROR, DES, or AES, then the SUBROUTINES option is used as described in section III.B.6. This usage determines whether the subroutine will be generated or whether the NM-TRAN Library version of the routine will be used. Whichever choice is made, it holds for all subroutines for which abbreviated code is given.

An abbreviated code cannot be given for the INFN routine.

Whether the TOL routine is used depends on the ADVAN routine used. Similarly, whether the MODEL routine is used depends on the ADVAN routine used.

If the TOL routine is required by the ADVAN routine, and if it is neither user-supplied nor defined by a $TOL record (see section C.10), so that TOL is not used as a subname, then using the TOL option, NM-TRAN will generate either a complete FORTRAN coded TOL subroutine or instructions to the NM-TRAN Library TOL routine. The number @n sub 1@ with the TOL option is the number of accurate digits required in the computation of all compartmental drug amounts. As a rule of thumb, one should begin by taking @n sub 1@ to be @n+1@ or @n+2@, or with double precision, perhaps to @n+2@ or @n+3@, where @n@ is the option value with the SIGDIGITS option on the $ESTIMATION record. If one succeeds with this setting, one might try increasing @n sub 1@ slightly. With ADVAN9 the number of accurate digits can be specified on a compartment-specific basis. However, to do this, either a TOL routine must be user-supplied or the $TOL record must be used.

If the MODEL routine is required by the ADVAN routine, the MODEL routine may be user-supplied. Then the PK routine must also be be user-supplied. If a DES (AES) routine is needed, then it too must be user-supplied. If the MODEL routine is not user-supplied, so that MODEL is not used as a subname, then using information supplied in the $MODEL record (see next section C.4), NM-TRAN will generate either a complete FORTRAN coded MODEL subroutine or instructions to the NM-TRAN Library MODEL routine. Abbreviated code for MODEL cannot be given. In this case an abbreviated code for PK may be given, as may abbreviated codes for DES and AES.

Each of the subnames ADVAN, SS, and TRANS, along with the equal sign that follows it, may be omitted when it is followed by a specific name of a PREDPP Library routine; see, for example, the control stream in section A. However, when the subname is not omitted, the specific name of a PREDPP Library routine can be given by the associated number only, e.g. ADVAN=1 instead of ADVAN=ADVAN1.

V.C.4. $MODEL Record

$MODEL   [NCOMPARTMENTS=@n sub 1@] [NEQUILIBRIUM=@n sub 2@] [NPARAMETERS=@n sub 3@]
         [COMPARTMENT=([name] [@attribute sub 1@] [@attribute sub 2@] ...)] ...
         [LINK @compname sub a@ [TO|AND] @compname sub b@ BY k [l]] ...

E.g.
$MODEL   NPARAMETERS=3
         COMP=(DEPOT DEFDOSE INITIALOFF) COMP=(CENTRAL DEFOBS NOOFF)
         LINK DEPOT CENTRAL BY 3
         LINK CENTRAL OUTPUT BY 1

This record gives information from which NM-TRAN can generate either a complete FORTRAN coded MODEL routine or instructions to the MODEL routine in the NM-TRAN Library.

This record is required when the ADVAN routine requires a MODEL routine, and this routine is not user-supplied. It is only required for the first problem specification. It applies for all problem specifications in the control stream, and it must not appear with a problem specification other than the first.

The number @n sub 1@ is the total number of compartments other than the output compartment; it must not exceed 9. If the NCOMPARTMENTS option is omitted, this number is taken to be the number of COMPARTMENT clauses that appear in the record (and its continuation records).

The number @n sub 2@ is the number of equilibrium compartments; this number must not exceed @n sub 1@. If the NEQUILIBRIUM option is omitted, this number is computed from the attributes of the COMPARTMENT clauses. If the option is used, however, then the last @n sub 2@ compartments are understood to be equilibrium compartments, whether or not any of these compartments are defined with COMPARTMENT clauses which include the EQUILIBRIUM attribute.

The number @n sub 3@ is the number of explicit (and implicit; see sections C.7-9) basic PK parameters. When an abbreviated code for the PK routine is used, the NPARAMETERS option may be omitted. (When implicit basic PK parameters are defined, this is a convenient practice.) In this case, and in the case of a general linear model, the number of basic PK parameters is the total number of K-type parameters recognized in the abbreviated code. In the case of a general nonlinear model and TRANS1, the number of basic parameters is the larger of (i) the largest subscript used with the P array in PK code, and (ii) the number of variables defined in PK abbreviated code and used in DES and/or AES abbreviated codes when such abbreviated codes are used. See next section C.5.

Each COMPARTMENT clause defines a single compartment. The compartments are numbered in the order in which their defining clauses appear in the record (and its continuation records). The name is the name given to the compartment, 1-8 characters from the FORTRAN character set. If spaces or nonalphanumeric characters are used, enclose the name in double or single quotes. If omitted, the name COMP n is given to the compartment, where n is the compartment number. The compartment name is used in PREDPP problem summary pages and in LINK clauses in the $MODEL record. The name of the output compartment and the attributes of this compartment are set by PREDPP. For the purposes of NM-TRAN, the name of the output compartment is OUTPUT, and its number is 0 or @n sub 1 + 1@, either will do.

Each attribute is one of: INITIALOFF, NOOFF, NODOSE, DEFOBSERVATION, DEFDOSE, EQUILIBRIUM, EXCLUDE. When an attribute is used, it specifies the opposite of the default attribute. The default attributes are: The compartment is initially on, may be turned on and off, may receive a dose, is not the default observation compartment, is not the default dose compartment, is not an equilibrium compartment, is included in the computation for the output compartment. Attributes EQUILIBRIUM and EXCLUDE are used only with ADVAN9, and the attribute NODOSE may be omitted when EQUILIBRIUM is also used, for it is then the default. Definitions for equilibrium compartments must follow the definitions for the nonequilibrium compartments.

If no attributes are used, the parentheses may be omitted. If neither compartment name nor attributes are used, i.e. the clause is simply COMPARTMENT, a compartment is defined where all defaults apply. In this case if the clause does not end the $MODEL record, it must be followed by a comma.

If no compartment has the attribute DEFOBSERVATION, the first compartment defined with the name CENTRAL is given the attribute. If there is no such compartment, the first compartment is given the attribute. If no compartment has the attribute DEFDOSE, the first compartment defined with the name DEPOT and which may receive doses is given the attribute. If there is no such compartment, the first compartment which may receive doses is given the attribute.

The LINK clauses need only be used with general linear models and only when the PK routine is user-supplied. When an abbreviated code for PK is used, this code accomplishes what the LINK clauses otherwise accomplish, and LINK clauses should not be used. A LINK clause defines a route of first-order drug distribution between the compartment A with name @compname sub a@ and the compartment B with name @compname sub b@. These names are established in the COMPARTMENT clauses. A compartment number, rather than a compartment name, can be used. If distribution occurs from A to B, the TO symbol is used. The LINK clause also specifies the internal number given to the rate constant quantifying the first-order distribution. This is the number k following the BY symbol. (It is the number of the row of the GG array where, as a result of basic parameter translation by the TRANS routine, the typical/subject-specific value and @eta@ derivatives for the rate constant can be located; see Guide VI, section III.M.) If distribution occurs in both directions, the AND symbol is used. In this case the number k is the internal number of the rate constant quantifying first-order distribution from A to B, and l is the internal number of the rate constant quantifying distribution from B to A. Both k and l must not exceed @n sub 3@.

K is an alias for LINK. Also, the symbol BY may be coded IS, or =, or omitted. This allows a unidirectional link to be tersely coded as: Knm=k (which is equivalent to LINK n TO m BY k).

Attributes DEFOBSERVATION and DEFDOSE may be abbreviated by initial substrings of length 4 or more.

The example of a $MODEL record given at the beginning of this subsection serves to produce a MODEL subroutine which, along with ADVAN5 or ADVAN7 implementing a general linear model, and the (code generated from the) abbreviated code for PK given in the example of section A, has the same effect as using ADVAN2 and the abbreviated code for PK. The same $MODEL record, without the LINK clauses, may be used along with ADVAN5 or ADVAN7, and a suitable abbreviated PK code, to achieve the same effect; see the example in Appendix VIII. The same $MODEL record, without the LINK clauses, may be used along with ADVAN6, ADVAN8, or ADVAN9, and suitable abbreviated PK and DES codes, to achieve the same effect; see the example in Appendix VIII.

V.C.5. $PK Record

$PK
      abbreviated code

This record gives an abbreviated code for the PK routine. It, along with all its continuation records is called a $PK block

This record is optional. If it appears, it must be with the first problem specification, and only with this problem specification. It must precede any $ERROR records in the problem specification. It cannot be used with a user-supplied MODEL subroutine (and should not be used with a user-supplied TRANS routine; see Guide VI, section III.M).

The basic PK parameters comprise the set of mandatory left-hand quantities. These depend on the ADVAN and TRANS subroutines used.

For any ADVAN among ADVAN1 through ADVAN4 and ADVAN10 (the analytic ADVAN’s), and for any TRANS which may be used with this ADVAN, the basic PK parameters are given in a list with that TRANS in Guide VI, section VII.C. The reserved variables symbolizing these parameters are those whose names are identical to the names used in the list.

For either ADVAN5 or ADVAN7 (the general linear models), and for TRANS1 (which is the only non-user supplied TRANS which may be used with these ADVAN’s), the basic PK parameters are the rate constants. The reserved variable symbolizing the rate constant that quantifies the first-order distribution of drug from compartment number m to compartment number n is Kmn. (See section C.4 for a description of compartment numbering.) The occurence of this variable on the left of an assignment statement or conditional assignment statement establishes the possiblity that this distribution can take place. The variable Km0 may be used instead of Kmn, where n is the number of the output compartment. The rate constants are numbered (these numbers are used internally by the ADVAN) according to the order in which they appear in the abbreviated code. See the first example in Appendix VIII.

For ADVAN6, ADVAN8, or ADVAN9 (the general nonlinear models), and for TRANS1, the reserved array elements symbolizing explicit basic PK parameters are P(1), P(2), etc. The value of the nth element of the P vector passed to DES and AES (see sections C.7-9 and Guide VI, sections VI.C, VI.E) is the value stored in P(n). These values, like other PK-defined items may be displayed; the appropriate labels are described below. Implicit basic PK parameters are discussed in sections C.7-9.

The additional PK parameters comprise a set of optional left-hand quantities. The reserved variables symbolizing these parameters are as follows:

Scaling parameters, bioavailablity fractions, the ouput fraction, and the time scale parameter default to the value 1 if they do not appear in the abbreviated code. Absorption lag parameters default to the value 0 if they do not appear in the abbreviated code.

See section C.4 for a description of compartment numbering. The variable FO or Fn, where n is the number of the output compartment, may be used instead of F0. 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, when this compartment is defined by the ADVAN rather than by a $MODEL record or user-supplied MODEL routine. The variable XSCALE may be used instead of TSCALE. Whichever of the alternate variable names is used first for a basic or additional PK parameter, this name must be used consistently throughout the $PK block.

There is a type of pseudo-statement specific to PK abbreviated code. It has the form CALLFL=n. The different permissible values for n imply different PK calling-protocols.

The value must be -2 when the $BIND record is used.

If the pseudo-statement does not appear, the value -1 is assumed. This allows PK to properly function in most situations.

Values 0 and 1 correspond to call-limiting protocols.†
----------

Limiting calls to PK, when this causes no undesireable effect, can result in a substantial reduction in CPU time. The CALL data item can be used with a call-limiting protocol to override the protocol and force calls with specific event records; see Guide VI, section V.J. When n is 0 or 1, and the data are single-subject data, then PK is called with the first event record of the data set, instead of the first event record of the individual record.

As usual, the label of a data item type can be used as a variable in the abbreviated code. With PREDPP it always refers to the data item in the last data record of an event record. In other words, data items in data records where the CONT data item is 1 are not available as right-hand quantities. When PK is called at a nonevent dose time t, the data item referenced by a given label may refer to the data item on either the dose record or the next event record following t. The defaults are described in section C.2, and a method (using the $BIND record) is given for changing them.

There are several reserved variables and array elements symbolizing special right-hand quantities:

The variable ICALL symbolizes a special right-hand quantity. It has the value 2 if the call to PK is a regular call during data analysis, and the value 4 if the call is a regular call during data simulation. (With verbatim code in the FIRST block (see section IV.I), 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.)

The variable NEWIND symbolizes a special right-hand quantity. It has the value 0 when PK is called with the first event record of the data set. It has the value 1 when PK is called with the first event record of the second or subsequent individual record. It has the value 2 when PK is called with the second or subsequent event record of an individual record. With single-subject data individual records are defined in such a way that event records are contained in a number of different individual records; see section II.C.4.1. Therefore, except when the event record is the first data record of the data set and the value of NEWIND=0, the value of NEWIND can be 1 or 2.

The variable DOSTIM symbolizes a special right-hand quantity. It has a nonzero value only when CALLFL=-2 and PK is being called at a nonevent dose time (see section C.2), in which case the value is this time. DOSTIM should be regarded a random variable when any ALAGn variable is a random variable. In this regard, if any ALAGn is defined as a random variable, it must be defined as such before any occurence of the variable DOSTIM in an assignment statement. When verbatim code is included in the $PK block, the PREDPP read-only common PRCOM2 (see Guide VI, section III.I) is included in the PK routine, so that then @eta@-derivatives of DOSTIM are available.

The array element DOSREC(n) symbolizes a special right-hand qunatity. It has a nonzero value only when CALLFL=-2 and PK is being called at a nonevent dose time, in which case it is the value of the nth data item in the (last data record of the) dose event record describing the dose. A label for a data item in the event record may be used instead of the integer n, e.g. one can use DOSEC(PREP) to symbolize the value of PREP on the dose event record. The $BIND record can also be used to insure that a variable such as PREP symbolizes the value on the dose event record. However, another example of the use of DOSREC, which is sometimes useful and with which the $BIND record cannot help as readily, is the use of DOSREC(TIME) to symbolize the value of TIME on the dose event record, i.e. the time the dose was actually administered.

The abbreviated code may not use certain variables which occur as arguments to the PK subroutine. These variables are: IDEF, IREV, EVTREC, N, INDXS, IRGG, GG, and NETAS. Indeed, unless variables are not listed in common NMPRD4 (see sections III.B.7 and IV.H) in the PK subroutine or in some second subroutine for which an abbreviated code is given, the variables reserved in one routine may not be used in either subroutine. Also, the array elements EPS(1), EPS(2), etc. may not be used in the abbreviated code for PK.

Variables which symbolize (first-, and second-) partial @eta@-derivatives of random variables defined in abbreviated code for PK are generated and displayable. The appropriate labels are the same as those used for the same kinds of derivatives computed in a generated code for PRED; see section IV.F.

Values of the variable P(n) are displayable. For this purpose, they are stored in a variable in common NMPRD4 with name Pm, where m is an integer with 5 digits and equal to n, with leading 0’s if needed (invariably). The values of variables P00..., in particular, are labeled 6... in tables and scatterplots. E.g. The values of variable P00003 are labeled 6003 and are the values of P(3).

If the data are population data, calls to GETETA and SIMETA occur in PK, as they occur in PRED when the $PRED record is used (for some discussion of SIMETA, see section III.B.13), to obtain values for all the @eta@ variables. If @eta@ variables occur in the model used in the ERROR routine, and that routine is user-supplied, the ERROR routine can locate these values in array ETA in common PRRAND. The needed declarations are:

COMMON /PRRAND/ ETA(10),EPS(10)
and if double precision NONMEM is used
DOUBLE PRECISION ETA,EPS

ERROR can either store realizations of the @epsilon@ variables in the EPS array in this common, or elsewhere.

PRED-error recovery (see section IV.G) is supported by PREDPP and NM-TRAN. This means that the EXIT statement described in section IV.G.2, when used in an abbreviated code for PK (or ERROR) generates an quick return to NONMEM with a PRED return code.

V.C.6. $ERROR Record

$ERROR
      abbreviated code

This record gives an abbreviated code for the ERROR routine. It, along with all its continuation records is called a $ERROR block

This record is optional. If it appears, it must be with the first problem specification, and only this problem specification. It must succeed all $PK records in the problem specification.

There is only one mandatory left-hand quantity: the quantity symbolized by Y and described in section IV.A.

There is a type of pseudo-statement specific to ERROR abbreviated code. It has the form CALLFL=n. The different permissible values for n imply different ERROR calling-protocols.

If the pseudo-statement does not appear, the value -1 is assumed.

Values 0 and 1 correspond to call-limiting protocols.†
----------

Limiting calls to ERROR, when this causes no undesireable effect, can result in a substantial gain in CPU time. The CALL data item can be used with a call-limiting protocol to override the protocol and force calls with specific event records; see Guide VI, section V.J. When n is 1, and the data are single-subject data, PK is called only with the first event record of the data set, instead of the first event record of the individual record.

Another call-limiting protocol is implementable, but not with the use of a pesudo-statement in the abbreviated code for ERROR. With this protocol, calls to ERROR are limited to one per problem. This protocol is implemented whenever the abbreviated code consists of only one of the following statements:

Y=F+ERR(1)
Y=F*(1+ERR(1))
Y=F+F*ERR(1)
Y=F*EXP(ERR(1))

or with ETA or EPS occuring instead of ERR. This protocol is not implemented if verbatim code or a pseudo-statement is used in the $ERROR block. (In the last three cases the complete code instructs PREDPP that HH(1) contains @{partial log sp y} over {partial epsilon}@, and so in each case it is sufficient to set HH(1) to 1, and do this once only at an initial problem call to ERROR.)

With any call-limiting protocol, during the Simulation Step, ERROR is called with every event record.

As usual, the label of a data item type can be used as a variable in the abbreviated code. With PREDPP it always refers to the data item in the last data record of an event record. In other words, data items in data records where the CONT data item is 1 are not available as right-hand quantities.

The variable F symbolizes a special right-hand quantity: the value of the scaled drug amount in the observation or other designated compartment (see Guide VI, section V.H) at the event time. In a population study, where @eta@ variables affect the scaled drug amount through their affect on PK parameters, the scaled drug amount is a random variable.

The array elements A(1), ..., A(10) symbolize special right-hand quantities, the amounts in compartments 1 through 10 (including the output compartment). In a population study, where @eta@ variables affect the drug amounts through their affect on PK parameters, these amounts are random variables. If an element A(n) appears, then the variable A cannot also be used. When verbatim code is included in the $ERROR block, the PREDPP read-only common PRCOM4 (see Guide VI, section IV.D) is included in the ERROR routine, so that then the @eta@-derivatives of the compartment amounts are available.

Variables defined in the $PK block can be used in the $ERROR block (unless variables are not listed in common NMPRD4 in either PK or ERROR; see sections III.B.7 and IV.H).

The variable ICALL symbolizes a special right-hand quantity. It has the value 2 if the call to ERROR is a regular call during data analysis, and the value 4 if the call is a regular call during data simulation. (With verbatim code in the FIRST block (see section IV.I), ICALL has the value 1 if the call to ERROR is the first call to ERROR in the problem. At this call, the THETA’s are the initial estimates; the ETA’s are undefined.)

The variable NEWIND symbolizes another special right-hand quantity. It has the value 0 when ERROR is called with the first event record of the data set. It has the value 1 when ERROR is called with the first event record of the second or subsequent individual record. It has the value 2 when ERROR is called with the second or subsequent event record of an individual record. With single-subject data individual records are defined in such a way that event records are contained in a number of different individual records; see section II.C.4.1. Therefore, except when the event record is the first data record of the data set and the value of NEWIND=0, the value of NEWIND can be 1 or 2.

The abbreviated code may not use certain variables which occur as arguments to the ERROR subroutine. These variables are: IDEF, IREV, EVTREC, N, INDXS, G, and HH. Indeed, unless variables are not listed in common NMPRD4 (see sections III.B.7 and IV.H) in the ERROR subroutine or in some second subroutine for which an abbreviated code is given, the variables reserved in one subroutine may not be used in the second subroutine.

Variables which symbolize (first-, second-, mixed-) partial @eta@-derivatives of random variables defined in abbreviated code for ERROR are displayable. They have names D....., where the dots stand for various combinations of 5 digits 0-9. The values of variables D00..., in particular, are labeled 3... in tables and scatterplots. E.g. The values of variable D00123 are labeled 3123. The label for the values of a variable D01..., or higher, is the first four characters of the variable name. E.g. The values of D05677 are labeled D056.

PRED-error recovery (see section IV.G) is supported by PREDPP and NM-TRAN. This means that the EXIT statement described in section IV.G.2, when used in an abbreviated code for PK or ERROR generates an quick return to NONMEM with a PRED return code.

The following discussion, relating to the $ERROR block, supplements that found in section II.C.4.2.

If (i) EPS’s are used in the $ERROR block, or (ii) a $SIGMA record is used, the data are inferred to be population data. If (iii) a $PK record is not used and a $OMEGA record precedes the $ERROR record, the data are inferred to be population data. This is true even if i and ii do not hold, and if ii does not hold, it is assumed that a record

$SIGMA  DIAGONAL(n)

where n is the largest index used with an EPS or ERR in the $ERROR block, might have equivalently been used. If (iv) the NPOPETAS option is used on an $MSFI record with a positive option value, the data are inferred to be poulation data. If neither i, ii, iii, nor iv hold, the data are inferred to be single-subject. See section II.C.4

Suppose a $PK record is not used, a $ERROR record is used, and only ETA’s or only ERR’s occur in the $ERROR block. As a corollary of iii (and comments in sections III.B.10 and IV.A), the following hold:

$OMEGA  DIAGONAL(n)

V.C.7. $DES Record

$DES
      abbreviated code

This record gives an abbreviated code for the DES routine. It, along with all its continuation records, is called a $DES block

This record is optional. If it appears, it must be with the first problem specification, and only this problem specfication. It may not appear when the MODEL routine is user-supplied. Implicit basic PK parameters may be used in the $DES block (see below) only when the $PK block precedes the $DES block.

The mandatory left-hand quantities are the first-order derivatives of the differential equations, symbolized by DADT(n), for the derivative of the amount in compartment n (excluding the output compartment) with respect to time. At least one such array element must be defined.

Symbolic differentiation is used to obtain code used in the generated subroutine to compute the elements of the DA and DP arrays.

The usual right-hand quantities may not be used. The allowable right-hand quantities include: current compartment amounts, symbolized by A(n), for the amount in the nth compartment (including both equilibrium compartments when they exist, but excluding the output compartment); PK parameters (obtained from TRANS1), symbolized by P(m), for the mth parameter; and time, symbolized by T. In a population study, where @eta@ variables affect the PK parameters, and, therefore, also affect the compartment amounts, these right-hand quantities (except for time) should be regarded as random variables. However, @eta@-derivatives are not computed in the generated routine itself. For technical reasons, these right-hand quantities should be regarded as random variables even when the data are single-subject. This means, for example, that these variables should never be used in conditional assignment statements. (Drug input information is not available for computations; PREDPP itself incorporates this type of information appropriately.)

Also, a PK-defined item may be used as a right-hand quantity. However, when so used, it becomes a special quantity called an implicit basic PK parameter and a few special considerations apply:

The symbol COM(n) may be used on the left or the right if n refers to a reserved position in common NMPRD4 (see section III.E.3).

The abbreviated code may not use certain variables which occur as arguments to the DES subroutine. These variables are: IR, DA, and DP. Indeed, unless variables are not listed in common NMPRD4 (see sections III.B.7 and IV.H) in the DES subroutine or in some second subroutine for which an abbreviated code is given, the variables reserved in one subroutine may not be used in either subroutine.

Variables which symbolize partial derivatives of the DA array are displayable. They have names E....., where the dots stand for various combinations of 5 digits 0-9. The values of variables E00..., in particular, are labeled 4... in tables and scatterplots. E.g. The values of variable E00123 are labeled 3123. The label for the values of a variable E01..., or higher, is the first four characters of the variable name. E.g. The values of E05677 are labeled E056.

Variables which symbolize partial derivatives of the DP array are displayable. They have names F....., where the dots stand for various combinations of 5 digits 0-9. The values of variables F00..., in particular, are labeled 5... in tables and scatterplots. E.g. The values of variable F00123 are labeled 5123. The label for the values of a variable F01..., or higher, is the first four characters of the variable name. E.g. The values of F05677 are labeled F056.

Verbatim header statements "FIRST and "MAIN can be used, but they have no effect because section 2 of the generated code is empty.

An example of a $DES record, using implicit basic parameters, is given in Appendix VIII.

V.C.8. $AESINITIAL Record

$AESINITIAL
      abbreviated code

The complete AES routine can be divided into two parts: code which computes the amounts in the equilibrium compartments at the beginning of an integration interval (these amounts depend on the amounts in the nonequilibrium compartments) and code which computes values for the right sides of the algebraic equations. An abbreviated code for AES is actually divided into two abbreviated codes which correspond to the two parts of the complete AES routine. This record gives an abbreviated code for the first part of the AES routine. The $AES record (see the next section C.9) gives an abbreviated code for the second part. The $AESINITIAL record, along with all its continuation records, is called a $AESINITIAL block

This record is optional. If it appears, it must be with the first problem specification, and only this problem specfication. If there are no equilibrium compartments, but ADVAN9 is used, the record need not appear. It may not appear when the MODEL routine is user-supplied. Implicit basic PK parameters may be used in the $AESINITIAL block (see below) only when the $PK block precedes the $AESINITIAL block.

In order to compute the amounts in the equilibrium compartments at the beginning of an integration interval, the algebraic system must be solved. However, only an approximate solution is needed. If requested, this will be used only as an initial solution, and ADVAN9 will numerically obtain a more precise solution.

The amounts in the equilibrium compartments at the beginning of the integration interval comprise a set of mandatory left-hand quantities. They are symbolized by A(n), where n is a number of an equilibrium compartment. At least one such quantity must be defined.

The variable INIT symbolizes an optional left-hand quantity. If it is set to 0, the amounts A(n) are regarded as only approximations to the exact amounts. In this case ADVAN9 solves numerically for more precise amounts satisfying the algebraic equations, using the approximations as an initial solution. If the computation of the amounts in the $AESINITIAL block determines these amounts accurately to at least the number of digits given by the option value of the TOL option in the $SUBROUTINES record, or by NRD or NRD(1) as given with the $TOL record, then INIT should either not be set, or set to 1.

The usual right-hand quantities may not be used. The allowable right-hand quantities include: nonequilibrium compartment amounts at the beginning of the integration interval, symbolized by A(n), for the amount in the nth nonequilibrium compartment; PK parameters (obtained from TRANS1), symbolized by P(m), for the mth parameter; and the time at the beginning of the integration interval, symbolized by T. In a population study, where @eta@ variables affect the PK parameters, and, therefore, also affect the compartment amounts and (if some @eta@ affects an absorption lag parameter) possibly T as well, these right-hand quantities should be regarded as random variables. However, @eta@-derivatives are not computed in the generated routine itself. For technical reasons, these right-hand quantities should be regarded as random variables even when the data are single-subject. This means, for example, that these variables should never be used in conditional assignment statements.

Also, a PK-defined item may be used as a right-hand quantity. However, when so used, it becomes a special quantity called an implicit basic PK parameter and a few special considerations apply:

The symbol COM(n) may be used on the left or the right if n refers to a reserved position in common NMPRD4 (see section III.E.3).

The abbreviated code may not use certain variables which occur as arguments to the AES subroutine. These names are: IR, DA, DP, and DT. Indeed, unless variables are not listed in common NMPRD4 (see sections III.B.7 and IV.H) in the AES subroutine or in some second subroutine for which an abbreviated code is given, the variables reserved in one subroutine may not be used in the second subroutine.

The verbatim header statement "LAST cannot be used. There is no fourth section of generated code.

Any (non-random) variables defined in the $AESINITIAL block may be used in a $AES block (see next section C.9). A random variable defined in terms of PK parameters, but not amounts, may also be used in a $AES block.

V.C.9. $AES Record

$AES
      abbreviated code

The complete AES routine can be divided into two parts: code which computes the amounts in the equilibrium compartments at the beginning of the integration interval (these amounts depend on the amounts in the nonequilibrium compartments) and code which computes values for the right sides of the algebraic equations. An abbreviated code for AES is actually divided into two abbreviated codes which correspond to the two parts of the complete AES routine. This record gives an abbreviated code for the second part of the AES routine. The $AESINITIAL record (see section C.8) gives an abbreviated code for the first part. The $AES record, along with all its continuation records, is called a $AES block

This record is optional. If it appears, it must be with the first problem specification, and only this problem specfication. If there are no equilibrium compartments, but ADVAN9 is used, the record need not appear. It may not appear when the MODEL routine is user-supplied. Implicit basic PK parameters may be used in the $AES block (see below) only when the $PK block precedes the $AES block.

The mandatory left-hand quantities are values of expressions which when set to 0, constitute the system of algebraic equations describing the equilibrium kinetics. They are symbolized by E(n). The number n must be an equilibrium compartment number. However, there need not be any particular relationship between the subscripts and the equilibrium compartments. At least one such quantity must be computed.

Symbolic differentiation is used to obtain code used in the generated subroutine to compute the elements of the DA, DP, and DT arrays.

The usual right-hand quantities may not be used. The allowable right-hand quantities include: current compartment amounts, symbolized by A(n), for the amount in the nth compartment (including all compartments except the output compartment); PK parameters (obtained from TRANS1), symbolized by P(m), for the mth parameter; and time, symbolized by T. In a population study, where @eta@ variables affect the PK parameters, and, therefore, also affect the compartment amounts, these right-hand quantities (except time) should be regarded as random variables. However, @eta@-derivatives are not computed in the generated routine itself. For technical reasons, these right-hand quantities should be regarded as random variables even when the data are single-subject. Also for technical reasons, even time should always be regarded as a random variable, even though time is never actually a randome variable. This means, for example, that these variables should never be used in conditional assignment statements.

Also, a PK-defined item may be used as a right-hand quantity. However, when so used, it becomes a special quantity called an implicit basic PK parameter and a few special considerations apply:

Non-random variables defined in the $AESINITIAL block may be used. A random variable defined in a $AESINITIAL block in terms of PK parameters, but not amounts, may also be used in a $AES block.

The symbol COM(n) may be used on the left or the right if n refers to a reserved position in common NMPRD4 (see section III.E.3).

The abbreviated code may not use certain variables which occur as arguments to the AES subroutine. These names are: IR, DA, DP, and DT. Indeed, unless variables are not listed in common NMPRD4 (see sections III.B.7 and IV.H) in the AES subroutine or in some second subroutine for which an abbreviated code is given, the variables reserved in one subroutine may not be used in either subroutine.

Variables which symbolize partial derivatives of the DA array are displayable. They have names E....., where the dots stand for various combinations of 5 digits 0-9. The values of variables E00..., in particular, are labeled 4... in tables and scatterplots. E.g. The values of variable E00123 are labeled 3123. The label for the values of a variable E01..., or higher, is the first four characters of the variable name. E.g. The values of E05677 are labeled E056.

Variables which symbolize partial derivatives of the DP array are displayable. They have names F....., where the dots stand for various combinations of 5 digits 0-9. The values of variables F00..., in particular, are labeled 5... in tables and scatterplots. E.g. The values of variable F00123 are labeled 5123. The label for the values of a variable F01..., or higher, is the first four characters of the variable name. E.g. The values of F05677 are labeled F056.

The verbatim header statements "FIRST and "MAIN cannot be used.

V.C.10. $TOL Record

$TOL
      abbreviated code

This record can be used to specify tolerances (i.e. accuracies) to which compartment amounts are computed by an ADVAN or SS routine that uses numerical techniques (see Guide VI, section VII). Different tolerances can be specified for the compartment amounts in different compartments. Whereas this record may be needed with ADVAN9, which supports compartment-specific tolerances, it is not needed with all other ADVAN and SS routines, where only a single tolerance applying to all compartments can be specified. In these other cases use of the TOL option on the $SUBROUTINES record suffices.

This record is optional. If it appears, it must be with the first problem specification, and only this problem specfication. It cannot be used when the TOL option is used in the $SUBROUTINES record.

The abbreviated code is very limited and brief; it is not like any other. The only statements that are permitted have one of the two forms

NRD=m
NRD(i)=m

where i is a compartment number (excluding the output compartment number), and m is the number of accurate digits required in the computation of the drug amounts in compartment i. Form 1 is a shorter way of writing form 2 with @i~=~1@.

Once the tolerance for a compartment is explicitly specified, it cannot be respecified. A tolerance for a given compartment need not be specified; see below. The order of the statements is immaterial.

If @i~>~1@ is the least compartment number such that the tolerance for compartment i is not specified, then for all @j~>=~i@, the tolerance for compartment @j@ is the tolerance explicitly specified for compartment @i-1@. This implies that if the only statement used is NRD=m, the number of accurate digits required in the computation of all compartmental drug amounts is m. In this case, as a rule of thumb, one should begin by taking @m@ to be @n+1@ or @n+2@, or with double precision, perhaps to @n+2@ or @n+3@, where @n@ is the option value with the SIGDIGITS option on the $ESTIMATION record. If one succeeds with this setting, one might try increasing @m@ slightly.

If ADVAN9 and SS9 are used together, and if different tolerances are specified for different compartments, only that tolerance specified for compartment 1 is used for the computation of steady-state compartmental amounts. If any ADVAN other than ADVAN9 is used, or if SS6 is used, the tolerances specified for compartments with numbers larger than 1 are ignored, and again only that tolerance specified for compartment 1 is used for the computation of all compartmental amounts.

TOP
TABLE OF CONTENTS