51 Reserved Data Items

Reserved data items used in NONMEM data sets.

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 steady-state 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 Section 50.5).

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 reset-dose 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 other-type 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 DATA_AVERAGE BLOCK

MEANING: Abbreviated code for computation of raw-data-averages

CONTEXT: Abbreviated code

SAMPLE:

$ERROR

IF (ICALL == 6) THEN
 ... data average block ...

ENDIF

DISCUSSION:

A data average block is a block of abbreviated code that is only executed when ICALL=6. This value of ICALL occurs when the raw-data-average (RAW_) data item is defined in the data set and has a non-zero value for some records. Data average blocks are not required when the raw-data-average data item is present, but they allow the user additional functionality. Such blocks may be present in $PRED and $ERROR. If for a given observation record matching a template record, a data average block sets the DV variable to a value different from the one in the record, this value is the one included in the average.

In this example, the displayed DV value for each template record is the proportion of DV items greater than 10 on those records matching the template record.

Y = ...
TRDV = DV
IF (ICALL == 6) THEN

 DV = 0
 IF (TRDV > 10) DV = 1
ENDIF

PRED may return a value of 1 in F, indicating that the DV item in the record is not to be included in the average. Continuing the above example, suppose that the DV variable is set to a value only when it exceeds 2, so that the average is the proportion of observations exceeding 10 among those that exceed 2. The code is as follows. See note 2 below on the returned value of F.

Y = ...
TRDV = DV
IF (ICALL == 6) THEN
 IF (TRDV <= 2) Y = 1
 DV = 0
 IF (TRDV > 10) DV = 1
ENDIF

When ICALL=6, PRED and ERROR are called with successive records as usual. However, with each observation record, all output from these routines other than a value set for the DV data item and values set for PRED-defined (ERROR-defined) items V used in a table or scatterplot and located in the SAVE region (See save_region) (and the F value, in so far as it is or is not 1) is ignored. In the same way that an average is formed for the DV, averages are formed for the elements of V. Upon entry into PRED or ERROR with a given record, the value of the DV item is the one on the record, and the values for V are the values that will be used in a table and/or scatterplot. If PRED or ERROR changes one of these values, the new value is the one used in the average. If a value is not changed, the unchanged value is used in the average. (For a nonobservation record, the output from that record is completely ignored.)

The following series of examples concern taking averages of PRED-defined items. They involve a mixture model, where, under each of the subpopulations, there is a parameter PA whose value depends on an eta. There is a template record.

Example A.

Suppose first that PA does not depend on (interindividually-varying) covariate values. Suppose moreover, that during copying passes, with each individual record a value of the quantity Q=P1*PA1+P2*PA2+P3*PA3 has been computed and stored in the SAVE region. Here, the P’s are the mixture probabilities, and the PA’s are conditional estimates of PA under the different models for the different subpopulations. Due to the presence of the template record, at ICALL=6, the average of Q across the eta estimates (from individuals with the same covariate values as are contained in the template record) will be computed - without any need for a data average block. More precisely, at ICALL=6 a pass through the data set occurs, during which a value of Q is obtained with each of the observation records that match the template record. However, the average of the Q values is an average of within-individual averages, and since Q does not vary within an individual record, the within-individual average computed for that record is the same value of Q as is obtained with each of the observation records of the individual record (matching the template record). The resulting average of the Q values is an estimate of the expected value of PA over the subpopulations and the randomly-varying PA’s.

Example B.

Suppose that PA depends on a covariate X E.g. PA=THETA(1)*X**THETA(2)*EXP(ETA(1)), and that one is interested in an estimate of the expected value of PA for X=x. Suppose also that the value for X in the template record is x. Once again, suppose that during copying passes, with each individual record a value of Q has been computed and stored in the SAVE region - using whatever value of X appears in the individual record. At ICALL=6, if and only if the observation records within an individual record have the value X=x and match the template record with respect to the other relevant data items, will the within-individual average be included in the average Q. Moreover, these observation records are the very ones whose value for Q is of interest.

Example C.

However, under a well-specifed model, ETA(1) should be independent of X, and so one might want to use an average of Q across the eta estimates from all individuals (with observation records). Then one might (i) during copying passes, for each individual record compute Q using the specific value X=x - regardless of what value of X appears in the individual record, and (ii) include the record

$OMIT X

to prevent the values of X from affecting the match with the template record.

Example D.

The strategy in example C fails if it is necessary to match on X for the purpose of forming averages other than the average Q, and it is at least awkward if one is interested in the expected value of PA for a variety of values of X. Here is an alternative strategy.

$ABB COMRES = 4 COMSAV = 4

$ERROR
...
Y = ...

IF (COMACT == 2) THEN
 IF (MIXNUM == 1) COM(1) = ETA(1)
 IF (MIXNUM == 2) COM(2) = ETA(2)
 IF (MIXNUM == 3) COM(3) = ETA(3)
ENDIF

IF (ICALL == 6) THEN
 PA1 = THETA(1) * TEMPLT(X)**THETA(2) * EXP(COM(1))
 PA2 = THETA(1) * TEMPLT(X)**THETA(2) * EXP(COM(2))
 PA3 = THETA(1) * TEMPLT(X)**THETA(2) * EXP(COM(3))
 COM(4) = MIXP(1) * PA1 + MIXP(2) * PA2 + MIXP(3) * PA3
ENDIF

$TABLE COM(1) COM(2) COM(3) NOPRINT FILE = junk
$TABLE ID ... COM(4) ...

During the copying passes, the values of the eta estimates are stored (in items COM(1), COM(2) and COM(3) of the SAVE region) rather than the value of Q. The first table record appears because unless the items COM(1), COM(2), and COM(3) are displayed, at ICALL=6 their values are 0. TEMPLT(X) refers generically to the value of X on the template record (See Special Rule 4 below); so there can be numerous template records with different values of X.

Example E.

Examples A-C are not explicit about how the mixture probabilities are computed. They might be obtained via MIXP, in which case during the copying passes (similar to what happens at ICALL=6 with example D), with a given individual record, they are the probabilities pertaining to that record. As long as the mixture probabilities do not depend on interindividual-varying covariates, the mixture probabilities are the same no matter what individual record it is to which they pertain. But if the probabilities depend on interindividual-varying covariates, and especially if one wants to estimate the expected value of Q for numerous different sets of values for these covariates, then one might use:

$ERROR
include nonmem_reserved_general

Y = ...

IF (COMACT == 2) THEN
 IF (MIXNUM == 1) COM(1) = ETA(1)
 IF (MIXNUM == 2) COM(2) = ETA(2)
 IF (MIXNUM == 3) COM(3) = ETA(3)
ENDIF
IF (ICALL == 6) THEN
 PA1 = THETA(1) * TEMPLT(X)**THETA(2) * EXP(COM(1))
 PA2 = THETA(1) * TEMPLT(X)**THETA(2) * EXP(COM(2))
 PA3 = THETA(1) * TEMPLT(X)**THETA(2) * EXP(COM(3))
 COM(4) = MIXPT(1) * PA1 + MIXPT(2) * PA2 + MIXPT(3) * PA3
ENDIF

The mixture probabilities found in MIXPT pertain to the individual record containing the template record (See Special Rule 7 below). Because they have been computed using the covariate values in that record, they are commensurate with the way PA has been computed for the different subpopulations. With versions prior to NONMEM 7.3, the probabilities in MIXPT must be referenced via verbatim code (note the double quotes).

$ERROR
" USE ROCM_REAL MIXPT=>MIXP_RAW

...
" COM(4) = MIXPT(1) * PA1 + MIXPT(2) * PA2 + MIXPT(3) * PA3

Special rules apply to data average blocks and passes through the data with ICALL=6.

No eta derivatives are computed in a data average block.
A RETURN statement may be used in a data average block. If Y= appears (i.e. Y is assigned a value) in a data average block before the RETURN (not necessarily in the same block containing the RETURN), then F is set to Y (F=Y); otherwise F is set to 0 (F=0). If there is no RETURN statement in a data average block, then as usual, F is set to the value of Y assigned by the time PRED (ERROR) exits.
Loops are permitted in a data average block. The syntax is as follows.

DO WHILE (condition)
 .. statements ..

END DO

During calls with ICALL=6, the template data record is found in NONMEM global variable TEMPLT. Items in the template data record may be referred to in abbreviated code of the data average block by position or by label, e.g., TEMPLT(1) or TEMPLT(ID).
During calls with ICALL=6, the repetition feature may not be used.
If a mixture model is used, then during calls with ICALL=6, both MIXNUM and MIXEST are the index of the subpopulation into which the individual (whose data record is being passed) has been classified.
If a mixture model is being used, then during calls with ICALL=6, (the final estimates of) the mixture probabilities associated with the individual record containing the template record are found in NONMEM global variable MIXPT. Code that uses these probabilities must be verbatim code.

(See raw_). (See Section 53.48) (See Section 53.54).

REFERENCES: None.

7 DATA_ITEMS

MEANING: The elements of a NONMEM Data Record

CONTEXT: NONMEM output

DISCUSSION:

Each data record consists of a series of data items, the labels for which are defined on the $INPUT record. Data items are of three types: NONMEM items, PREDPP items, and others. The first two types are signified by certain reserved labels, such as (for NONMEM items): ID (for IDentification), MDV (for Missing Dependent Variable), or DV (for Dependent Variable). NONMEM prints the labels of the data items in the order it understands them to appear on the data records as a check for the user.

LABELS TO BE USED FOR ITEMS APPEARING IN TABLES AND SCATTERPLOTS ARE:

ID TIME DV AGE  WT PRED RES        WRES

The above states that the first data item is ID (NONMEM item), the second is TIME (a PREDPP item), the third is DV (a NONMEM item), then AGE and WT, which are other items, and finally PRED, RES and WRES, which are NONMEM-generated items – the predicted value of DV, the residual (DV-PRED), and the weighted residual (a transformation of RES to units of the population standard deviation).

(See data record, Section 51.9).

REFERENCES: Guide IV, section III.B.2

8 DATA_RECORDS

MEANING: Organized elements of a NONMEM Data Set

CONTEXT: NONMEM output

DISCUSSION:

A NONMEM data set consists of a series of data records; each data record, in turn, consists of a series of data items, the names of which are defined on the $INPUT record. NONMEM counts the data records and displays this count in its output as a check for the user. This count is of logical records as read by a FORTRAN format specification, which is also displayed in the output. If the format specification contains no slash (/) characters (which denote the start of a new FORTRAN record), then each logical record corresponds to a FORTRAN record.

NO. OF DATA RECS IN DATA SET: 394

(See data item, Section 51.9).

REFERENCES: Guide IV, section II.C

9 DATA_SET

MEANING: The data to be analyzed by NONMEM

CONTEXT: NONMEM output

DISCUSSION:

“Data set” refers to all of the data (from all of the individuals) that is to be used in the NONMEM analysis. NONMEM is aware of certain features of the data. NONMEM lists what it knows about the data set as a check for the user.

DATA SET LOCATED ON UNIT NO.: 2

THIS UNIT TO BE REWOUND:  NO

NO. OF DATA RECS IN DATA SET: 394

NO. OF DATA ITEMS IN DATA SET: 8

ID DATA ITEM IS DATA ITEM NO.: 1

DEP VARIABLE IS DATA ITEM NO.: 4

The above states that the data set is associated with a file on FORTRAN logical unit 2. The rewind feature (“UNIT TO BE REWOUND …”) is of interest only if this is not the first problem of the NONMEM run. The other lines report how many records were read, the number of data items on each record, and the index order of the two NONMEM data items, ID (identification) and DV (dependent variable).

(See data record, data item).

REFERENCES: Guide IV, section III.B.2

10 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

11 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, Section 53.55, Section 53.55).

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

12 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 multiplied 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 zero-order 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 Bolus dose.

>0, 0 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 zero-order 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 Section 60.41, Section 60.26).

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

13 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 Section 55.15).

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

14 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

15 `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. Dose-related 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:

NMTRAN is appending EVID
The record is not a dose event (AMT, RATE, SS = 0)
MDV is present in the data set (i.e., was listed on $INPUT)
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

16 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 end-of-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

REFERENCES: Guide IV, section III.B.5

17 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

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

18 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 Section 50.9).

(See Section 60.26).

REFERENCES: Guide VI, section V.G

REFERENCES: Guide IV, section V.B

19 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

REFERENCES: Guide V, section 12.4.2, 12.5

20 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.

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 Section 60.27, Section 53.40).

REFERENCES: none.

21 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 REFERENCES: Guide V, section 6.8

22 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 definition 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 raw-data-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 Section 60.24, Section 51.6).

REFERENCES: none.

23 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

24 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 Section 53.94).

REFERENCES: none.

25 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 compartment 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 compartment 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 identical 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 REFERENCES: Guide V, section 6.8

26 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). Steady-state 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 Section 51.25).

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 tran-

            sient 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 steady-state dose record with rate 0.)

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

27 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 Section 51.10).

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 Section 50.9).

REFERENCES: Guide VI, section V.C

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

1 ADDL DATA ITEM

2 AMT DATA ITEM

3 CALL DATA ITEM

4 CMT PCMT DATA ITEM

5 CONT DATA ITEM

6 DATA_AVERAGE BLOCK

7 DATA_ITEMS

8 DATA_RECORDS

9 DATA_SET

10 DATE DATA ITEM

11 DEFAULT COMPARTMENT

12 DOSE EVENT RECORD

13 DV AND MDV DATA ITEMS

14 EMPIRICAL SS DOSE EVENT RECORD

15 EVID DATA ITEM

16 FINISH

17 ID .ID. AND L1 DATA ITEMS

18 II DATA ITEM

19 L2 DATA ITEM

20 MRG_ DATA ITEM

21 RATE DATA ITEM

22 RAW_ DATA ITEM

23 REPL_ DATA ITEM (NM75)

24 RPT_ DATA ITEM

25 SS DATA ITEM

26 SS DOSE EVENT RECORD

27 TIME DATA ITEM

1 `ADDL` DATA ITEM

4 CMT `PCMT` DATA ITEM

13 DV AND `MDV` DATA ITEMS

15 `EVID` DATA ITEM