128  Reserved Data Items

Generated from nmhelp plain-text source files (*.dat) of the NONMEM 7.6.0 distribution. These mirror the content presented by nmhelp and complement the formatted Part VIII Help Guide.

1 ADDL DATA ITEM

MEANING: Additional Dose (ADDL) data item for PREDPP

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... ADDL ...

DISCUSSION:

ADDL labels PREDPP’s additional dose (ADDL) data item. The additional dose data item is optional. In a dose or reset-dose event record it describes how many additional doses, exactly like the present (“initiating”) dose, should be given. The interdose interval (II) data item gives the time between the additional doses (See ii).

When ADDL is 0, no additional doses are given.

For non-steady-state doses, ADDL should be a positive number if and only if the II data item is a positive number. II gives the time between additional doses.

For steady-state infusions, ADDL must be 0.

For other steady-state doses, ADDL is optional. If it is a positive number, it continues the pattern of implied doses beyond the steadystate dose. The additional doses of the pattern are non-steady state doses.

With NM75 there is a new way of computing SS, the Empirical method, in which there is no SS data item, and a negative value of ADDL requests the computation. This is described separately. (See empirical_SS). (See Guide Introduction_7 “An Empirical Method of Achieving Steady State”)

For observation, other-type and reset event records, ADDL should be zero.

The following two data record fragments specify the same set of doses:

      TIME   AMT   ADDL   II    DV
      10.    15.   0      0     .
      15.    .     .      .     25.7
      20.    10.   0      0     .
      22.    15.   0      0     .
      34.    15.   0      0     .
      36.    .     .      .     30.2
      TIME   AMT   ADDL   II    DV
      10.    15.   2      12.   .
      15.    .     .      .     25.7
      20.    10.   0      0     .
      36.    .     .      .     30.2

The observation at time 15 and the extra dose at time 20 do not affect the regular dosing regimen (doses at times 10, 22, and 34).

There is a discussion of user (concomitant) data items used to compute PK parameters that are relevant to ADDL doses; (See $BIND).

REFERENCES: Guide VI, section V.K

2 AMT DATA ITEM

MEANING: Dose Amount (AMT) data item for PREDPP

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... AMT ...

DISCUSSION:

AMT labels PREDPP’s dose amount (AMT) data item. The dose amount data item is optional.

AMT must be 0 for non-dose event records.

AMT must be 0 for “steady-state with constant infusion” dose or resetdose event records.

AMT must be a positive number in all other dose or reset-dose event records.

(See dose, steady_state_dose).

REFERENCES: Guide VI, section V.D; Guide V, section 6.8

3 CALL DATA ITEM

MEANING: Call (CALL) data item for PREDPP

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... CALL ...

DISCUSSION:

CALL  labels  PREDPP's  call  (CALL) data item.  The call data item is

optional. It is used to force calls to PK and/or ERROR subroutines with event records for which such calls would not normally occur. (When $PK and/or $ERROR blocks are present, the effect of calling these routines with an event record is to evaluate the $PK and/or $ERROR abbreviated code for that particular event record.)

Values are:

0 (Default) No forced call; PREDPP takes its normal action.

1 Force a call to ERROR with the event record.

2 Force a call to PK with the event record.

3 Force calls to both PK and ERROR with the event record.

10 Call ADVAN9, ADVAN15, or ADVAN17 with the event record. May be
used whether or not the TIME data item is defined. May be combined with values 1, 2, and 3. e.g., CALL = 11 forces calls to ADVAN9, ADVAN15, or ADVAN17 and to ERROR with the event record.

If the PK routine is not called with a given event record, then the basic and additional PK parameters retain the values they had after the last call to PK. This would cause a problem if some parameter depends on an data item whose value is different on the given event record than on the last event record for which PK was called.

If the ERROR routine is not called with a given event record, then NONMEM’s PRED value is a scaled compartment amount. This would cause a problem if the event record is an other-type event which was included in the data set in order to obtain a prediction of (say) a pharmacodynamic effect.

The pattern of calls to ADVAN9, ADVAN15, ADVAN17 depends on the presence or absence of the TIME data item.

If TIME is defined, ADVAN9, ADVAN15, or ADVAN17 is called by default exactly as other ADVAN routines are called: when TIME increases. CALL=10 may be used to obtain additional calls. For example, immediately following a bolus dose event record one might include an othertype event record having the same value of TIME and CALL=10. ADVAN9, ADVAN15, or ADVAN17 is called, and the amounts in the equilibrium compartments are computed based on the amounts in the other compartments.

If TIME is not defined, ADVAN9, ADVAN15, or ADVAN17 is called by default with every event record unless the AES routine specifies the calling protocol “call once per individual record”. In this case, CALL=10 may be used to force calls to the ADVAN routine for records subsequent to the first.

REFERENCES: Guide VI, section V.J; Guide IV, section V.C.1

4 CMT PCMT DATA ITEM

MEANING: Compartment (CMT) and Prediction Compartment (PCMT) data items for PREDPP

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... CMT PCMT ...

DISCUSSION:

CMT and PCMT label PREDPP’s compartment (CMT) and prediction compartment (PCMT) data items. The compartment and prediction compartment data items are optional. They may be used separately or together. Their meanings depend on the particular kind of event record.

Observation Event:
CMT specifies the number of the observation compartment (the compartment whose scaled drug amount appears as F in the error routine). When this number is that of the output compartment, it is allowed to have a negative sign, in which case the output compartment is turned off after F is obtained. This is also the case for an output-type compartment, which is a compartment with attributes INITIALOFF and NODOSE. (With a compartment n which is not the output compartment or an output-type compartment, two records must be used, with the same TIME value: the first with CMT=n and EVID=1 to obtain the observation, and the second with CMT=-n and EVID=2 to turn the compartment off.) By convention, the number of the output compartment may also be given by the CMT data item as the number 1000 (this is true regardless of the type of the event record). With small models (number of compartments <= 99), this number may also be given as 100. With versions of NONMEM prior to 7.3, only small models are possible, and only 100 may be used. When CMT is 0, the default compartment for observations is used. PCMT is ignored.
Dose Event:
CMT specifies the number of the compartment into which the dose is introduced. The dose compartment is turned on if it was previously off. When CMT is 0, the default compartment for doses receives the dose. PCMT specifies the number of the compartment for which an F value is computed. PCMT may be specified as 1000 or 100 to indicate the default compartment for output, similarly to CMT above. When PCMT is 0, the default compartment for observations is used.
Other-Type Event:
A positive value of CMT specifies a compartment to be turned on. A negative value of CMT specifies a compartment to be turned off. When CMT is 0, no change is made in the status of any compartment. PCMT is the same as for dose events.
Reset Event:
CMT is ignored. PCMT is the same as for dose events.
Reset-Dose Event:
CMT and PCMT are the same as for dose events.

Guide V (Introductory Guide) has an example of how urine collections and observations of urine concentration can be described in the data file, along with observations of plasma concentrations. See Chapter 6, Section 9, The Output Compartment: Urine Collections and Observations

REFERENCES: Guide VI, section V.H; Guide V, section 6.9

5 CONT DATA ITEM

MEANING: Continuation (CONT) data item for PREDPP

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... CONT ...

DISCUSSION:

CONT labels PREDPP’s continuation (CONT) data item. The continuation data item is optional. The CONT data item allows a PREDPP event record to span several data records. It is useful when more than NONMEM’s maximum number of data items per record are needed to describe a single event. When the CONT data item is not defined on the $INPUT record, every event record consists of a single data record.

Values are:

0 This is the last or only data record of the event record.

1 This and the succeeding record are both members of the same event
record. MDV must be 1.

PREDPP ignores records having CONT=1, except to pass them to the PK and ERROR routines as part of the complete event record. Values of PREDPP data items such as EVID, AMT, etc., are significant only on the final record of each event record, i.e., on records having CONT=0.

With NM-TRAN abbreviated code, values on data records having CONT=1 are not available for use as right-hand quantities, i.e., abbreviated code cannot reference the values in data records other than the last of each event record. (It would be possible to reference such values using verbatim code, however). When NM-TRAN performs time translation or ii conversion, it does so only for the event records having CONT=0. (See date, time, ii).

REFERENCES: Guide VI, section II , V.A , V.I; Guide IV, section V.B , V.C.5

6 DATE DATA ITEM

MEANING: Date (DATE) data item for NM-TRAN

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... DATE[=DROP] ...

DISCUSSION:

DATE, DAT1, DAT2, and DAT3 are labels for the date data item. The date data item is optional. When it is present, NM-TRAN performs time translation for the time data item (to relative times starting at 0), whether or not any time values contain the character “:”.

The label given to the date data item describes its format:
DATE month day year DAT1 day month year DAT2 year month day DAT3 year day month

When the date represents a calendar date, components are separated by any nonnumeric character, such as - or / (e.g., 12-3-90 or 12/3/90). DATE=DROP should be specified in this case because the NONMEM data set must not contain non-numeric characters.

If only one component is present, it is assumed to be the day (and it may be 0 or negative). If two components are present, they are assumed to be the day and month, and they must not exceed 31 and 12, respectively.

EXAMPLE:

NM-TRAN data set NONMEM data set

      ID     DATE          TIME        ID         TIME
      ----   ----          ----        ----       ----
      1      10-1-86       9:15        1          0.00
      1      10-1-86       14:40       1          5.42
      1      10-2-86       8:30        1         23.25
      2      10-12         8           2          0.00
      2      10-14         10          2         50.00

If present, the year component may consist of one to four digits. The value of NM-TRAN’s LAST20 constant determines the assumed century of one and two digit years: 1900’s or 2000’s (See last20).

REFERENCES: Guide IV, section II.C.2 , III.B.2

7 DEFAULT COMPARTMENT

MEANING: Default compartments for kinetic models with PREDPP

CONTEXT: NONMEM data set

DISCUSSION:

The prediction computed by PREDPP is a scaled drug amount in some compartment called the observation compartment. Every dose is input into some dose compartment.

With every kinetic model there are designated a default observation compartment and a default dose compartment. For some kinetic models, these designations are built into the model definition; for others, these designations are given by the user in the user subroutine MODEL (or in $MODEL abbreviated code).

Unless otherwise specified on an observation event record by means of the compartment data item (CMT), the observation compartment is taken to be the default observation compartment. Unless otherwise specified on a dose event record by means of the compartment data item, the dose compartment is taken to be the default dose compartment.

The models for which default designations are built-in are listed here. The numbers are the compartment numbers.

Model Default dose compartment Default observation compartment

 ADVAN1               1                              1
 ADVAN2               1                              2
 ADVAN3               1                              1
 ADVAN4               1                              2
 ADVAN10              1                              1
 ADVAN11              1                              1
 ADVAN12              1                              2

(See cmt, $model, model).

REFERENCES: Guide VI, section V.H , VI.B , VII.C; Guide IV, section V.C.4

8 DOSE EVENT RECORD

MEANING: Specification of dose for PREDPP

CONTEXT:

$INPUT record and NONMEM data set

DISCUSSION:

PREDPP recognizes two varieties of doses, transient and steady-state. Steady-state doses are described separately (See SS_dose_event). Transient doses are described here.

For a transient dose, the SS data item must be not defined or must be zero. The ADDL data item may be used to specify additional transient doses at regular intervals given by II. The dose is introduced into a dose compartment n, which is defined either explicitly in the event record (by the value n>0 of the CMT data item), or as the default compartment for doses for the particular ADVAN (when the CMT data item is not defined or contains zero).

Absorption lag applies to the initiating dose and to all subsequent additional doses. If an absorption lag parameter is defined by PK for the dose compartment (this parameter is coded ALAGn in abbreviated code) and has a positive value, then the dose is referred to as a “lagged dose” and it is actually introduced into the system at a “lagged time” equal to the time at which the dose would ordinarily be introduced plus the value of the absorption lag parameter. The value of ALAGn in effect at time T applies to the dose and to all subsequent additional doses, even if ALAGn changes value with a subsequent event record.

Bioavailability applies to the initiating dose and to all subsequent additional doses. A bioavailability parameter may be defined by PK for the dose compartment (it is coded Fn in abbreviated code) and must have a positive value. If no such parameter is defined, the bioavailability parameter is assumed to have the value 1. The value of amount in the following discussion is the value of the AMT data item multi-plied by the value of the bioavailability parameter in effect at the time the dose is actually introduced. Changes in the value of Fn at later times have no affect on past doses, e.g., infusions and zeroorder bolus doses that are already in progress are unaffected.

The type of dose is described by the values of the AMT and RATE data items.

AMT   RATE
0 0 Bolus dose.
The dose is introduced into the dose compartment at the event time (before ERROR is called with the event record).
0 >0 Infusion dose (“regular infusion”).
The infusion is started at the event time. Its duration is computed as amount/RATE.
0 -1,-2 Zero-order bolus dose.
Similar to a regular infusion, except that the duration of a regular infusion is specified by information in the dose event record and computed by PREDPP itself, whereas the duration of a zero-order bolus dose is regarded as a parameter which may be modeled and computed by the user’s PK routine or $PK abbreviated code. The infusion is started at the dose event time.
  • If RATE=-2, the duration is computed by PK. The parameter is coded Dn in abbreviated code, e.g., D1 models the duration of zeroorder bolus doses to compartment 1. The duration is given by the value of Dn as computed by PK at the dose event time (or lagged time, if the dose is lagged). Rate is computed as amount/duration and is thus fixed for this infusion, even if the value of Dn changes value with a later event record.
  • If RATE=-1, the infusion rate is computed by PK. The parameter is coded Rn in abbreviated code, e.g., R1 models the rate of zero-order bolus doses to compartment 1. The rate which applies during the advance from a particular state time to a later state time is given by the value of Rn in effect for the the later time, and may change during the course of the infusion. The duration at any state time is computed as amount/rate, where amount represents the remaining dose amount and rate represents the value of Rn at the state time. The infusion continues until the entire dose amount has been introduced into the system.
CAUTION:   If  PREDPP  is used without using NM-TRAN as a preprocessor

then any user-supplied negative values for these data items will be passed to PREDPP. For a discussion of the circumstances such that the data file used by NONMEM and PREDPP is FDATA (in which case NM-TRAN has preprocessed it) or is the file named in the $DATA record, see NONMEM Users Guide, Part IV.

(See multiple dose example, exogenous supplementation example).

REFERENCES: Guide VI, section III.B.2 , V.F , V.G , V.H; Guide V, section 6.8; Guide IV, section III.B.5

9 DV AND MDV DATA ITEMS

MEANING: Dependent Variable (DV) and Missing Dependent Variable (DV) data items for NONMEM

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... DV MDV ...

DISCUSSION:

DV and MDV label NONMEM’s dependent variable (DV) and missing dependent variable (MDV) data items, respectively.

The dependent variable (DV) data item is required by NONMEM. It is the observed value associated with the data record.

The missing dependent variable (MDV) data item is optional. If it is present, then the ID data item must also be present.

Values of MDV are:

0 The DV data item is an observed value, i.e., DV is not missing.

1 The DV data item is not regarded an observed value, i.e., DV is missing. The DV data item is ignored.

100 Same as MDV=0, but this record is ignored during Estimation and Covariance Steps. During other steps, MDV will changed to 0.

101 Same as MDV=1, but this record is ignored during Estimation and Covariance Steps. During other steps, MDV will changed to 1.

Reserved variables MDVI1, MDVI2, MDVI3 can be used to override values of MDV>100. These variables are defined in include file nonmem_reserved_general, which needs to be copied from util to the present run directory so NMTRAN has access to it.

With PREDPP, event records whose types are dose, other-type, reset, or reset-dose (i.e., which have EVID values 1, 2, 3, 4) must all have MDV=1. NM-TRAN will append the MDV data item if PREDPP is used and MDV is not present on the $INPUT record.

(See observation records).

REFERENCES: Guide I, section B.1 , C.4.3; Guide VI, section II , V.A; Guide IV, section III.B.2 , V.B

10 EMPIRICAL SS DOSE EVENT RECORD

MEANING: Specification of empirical steady-state dose for PREDPP

CONTEXT:

$INPUT record and NONMEM data set

DISCUSSION:

With some systems, steady state cannot be computed by the usual methods requested by the SS data item. The Empirical steady state method computes steady state by giving a large number of doses until the state variables no longer change according to the SSTOL/SSATOL tolerance specified in $SUBROUTINES. The SS data item is not used. A negative value of ADDL requests the computation, and also specifies the maximum number of doses (ABS(ADDL)+1). Interdose interval II is used as usual.

Reserved variables ADDL_ACTUAL and ADDL_TIME and ADDL_TIMEDIFF are given useful values.

(See Guide Introduction_7 “An Empirical Method of Achieving Steady State”)

REFERENCES: Guide Introduction_7

11 EVID DATA ITEM

MEANING: Event Identification (EVID) data item for PREDPP

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... EVID ...

DISCUSSION:

EVID labels PREDPP’s event identification (EVID) data item. The event identification data item is required. NM-TRAN can supply this data item if dose and observation events are the only types of events present in the data. EVID can have one of four values in any event record.

0 Observation event. The DV data item is an observation. The CMT
data item specifies which compartment is being observed. Doserelated data items (AMT, RATE, II, ADDL, SS) must be zero.
1 Dose event. The CMT data item specifies which compartment is
being dosed. The DV data item is ignored. One or more of AMT, RATE, II, ADDL, SS data items must be non-zero to define the dose.
2 Other-type event. The DV data item is ignored. Dose-related
data items must be zero. Examples of other-type events are: A compartment is turned on or off (CMT specifies which compartment is to be turned on or off); a prediction is obtained at a specified time so that it may be displayed in a table or scatterplot (PCMT specifies the compartment from which the prediction is obtained); some event occurs at a different time than any observation or dose event, e.g. a covariate such as weight changes, an intervention such as hemodialysis is started or stopped.
3 Reset event. The kinetic system is re-initialized. Time is
reset to the time of the event record, the amounts in each compartment are reset to zero, the on/off status of each compartment is reset to its initial status. The DV data item is ignored. Dose-related data items must be zero.
4 Reset-and-dose event. The system is first reset, and then a dose
is given. The DV data item is ignored.

With NONMEM 7, there is a change in the value of EVID under the following circumstances: 1) NMTRAN is appending EVID 2) The record is not a dose event (AMT, RATE, SS = 0) 3) MDV is present in the data set (i.e., was listed on $INPUT) 4) MDV is 1 or MDV is 101

Previous versions of NMTRAN always set EVID=0 (observation) when the record was not a dose event. NMTRAN will now set EVID=2 (Other-type event) for this case. Note that if the user supplies both EVID and MDV, there is no change. Similarly, if the user supplies neither EVID nor MDV, so that NMTRAN is appending both of them, there is no change. There is only a change when the user supplies MDV but not EVID, and has set MDV=1 or MDV=101 for non-dose records.

With NONMEM 7.2 and higher, the “Repeated Observation Records” feature exists to assist in specialized methodologies such as stochastic differential equations. A record in a data file may be set up for repeated calls to PK and ERROR. Each time, the same record is passed to PK and/or ERROR, but with a different EVID. The user’s control stream model in $PK or $ERROR may then take advantage of executing certain code conditional on the EVID value. For this to occur, the user must introduce one or more of the following data items in the data file, with these names:

XVID1 XVID2 XVID3 XVID4 XVID5

These stand for “extra” EVIDs. On the first call to PK/ERROR, the EVID is set to the value given in XVID1. On the second call, the EVID is set to that in column XVID2, etc. up to XVID5. Only as many XVIDs as are required are needed to be defined. All the other items in the record do not change, except that if the present EVID used is not 0, then the MDV value is set to 1 for that call. If an XVID is -1, then the call to PK/ERROR for that XVID is not made, nor for the remaining XVIDs. If there is an EVID column, the value in this column is not passed to PK/ERROR unless XVID1=-1 in which case a “normal” call with that record occurs. (See stochastic differential equation example)

REFERENCES: Guide IV, section V.B; Guide VI, section V.B

12 FINISH

MEANING:

FINISH record

CONTEXT: NM-TRAN and NONMEM data sets

USAGE:

FIN

DISCUSSION:

A FINISH record signals the end of the data for a given NONMEM problem. It is always optional.

FINISH record in NM-TRAN data sets:

When the RECORDS option of the $DATA record is omitted, NM-TRAN reads the data set to a FINISH record or to end-of-file, whichever comes first.

When a format is omitted on the $DATA record, a FINISH record consists of the characters FIN appearing anywhere in the record (the other characters are all blank).

When a format is provided on the $DATA record, a FINISH record must have the same form as in NONMEM data sets.

FINISH record in NONMEM data sets:

When Fields 3 and 6 of the NONMEM DATA Control Record are blank or zero, NONMEM reads the data set to a FINISH record or to endof-file, whichever comes first. (Field 3 and 6 either contains the number of data records or are blank or zero. They must be blank or zero when the number of records is greater than 99999999.)

The format of the FINISH record is:

Blank characters in positions 1-76 and 80 and the characters F, I, and N in positions 77, 78, and 79, respectively.

If m is the number of FORTRAN records spanned per data record, there must be m-1 blank FORTRAN records inserted before the FINISH record.

In addition, the following three rules must be followed:

All FORTRAN records of the input data file must be 80 characters long.

All FORTRAN records of the input data file except the FINISH record must have blank characters in positions 77-80.

The total number of A, E, and F codes on the FORMAT record, including their multiplicities, must equal, not exceed, the number of data items specified on the DATA record.

REFERENCES: Guide II, section D.2.3; Guide IV, section III.B.5

13 ID .ID. AND L1 DATA ITEMS

MEANING: Identification (ID) data item for NONMEM

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... ID ...

DISCUSSION:

ID, .ID. and L1 are labels for NONMEM’s identification data item.

ID The observations in the data set are divided into groups called
level-one observations. These groups may have different sizes. Level-one observations are treated as being statistically independent multivariate observations. Because there can be at most one scalar observation on any data record, the identification (ID) data item is used to group together the data records containing the scalar observations comprising a level-one observation. Using NM-TRAN, the identification data item is given the label ID in the $INPUT record. A contiguous set of data records with the same value of ID are collectively called an individual record (also called an L1 record), and this record “contains” one level-one observation. A change in ID value indicates the start of a new individual record. When every level-one observation consists of a single scalar observation, so that the entire level-one observation can be contained in a single data record, ID data items are not generally required. However, they are always required when the data are population data and PREDPP is used.
.ID. When the data are single-subject data and PREDPP is used, NM-TRAN
automatically generates the ID data items and provides the label .ID. for the NONMEM control stream. (Or if L2 data items appear, these are taken to be the ID data items.) If the ID label is given in the $INPUT record, NM-TRAN ignores it, and it also ignores the data items associated with this label.
L1 Using NM-TRAN, the identification data item may be given the
label L1 in the $INPUT record. Use of L1 as a label or synonym (e.g. ID=L1) in the $INPUT record specifies that the associated data items are to be used as the identification data items and, if the data are single-subject data, the automatic generation of the identification data items is suppressed.

REFERENCES: Guide I, section B.1; Guide IV, section II.C.4 , III.B.2

14 II DATA ITEM

MEANING: Interdose Interval (II) data item for PREDPP

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... II ...

DISCUSSION:

II labels PREDPP’s interdose interval (II) data item. The interdose interval data item is optional. In a dose or reset-dose event record it gives the time between implied or additional doses (i.e., for repeated doses with a given period, the II data item is this period).

For a steady-state infusion (AMT=0; RATE>0), II should be 0.

For other steady-state doses, II should be a positive number. II gives the time between implied doses.

For non-steady-state doses, II should be a positive number if and only if the ADDL data item is a positive number. II gives the time between additional doses.

For observation, other-type, and reset event records, II should be zero.

The units of II should be consistent with those of TIME.

Any II value in the NM-TRAN data set that contains a colon (:) is assumed to be a clock time (hh:min) and NM-TRAN converts it (to hh.fr) as in the first example:

NM-TRAN data set NONMEM data set II II —- —- 1:30 1.50 1.30 1.30

The $DATA record may include the option TRANSLATE=(II/24), in which case all interdose interval data items (obtained after clock time conversion) are divided by 24. (See $data).

(See exogenous supplementation example).

REFERENCES: Guide VI, section V.G; Guide IV, section V.B

15 L2 DATA ITEM

MEANING: Level Two (L2) data item for NONMEM

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... L2 ...

DISCUSSION:

L2 labels level-two (L2) data items. The level two data item is optional.

Recall that the ID data item is used to group together the data records containing observations which have the same realization of the level-one random effects (etas). Similarly, the L2 data item is used to group together the data records containing observations which have the same realization of the level-two random effects (epsilons). The observations of such a group is called a level-two observation. The group itself is called a level-two (L2) record. Data records of an L2 record must be contiguous (and contained within the same individual record). By default, level-two observations are treated as being statistically independent multivariate observations. (However, within a level-one observation, the level-two random effects can be made to be correlated between level-two observations.)

Here is an example of a fragment of a data set using L2 data items. There are two types of observations, designated by the two different values of the user data item TYPE. Note that the L2 data items are the same for both of the observations at TIME=2, and they are also the same for both of the observations at TIME=112.5.

      ID   TIME    AMT   APGR     WT     DV TYPE L2
       1    0.    25.0    1.4      7      .   .   1
       1    2.0      .    1.4      7    6.0   1   1
       1    2.0      .    1.4      7   17.3   2   1
       1   12.5    3.5    1.4      7      .   2   2
       1   24.5    3.5    1.4      7      .   2   2
       1   37.0    3.5    1.4      7      .   2   2
       1   48.0    3.5    1.4      7      .   2   2
       1   60.5    3.5    1.4      7      .   2   2
       1   72.5    3.5    1.4      7      .   2   2
       1   85.3    3.5    1.4      7      .   2   2
       1   96.5    3.5    1.4      7      .   2   2
       1  108.5    3.5    1.4      7      .   2   2
       1  112.5      .    1.4      7    8.0   1   2
       1  112.5      .    1.4      7   31.0   2   2

When the data are single-subject and the L2 data item is defined to NM-TRAN in a $INPUT record, the ID data item is taken to be the L2 data item. The ID item may be defined, but then it is not in turn identified to NONMEM as such. The labels L2 and ID (if defined) may be used in abbreviated code, and then they refer to the corresponding items of the data record, as specified in the $INPUT record. However, if the user uses the label L1 instead of the label ID, or uses the label L1 as a synonym with the ID label, then NM-TRAN does not change the designations: For NONMEM, the items labeled L1 are taken to be the ID data items, and the items labeled L2 are taken to be the L2 data items.

REFERENCES: Guide II, section D.3.3; Guide V, section 12.4.2 , 12.5

16 MRG_ DATA ITEM

MEANING: Marginal (MRG_) data item

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... MRG_ ...

DISCUSSION:

MRG_ labels NONMEM’s marginal (MRG) data item. The marginal data item is optional. With a nonobservation record (i.e. MDV=1 or MDV=101), it controls the definition of the value of the PRED item associated with the record. Basically, 0 means the PRED item is the typical value of F, and 1 or 2 means it is the expectation of F. (Note that with NM-TRAN, F is defined by Y.) However, the marginal data item also controls the definition of the value of any PRED-defined item D that is displayed in a table or scatterplot (except items stored in the SAVE region) and associated with the record.

Values are:

0 The PRED item is the typical value of F and a displayed item D is
either the typical value of the variable D or, if conditional estimates are requested, the conditional estimate of the variable D.
1 or 2
The values of the PRED and D items are determined by other things: If the Simulation Step is implemented, and ONLYSIMULATION is specified, the PRED item is the simulation expectation of F, over the simulated values of eta for all the individuals in the data set (including those individuals with no observation records), and the D item is the simulation expectation of the variable D. If conditional estimates are obtained (e.g., using the POSTHOC option), the PRED item is the posterior expectation of F, over the conditional estimates of eta for all individuals in the data set (that have some observation records), and the D item is the posterior expectation of the variable D. Otherwise, the PRED and D items are as with METHOD=0. If the expectation is the posterior expectation:
  • If MRG_=1, the deletion adjustment is not used.
  • If MRG_=2, the deletion adjustment is used. With the deletion adjustment, the posterior expectation for a given individual is obtained by not including in the computed expectation the value of the variable evaluated at the conditional estimate of his eta.

With MRG_=1 or 2, MDV must also be 1 or 101. This use of MDV=1 does not prevent, as would ordinarily happen, the DV or RES items from being plotted.

A plot of PRED (and of any PRED-defined item not stored in the SAVE region) will only include points from records with MRG_=1, unless one explicitly partitions on MRG_.

If PREDPP is used and NM-TRAN generates MDV, MDV is set to 1 if MRG_ is 1 or 2. If PREDPP is used, NM-TRAN sets MRG_ to 0 (if it is not already 0) when EVID is not equal to 0. LP

Warning: If PREDPP is used and NM-TRAN generates EVID, it sets EVID=2 for records with MDV=1 and no dosing information. This causes MRG_ to be set to 0. When MRG_ is used, the data set should include MDV and EVID data items. The values should be MDV=1 and EVID=0 when MRG_>0.

(See expectation example, expectation block).

REFERENCES: none

17 RATE DATA ITEM

MEANING: Dose Rate (RATE) data item for PREDPP

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... RATE ...

DISCUSSION:

RATE labels PREDPP’s dose rate (RATE) data item. The dose rate data item is optional. In a dose or reset-dose event record it can take four kinds of values.

0 The dose is an instantaneous bolus dose.

0 The dose is an infusion, and the value of RATE gives its rate.
If this is not a steady-state infusion, the AMT data item must be positive also. If this is a steady-state dose event record, both AMT and RATE may be 0; (See ss dose).
-1 The dose is a zero-order bolus dose, i.e., an infusion, whose
rate is modeled in the PK routine. As an example, suppose the compartment being dosed is numbered 1 (e.g., the CMT data item contains 1, or it contains 0 and compartment 1 is the default compartment for doses). The $PK abbreviated code must define a value for R1, the rate parameter for compartment 1, e.g., R1=THETA(4)+ETA(4)
-2 The dose is a zero-order bolus dose, i.e., an infusion, whose
duration is modeled in the PK routine. As an example, suppose the compartment being dosed is numbered 1 as above. The $PK abbreviated code must define a value for D1, the duration parameter for compartment 1, e.g., D1=THETA(4)+ETA(4)

RATE must be 0 for observation, other-type, and reset event records.

(See dose, steady_state_dose).

REFERENCES: Guide VI, section V.E; Guide V, section 6.8

18 RAW_ DATA ITEM

MEANING: Raw-data (RAW_) data item

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... RAW_ ...

DISCUSSION:

RAW_ labels NONMEM’s raw-data (RAW) data item. The raw-data data item is optional. With a nonobservation record (i.e. MDV=1) it controls the definition of the value of the DV item associated with that record that appears in tables or scatterplots (whereas without the raw-data item, this DV item is the one in the original data set). Basically, 0 means the displayed DV item is that in the original data set, and 1 means the DV item is the raw-data-average of original DV items.

Values are:

0 The data record is not a template record.

1 The data record serves as a template record, aiding in the defi-
nition of the (particular) raw-data-average. The DV and RES items become the raw-data-average and the difference between this average and the PRED item, respectively. The average is over all observations in all other data records with user-defined data items matching (i.e. equal to) those occurring in the template record. (A user-defined data item is a data item not recognized by NONMEM, i.e., not one of ID, L2, DV, MDV, RAW_, MRG_, REPL_. It may be a PREDPP data item. Specific user-defined data item types may be excluded from the match; see the $OMIT record.) The average is a two-stage average; it is the average of within-individual averages. Any PRED-defined item stored in the SAVE region and displayed in a table or scatterplot is handled as is the DV item; it too is replaced by an average of the corresponding PRED-defined items obtained with observation records. Thus, several different rawdata-averages can be defined (using the same template).

With RAW_=1, MDV must also be 1 or 101. This use of MDV=1 does not prevent, as would ordinarily happen, the DV or RES items from being plotted.

A plot of DV, RES (and of any PRED-defined item stored in the SAVE region) will only include points from records with RAW_=1, unless one explicitly partitions on RAW_.

If PREDPP is used and NM-TRAN generates MDV, MDV is set to 1 if RAW_ is 1. If PREDPP is used, NM-TRAN sets RAW_ to 0 (if it is not already 0) when EVID is not equal to 0.

Warning: If PREDPP is used and NM-TRAN generates EVID, it sets EVID=2 for records with MDV=1 and no dosing information. This causes RAW_ to be set to 0. When RAW_ is used, the data set should include MDV and EVID data items. The values should be MDV=1 and EVID=0 when RAW_>0.

(See data average example, data average block).

REFERENCES: none

19 REPL_ DATA ITEM (NM75)

MEANING: Replication (REPL_) data item

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... REPL_ ...

DISCUSSION:

REPL_ labels NONMEM’s replication (REPL_) data item. The replication data item is optional. When the REPL_ data item is listed in $INPUT, the NONMEM data set is considered to be a template data set. NONMEM itself replicates subjects from the template data set at the start of the problem to create an expanded NONMEM data set.

(Note that the NONMEM data set is typically the file FDATA generated by NM-TRAN, unless there is nothing for NM-TRAN to change and the format is supplied on the $DATA record, in which case the file named on the $DATA record is the NONMEM data set. See NONMEM Users Guide, Part IV.)

The value of REPL_ is the replication number for that subject. If the value is fractional, it will be truncated to the nearest integer. Only the REPL_ value of the first record of each individual will be used to determine its replication number. If for some subject the value of REPL_ is 0, the subject is deleted from the NONMEM data set.

REPL_ may be used with the $DATA … REPL option, which replicates the entire data set REPL=n times. If both are used the REPL_ data item applies first, and the REPL option applies second. See REPL option of $DATA record. The REPL option and REPL_ data item are meant to be used with $SIMULATION or $DESIGN. For important information, see Guide Introduction_7 Section $DATA REPL

REFERENCES: Guide Introduction_7

20 RPT_ DATA ITEM

MEANING:

REPEAT (RPT_) data item

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... RPT_ ...

DISCUSSION:

RPT_ labels NONMEM’s repeat data item. The repeat data item is optional. It is used as an alternative way to mark a data record as a repetition base. (For another way of doing this, global “Repetition Variables” RPTI,RPTO,RPTON,PRDFL may be used.)

Permissible values of RPT_ are:

0 The data record is not a repetition base.

n (n between 1 and 5)
The data record is marked as a “repetition base with value n”, i.e. as the first of a series of contiguous records of the current individual record (with single-subject data, contiguous records of the data set) which may be repeated. See repeatf.ctl in the examples directory.

(See Repetition_Variables).

REFERENCES: none

21 SS DATA ITEM

MEANING: Steady-State (SS) data item for PREDPP

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... SS ...

DISCUSSION:

SS labels PREDPP’s steady-state (SS) data item. The steady-state data item is optional. It can take one of three values in any event record.

0 indicates that the dose is not a steady state dose.

1 indicates that the dose is a steady state dose, and that the com-
partment amounts are to be reset to the steady-state amounts resulting from the given dose. Compartment amounts resulting from prior dose event records are “zeroed out,” and infusions in progress or pending additional doses are cancelled. The system is not totally reset: the on/off status of the compartments remains as it was at the time of the prior event record (if any), and the value of time must be greater than or equal to its value on the prior event record (if any).
2 indicates that the dose is a steady state dose and that the com-
partment amounts are to be set to the sum of the steady-state amounts resulting from the given dose plus whatever those amounts would have been at the event time were the steady-state dose not given. I.e., letting t be the time on the event record, then the amounts in the compartments are updated to amounts valid for time t, and next, these amounts are added to the steady-state amounts. This is meaningful when kinetics are linear and the superposition principle holds.
3 indicates that the dose is a steady state dose. SS = 3 is iden-
tical to SS = 1 with one exception: with Steady State routines SS6 and SS9, the existing state vector (compartment amounts and eta derivatives) is used as the initial estimate in the computation of the steady-state amounts. The user supplies the initial estimate with some combination of prior event records, e.g., reset, transient dose, and other-type event records.

When the SS data item is used, one or more of the data items AMT, RATE, and II must be present in the event record to specify the steady state dosing pattern.

REFERENCES: Guide VI, section V.F; Guide V, section 6.8

22 SS DOSE EVENT RECORD

MEANING: Specification of steady-state dose for PREDPP

CONTEXT:

$INPUT record and NONMEM data set

DISCUSSION:

PREDPP recognizes two varieties of doses, transient and steady-state. Transient doses are described separately (See dose_event). Steadystate doses are described here.

(With NM75 there is a new way of computing SS, the Empirical steady state method, in which there is no SS data item, and a negative value of ADDL requests the computation. This is described separately.) (See empirical_SS). (See Guide Introduction_7)

A steady-state dose is a dose that is imagined to be the last of a series of implied doses, each exactly like the dose in question, given at a regular interval specified by the II data item and leading to steady-state by the time the steady-state dose is given.

For steady-state doses, the SS data item must be defined and positive (See ss_data_item).

The ADDL data item may be used on the SS dose event record to specify additional transient doses after the steady-state dose, given at the interval II.

The CMT data item (See cmt) applies to steady-state doses as to transient doses.

PK parameters absorption lag (ALAGn), bioavailability (Fn), modeled rates (Rn) and modeled durations (Dn) apply to steady-state doses as they do to transient doses, except as noted.

When absorption lag applies, it is understood to apply to all implied doses. Steady-state is computed as if there were no ALAG, and then there is an advance to the appropriate point in the steady-state cycle (II-ALAG). See Guide VI, Section V.F.4, Note 4

MTIME parameters do not apply to steady-state doses. See Guide VI, Section V.F.4, Note 3

When bioavailability applies, it is understood to apply to all implied doses.

Values of AMT, RATE, II data items:

AMT   RATE      II

0 0 >0 Steady-state with multiple bolus doses.

0 >0 >0 Steady-state with multiple infusions.
The final infusion is started at the event time of the SS dose record and continues beyond its event time. (More than one infusion continues when the duration of the steady-state infusion is greater than II.)
0 -1,-2 >0 Steady-state with multiple zero-order bolus doses.
The final infusion is started at the event time of the SS dose record and continues beyond its event time. (More than one infusion continues when the duration of the steady-state infusion is greater than II.)
0 0,>0,-1 0 Steady-state with constant infusion.
The infusion terminates at the event time of the SS dose record. The ADDL data item cannot be used to specify additional transient doses. Doses with rate 0 are useful when the differential equations coded by the user explicitly provide for endogenous drug production. (The Initial Steady State feature (I_SS) may be specified in the model instead of using a steadystate dose record with rate 0.)

REFERENCES: Guide VI, section V.F; Guide V, section 6.8

23 TIME DATA ITEM

MEANING: Time (TIME) data item for PREDPP

CONTEXT:

$INPUT record and NONMEM data set

USAGE:

$INPUT ... TIME ...

DISCUSSION:

TIME labels PREDPP’s time (TIME) data item. The time data item is required with PREDPP. (An exception occurs with ADVAN9, ADVAN15, and ADVAN17 when there are only equilibrium compartments, in which case the time data item is optional.) However, even when PREDPP is not used, a time data item has a special meaning to NM-TRAN; see below.

With PREDPP, the time data item gives the time of the event, the “event time.” With NONMEM 7.4, time data items may be negative; with earlier versions, time data items must be non-negative. Event records must be ordered within an individual record so that time does not decrease, i.e., so that time on any record other than the first is greater than or equal to time on the prior record. Exceptions are the event times of reset and reset-and-dose events, where the time may be any number.

With or without PREDPP, if any time data item in the NM-TRAN data set contains a colon (:), then all time data items are assumed to be clock times (hh:min), and NM-TRAN translates all times to relative times (hh.fr) starting at time 0. Specifically, the time of the first data record of an individual record (if the data are population data) or the first data record of the data set (if the data are single-subject data) is set to 0. Subsequent times in the NONMEM data set are calculated relative to that time. (See date data item).

Example:

NM-TRAN data set NONMEM data set TIME TIME —- —- 8:00 0. 14:45 6.75 14.75 6.75

NM-TRAN permits negative clock times.

The $DATA record may include the option TRANSLATE=(TIME/24), in which case all relative times (obtained after clock time conversion) are divided by 24. (See $data).

REFERENCES: Guide VI, section V.C; Guide IV, section II.C.2 , III.B.2