123  NM-TRAN

NONMEM V Supplemental Guide

Authors

Alison J. Boeckmann

Stuart L. Beal

Lewis B. Sheiner

Published

March 1, 2013

1 General

2 Warning Messages

NM-TRAN Version III generates various informational and warning messages. These messages are not fatal (NONMEM may still be run) and may be ignored. Warning messages can be suppressed or their numbers limited for a given run by use of a new NM-TRAN control record $WARNINGS.

See Guide III V.2.1.4

See Guide VIII $warning

3 Day-Time Translation: the Year 2000

All versions of NMTRAN process the year correctly when all four digits are coded. However, earlier versions of NM-TRAN than III assume that two digit years are in the 1900’s. With NM-TRAN Version III, a constant LAST20 specifies the highest 2-digit year nn that is assumed to be in the 21st. century, i.e., to represent 20nn. By default, this constant has the value -1, and all 2-digit years remain in the 1900’s. LAST20 can be changed at installation time. It can also be changed at run time using the LAST20 option of the $DATA record. As an example, consider this fragment of data:

# TIME DROP=DATE
       0 12-31-99
       0 01-01-00

Earlier versions of NM-TRAN, and the present version with LAST20 set to -1, produce an error message:

(DATA ERROR)           RECORD  2, DATA ITEM 2: ******

ELAPSED TIME MAY NOT BE NEGATIVE.

With LAST20 set to 0 or any larger value, there is no error. The second year is understood to represent 2000. The elapsed time is 24 hours.

With earlier versions of NM-TRAN, and with LAST20 set to -1, the years “00” and “0” are not leap years. With LAST20 set to 0 or any larger value, they are understood to be 2000, which is a leap year. This changes the translation of dates that span February to March.

A warning message related to leap year can be controlled at installation time.

See Guide III V.2.1.5

See Guide VIII $data

4 More Digits After Day-Time Translation

Previous versions of NM-TRAN provide four digits (xxxx.xx) for the TIME data item after day-time translation. This allows TIME to be at most approximately 416 days (416*24=9984 hours). NM-TRAN III provides five digits (xxxxx.xx), which allows TIME to be at most approximately 4166 days. Furthermore, when the $DATA record includes the option WIDE, six digits (xxxxxx.xx) are provided.

See Guide VIII $data

5 TIME and II Data Items: Conversion to Days

The option TRANSLATE on the $DATA record directs NM-TRAN to divide the contents of the TIME and/or II data items by 24, thus converting hours to days. The user must insure that the units of PK parameters such as CL or K are consistent with this.

See Guide VIII $data

6 Generated ID Data Items

NM-TRAN infers that the data are population data when certain things are true of the control stream. (☞) Add to the list in Guide IV Chapter II section C.4.2 the following:

  1. An $ESTIMATION record includes the option LIKELIHOOD or -2LOGLIKELIHOOD, and an abbreviated code is present which uses η’s.
  2. The $ESTIMATION record includes the option LIKELIHOOD or -2LOGLIKELIHOOD, and an $OMEGA record is used.

In these cases the user need not supply the L1 data item label on the $INPUT record, although it is not incorrect to do so.

NM-TRAN generates one or the other of the following warning messages in all cases. This permits the user to verify that NM-TRAN has made the correct inference.

 (WARNING 1) NM-TRAN INFERS THAT THE DATA ARE SINGLE-SUBJECT.
 (WARNING 2) NM-TRAN INFERS THAT THE DATA ARE POPULATION.

7 Control Records

8 INCLUDE Records

Records whose first non-blank characters are INCLUDE may be present anywhere in the control stream. Such a record causes NM-TRAN to read records from a given file into the control stream.

See Guide VIII include

9 Filenames on Control Records

Filenames on NM-TRAN records may consist of as many characters as fit on a single line. A filename may not contain embedded spaces. If it contains commas, semicolons, or parentheses, or if it starts with an equal sign, then it must be surrounded by single quotes ' or double quotes ". An option name may not be used as a filename unless it is surrounded by quotes.

10 $PROBLEM Record

The text following $PROBLEM is optional.

See Guide VIII $problem

11 $DATA Record

When the format option is omitted, the maximum record size in the NM-TRAN data set is increased from 300 to 999 characters.

The option IGNORE allows records starting with any alphabetic characters (not just a single specified character) to be ignored. The character # is the default. Records in the NM-TRAN data set whose first character is # are ignored, even if the $DATA record does not include the IGNORE option.

The option NOOPEN specifies that the data set is not to be opened by NM-TRAN. This is useful in a multi-problem control stream when the data set is created by an earlier problem.

See Guide VIII $data

12 $SUBROUTINES Record

With $SUBROUTINES LIBRARY, different abbreviated code may be present in different problems of a multiple-problem run.

The name to which a subname is set may be a filename as described in 61 (Filenames on Control Records) above.

See Guide VIII $subroutine, subroutine

13 $THETA Record

A new option NOABORTFIRST applies to the Initial Estimates Step.

See Guide VIII $theta

14 $MSFI Record

The characters “=n” of the NPOPETAS are optional. The option may be coded POPETAS. This option can be used to inform NM-TRAN that the data are population data. This may be needed when the $ESTIMATION record does not appear.

See Guide VIII $msfi

15 $ESTIMATION Record

New options of the $ESTIMATION record are described in Chapter 1 of this guide.

16 $SIMULATION Record

NM-TRAN provides an initial call to SIMETA and SIMEPS. Additional calls to SIMETA and SIMEPS can be specified explicitly in abbreviated code in simulation blocks.

Data can be transgenerated using abbreviated code in a simulation block.

With the option ONLYSIMULATION, simulated η values are displayable by using ETA labels in $TABLE and $SCATTERPLOTS provided that the ETA array is defined in common NMPRD7, as is automatically the case when $PK, $ERROR, and $PRED abbreviated code is used.

Options REQUESTFIRST and REQUESTSECOND cause NONMEM to compute first and second partial eta-derivatives during the Simulation Step.

Option NOPREDICTION can be used with ONLYSIMULATION and indicates both that the simulated value is returned in the DV data item, and that etas (if any) are population etas. NOPREDICTION may be needed when the $SIMULATION record appears, and the $ESTIMATION record does not appear.

See Guide VIII $simulation, simulation block, nmprd7

17 $TABLE Record

In a multi-problem run, the list may include PRED-defined labels from a prior problem.

The characters ETA(A) and ETAA are no longer accepted as symbolizing ETA(10).

There are new options:

FIRSTONLY
FORWARD NOFORWARD
APPEND NOAPPEND

See Guide VIII $table

18 $SCATTERPLOT Record

There are new options:

FIRSTONLY
ABS0 NOABS0
NOORD0
OBSONLY

See Guide VIII $scatter

19 $MIX Record

The $MIX record marks the beginning of abbreviated code for the MIX routine. (☞)

See Guide VIII mix

20 Abbreviated Code

21 New Features

FORTRAN CALL, DO WHILE, ENDDO, and RETURN statements may be used under certain circumstances.

FORTRAN functions SIN, COS, and ABS are allowed, and may have random variable arguments. Note that the partial derivative of ABS(X) with respect to η is mathematically undefined at X=0. We are arbitrarily defining it to be dX/dη. If the prediction depends on X, X must always be either positive or negative.

Parentheses may be nested.

Parentheses may be used in arithmetic expressions that are part of conditional expressions, but not when the parentheses include .AND. or .OR..

Conditional statements may be nested, unless random variables appear anywhere in the inner or outer blocks.

FORTRAN WRITE and PRINT statements may be used, with restrictions.

Variables in generated code that symbolize (first-, and second-) partial η-derivatives of random variables will have different names with NM-TRAN Version III than with Version II.

See Guide VIII write print, abbreviated

22 Restrictions on the Use of Random Variables in Abbreviated Code

Random variables may be assigned using conditional statements. Old code (using indicator variables) is still valid.

Random variables may be redefined, and may appear on the right hand side of conditional assignment statements. They may be used recursively in their own redefinition.

If a random variable is defined by “incomplete” conditionals (i.e., conditionals which do not include both true and false cases), and all tests fail, the random variable has the value zero. This is a major difference between random and non-random variables. Consider these examples:

   IF (WT.GT.0) K=WT*THETA(1)*EXP(ETA(1))
   IF (WT.GT.0) TVV=WT*THETA(1)

If WT is ≤ 0, K is zero.

If WT is ≤ 0, TVV retains its prior value, which may have been computed with a previous event record.

When a COM(i) variable is defined by incomplete conditional statements and all tests fail, the variable retains its value (as do non-random variables).

See Guide VIII abbreviated

23 Improved Computation of Powers

Although when B=0 and P>0 the computation R=B**P is mathematically defined and is 0, some floating point processors fail with a floating point error. NM-TRAN now causes powers to be computed, in both generated and Library codes, in a manner that avoids floating point errors in this circumstance. In effect, powers are now computed as in a work-around that has been suggested to numerous NONMEM users who have asked for help with this difficulty:

 Q=0
 IF (B.EQ.0) Q=1
 R=(1-Q)*(B+Q)**P

If the work-around is already part of the abbreviated code it may be removed, but there is no harm if it remains; the generated or Library code will execute correctly, albeit more slowly than necessary.

24 Right-Hand Quantities

The reserved variable Y may now appear on the right-hand side in $PRED and $ERROR abbreviated code, e.g., LOGY=LOG(Y).

See Guide VIII $pred, $pred

The variable MIXP symbolizes a mixture probability computed by subroutine MIX.

See Guide VIII mix, mixp, rocm25

Right-hand quantities of interest with simulation are NREP and IREP. Right hand-quantities of interest with multiple problem runs and with super problems are NPROB, IPROB, S1NUM, S2NUM, S1NIT, S2NIT, S1IT, and S2IT.

See Guide VIII rocm10, rocm14

If NM-TRAN appends the EVID and/or MDV data items, then EVID and MDV may appear on the right-hand side in $PK, $ERROR, $DES, and $AES abbreviated codes.

25 Pseudo-Statements

The statement

 COMRES=-1

may optionally be enclosed within parentheses, and, if so, may optionally be coded on the first line of the block, e.g.

 $PRED (COMRES=-1)

See Guide VIII $abbreviated

26 ICALL Blocks

Abbreviated code between an IF statement that tests ICALL and the matching ENDIF is referred to as an ICALL block. E.g.,

   IF (ICALL.EQ.4) THEN
   ... ICALL block ....
   ENDIF

In general, there is no reason to include code testing for ICALL.EQ.2 (regular call). Such code should normally not be in an ICALL block, as it is, in effect, the default code.

In this section, ICALL blocks that test for values other than 2 are discussed. Such blocks are named according to the value of ICALL:

      0 Run initialization block
      1 Problem initialization block
      3 Problem finalization block
      4 Simulation block
      5 Expectation block
      6 Data Average block

The code within an ICALL block may include nested IF statements but if so, any test of ICALL must be in the outermost IF statement.

In an ICALL block, nested IF statements may include random variables but eta-derivatives are not computed.

Certain FORTRAN statements are permitted in ICALL blocks.

Feature ICALL Values Kind of Record
CALL PASS(MODE) 0,1,3 $PRED
CALL SUPP(ie,ic) 0,1,3 $PRED
CALL RANDOM(n,R) 4,5 $PRED,$PK,$ERROR
CALL SIMETA(ETA) 4 $PRED,$PK,$ERROR
CALL SIMEPS(EPS) 4 $PRED,$ERROR
DO WHILE( condition ) ... ENDDO 0,1,3,4,5,6 $PRED,$PK,$ERROR†
RETURN 0,1,3,4,5,6 $PRED,$PK,$ERROR†

ICALL values 0,1,3 are not appropriate for $PK and $ERROR.

ICALL value 6 is not appropriate for $PK.

RETURN statements must be used with caution because their use may by-pass desired actions of the routine.

See Guide VIII simulation, expectation, data average initialization-finalization, abbreviated

27 NM-TRAN with PREDPP

28 $BIND Record

The $BIND record is permitted with user-written PK routines as well as with $PK abbreviated code.

See Guide VIII $bind

29 $MODEL Record

The total number of compartments other than the output compartment defined on the $MODEL record may be as large as 19. If necessary, this maximum can be increased even further.

See Guide III IV.1.3, V.1.6

See Guide VIII $model, pk, psizes, tsizes

The name of a compartment may not be identical to an attribute unless it is enclosed in quotes (' or "). E.g., COMP=(DEFOBS) is not permitted but COMP=("DEFOBS",DEFOBS) is permitted.

When the number of compartments for ADVAN5 or ADVAN7 exceeds 10, the LINK clause syntax Knm=k may be ambiguous. The letter T may be used to separate the two compartment numbers KnTm.

See Guide VIII advan5 advan7

With ADVAN9, all compartments may have the attribute EQUILIBRIUM.

30 $PK Record

When the number of compartments for ADVAN5 or ADVAN7 exceeds 10, the reserved variable Knm may be ambiguous. The letter T may be used to separate the two compartment numbers KnTm.

See Guide VIII advan5 advan7

The variable SC symbolizes the scaling parameter for the central compartment with general ADVAN routines (5 through 9) if there is a compartment whose name is CENTRAL.

Pseudo-statements defining the calling protocol (CALLFL=n) and the variable listing option (COMRES=n) may be coded within parentheses following the record name, or on the next line. Within the parentheses, the calling protocol may optionally be described by a descriptive calling protocol phrase. E.g., the following are equivalent:

$PK (CALLFL=1)
$PK (ONCE PER INDIVIDUAL RECORD)

See Guide VIII calling protocol phrase, $pk

31 $ERROR Record

Pseudo-statements defining the calling protocol (CALLFL=n) and the variable listing option (COMRES=n) may be coded within parentheses following the record name, or on the next line. Within the parentheses, the calling protocol may optionally be described by a descriptive calling protocol phrase. E.g., the following are equivalent:

$ERROR (CALLFL=1)
$ERROR (ONCE PER INDIVIDUAL RECORD)

See Guide VIII calling protocol phrase, $error

32 $DES Record

The allowable right-hand side quantities include the data items of a data record, symbolized by the labels and synonyms specified in the $INPUT record, and values of the θ parameters, symbolized by THETA(1), THETA(2), etc.

If quantities depending only on data items and θ parameters are computed directly in $DES rather than $PK, improvement in run time is possible.

Reserved variables DOSTIM and DOSREC may be used under certain circumstances.

See above 41 (Use of DOSTIM and DOSREC in DES)

ICALL blocks testing for ICALL values 4 and 5 are permitted. However, none of the statements listed in 77 (ICALL Blocks)” above may be used.

With ADVAN9, a $DES block may not appear when there are only equilibrium compartments.

With ADVAN10 and steady-state doses with constant infusion doses, basic PK parameters KM and VM may be used in the $DES abbreviated code.

See Guide VIII $des

33 $AESINITIAL Record

When there are only equilibrium compartments and there is no TIME data item, ADVAN9 is called by default with every event record. $AESINITIAL may specify a calling protocol for ADVAN9. Pseudo-statements defining the calling protocol (CALLFL=n) and the variable listing option (COMRES=n) may be coded within parentheses following the record name, or on the next line. Within the parentheses, the calling protocol may optionally be described by a descriptive calling protocol phrase. E.g., the following are equivalent:

$AESINIT (CALLFL=1)
$AESINIT (ONCE PER INDIVIDUAL RECORD)

See Guide VIII $aesinitial, calling protocol phrase

34 $AES Record

The index i for algebraic expressions E(i) is optional.

The allowable right-hand side quantities include the data items of a data record, symbolized by the labels and synonyms specified in the $INPUT record, and values of the θ parameters, symbolized by THETA(1), THETA(2), etc.

If quantities depending only on data items and θ parameters are computed directly in $AES rather than $PK, improvement in run time is possible.

Reserved variables DOSTIM and DOSREC may be used under certain circumstances.

See above 41 (Use of DOSTIM and DOSREC in DES)

ICALL blocks testing for ICALL values 4 and 5 are permitted. However, none of the statements listed in 77 (ICALL Blocks) above may be used.

See Guide VIII $aes