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.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# record 1
      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

# record 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).

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.

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.

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.

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

• Observation Event:

  • CMT specifies the number of the observation compartment (the compartment's scaled drug amount F in the error routine). When this number is for the output compartment, it can be negative so the output compartment is turned off after F is obtained. This is also the case for an output-type compartment, a compartment with attributes INITIALOFF and NODOSE (for a compartment n that is neither an output compartment or an output-type compartment, two records must be used to achieve this. They share a same TIME, while the first has CMT=n and EVID=1 to obtain the observation, and the second with CMT-n= and EVID=2 to turn off the compartment). An output-type compartment is initally off, may be turned on and off, and may not receive a dose. It must be turned on with an other-type event record in order start accumulating drug.
  • 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 F computed.
  • CMT and PCMT may be specified as 1000 or 100 to indicate the default compartment for output.
  • 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.

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

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.

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)

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.

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

1
2
3

II
1:30
1.30

NONMEM data set

1
2
3

II
1.50
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 exogenous supplementation example).

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

  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.

See $ERROR control record on how to use L2 data to model the above data for two types of observations.

MRG_ labels NONMEM's optional marginal (MRG) data item. 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 NMTRAN, F is calculated through Y.) Note that the marginal data item also affects the definition of the value of any PRED-defined item (denoted as "D" below) that is displayed in a table or scatterplot (except items stored in the SAVE region) and associated with the record.

• MRG_=0: The PRED item is the typical value of F and an output D is either the typical value or (for conditional estimates) the conditional estimate of the variable D.

• MRG_=1 or MRG_=2: The values of the PRED and D items are determined as follows.

  • If the Simulation Step with ONLYSIMULATION option, 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 observation records), and the D item is the posterior expectation of the variable D.
  • In other cases, the PRED and D items are as with METHOD=0.

  If the expectation is the posterior expectation:

  • MRG_=1, the deletion adjustment is not used.
  • 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 expectation block).

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.

• RATE=0: the dose is an instantaneous bolus dose.
• RATE>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).

• RATE=-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., CMT=1, or CMT=0 and compartment 1 is the default dose compartment). The $PK abbreviated code must assign for the reserved variable R1, the rate parameter for compartment 1, e.g.,

  1	R1=THETA(4)+ETA(4)

• RATE=-2: the dose is a zero-order bolus dose, i.e., an infusion, whose duration is modeled in the PK routine. For example, assume again the dose compartment is 1, with RATE=-2, the $PK block must assign for reserved variable D1, the duration parameter for compartment 1, such as

  1	D1=THETA(4)+ETA(4)

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

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 $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).

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.) The REPL_ data item and REPL option are meant to be used with $SIMULATION or $DESIGN.

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.

For clinical trial simulations, typically one creates a data file containing template subjects, which are to be replicated a number of times. The replication of the template subjects was often done in R or Excel, as NONMEM could not expand the data file in this way. As of NM75, NONMEM will replicate each subject REPL=n times, and then utilize this expanded 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.) For example, suppose a data file, called template.csv, contains 3 subjects, each one representing a particular covariate type, dosing type, and/or sample time pattern. The desire is that each of these subjects be replicated 100 times in the data set. This is done with the following record.

1

$DATA template.csv ignore=@ REPL=100

Make sure that the ID values of the template are integer valued. If the number of replications is greater than the difference between two consecutive ID values in the template, NONMEM will add a fractional value to each replicate subject, so that the integer portion of the ID is the original ID, and the fractional portion represents the replication number (NONMEM does not require integer valued ID’s, only unique ID numbers that have no more than 14 significant digits). Otherwise, the replicate ID’s will be integer incremented. To assure only integer ID’s are created, make sure the template ID’s are spaced by an amount greater than the number of replications desired for each subject.

To specify a different replication for each subject, a reserved data item has been introduced in NM75, called REPL_, the value of which will be used as 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. For example,

1
2

$INPUT ID TIME  AMT  RATE EVID MDV DV  REPL_
$DATA warfarin.dat ignore=C

with "warfarin.dat"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

CID TIME    AMT  RATE EVID MDV DV    REPL_
1.0 0.0    70.0  0.0  1    1   0.0   2
1.0 0.5     0.0  0.0  0    0   1.0   .
1.0 1.0     0.0  0.0  0    0   1.0   .
1.0 2.0     0.0  0.0  0    0   1.0   .
1.0 6.0     0.0  0.0  0    0   1.0   .
1.0 24.0    0.0  0.0  0    0   1.0   .
1.0 36.0    0.0  0.0  0    0   1.0   .
1.0 72.0    0.0  0.0  0    0   1.0   .
1.0 120.0   0.0  0.0  0    0   1.0   .
2.0 0.0    70.0  0.0  1    1   0.0   3
2.0 0.5     0.0  0.0  0    0   1.0   .
2.0 1.0     0.0  0.0  0    0   1.0   .
2.0 2.0     0.0  0.0  0    0   1.0   .
2.0 6.0     0.0  0.0  0    0   1.0   .
2.0 24.0    0.0  0.0  0    0   1.0   .
2.0 36.0    0.0  0.0  0    0   1.0   .
2.0 72.0    0.0  0.0  0    0   1.0   .
2.0 120.0   0.0  0.0  0    0   1.0   .

shows that data of subject 1 will be replicated 2 times within NONMEM, and data of subject 2 will be replicated 3 times. The ID values of the replicates will be 1.00, 1.01, 2.0, 2.01, 2.02.

REPL_ may be used with the REPL option of $DATA to replicate the entire data set REPL=n times. For the same data set above,

1
2

$INPUT ID TIME  AMT  RATE EVID MDV DV  REPL_
$DATA warfarin.dat ignore=C REPL=100

will result in 200 replications for subject 1, and 300 replications for subject 2. If both REPL_ and $DATA REPL are used, the REPL_ data item applies first, and the REPL option applies second.

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

The optional SS labels PREDPP's Steady State data item. It can take one of the following values in any event record.

• SS=0 indicates that the dose is not a steady state dose.
• SS=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).
• SS=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. In other words, let 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.
• SS=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.

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

Example:

NM-TRAN data set

1
2
3
4

TIME
8:00
14:45
14.75

NONMEM data set

1
2
3
4

TIME
0.
6.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.

In addition to relative (elapsed) time, TIME data item can be used together with DATE data to specify actual dates:

1

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

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:

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

1
2
3
4
5
6

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

NONMEM data set

1
2
3
4
5
6

ID         TIME
1          0.00
1          5.42
1         23.25
2          0.00
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.

USAGE:

1

FIN

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, which- ever 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.)

• Format:

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