119 NM-TRAN
Introduction to NONMEM Version VI
1 I.4.1 General
1. The IGNORE option on the $DATA record has been expanded so that any data record will be dropped when the values of one or more data items meet certain user-specified criteria, and a new ACCEPT option has been introduced so that any data records will be dropped unless the values of one or more data items meet certain user-specified criteria.
(See the $DATA Help Item.)
2. With Version V, the option TRANSLATE=(TIME/24) (or TRANSLATE=(II/24)) on the $DATA record results in the TIME (or II) data items in units of hours being converted to data items in units of days, with two figures to the right of the decimal point being retained. With version VI, this option results in three figures to the right of the decimal point being retained, as does the option TRANSLATE=(TIME/24.000) (or TRANSLATE=(II/24.000)). The option TRANSLATE=(TIME/24.00) (or TRANSLATE=(II/24.00)) results in two figures to the right of the decimal point being retained.
(See the $DATA Help Item.)
3. With Version V, the DO WHILE construction is allowed in an initialization/finalization block, and when this is used in conjunction with direct calls to the NONMEM utility routine PASS, passes through the data set may be implemented during problem initialization/finalization. Now a new DO WHILE (DATA) construction is allowed, which automatically and transparently manages the calls to PASS.
(See the ABBREVIATED CODE and PASS Help Items.)
4. With Version V, a random variable defined in an abbreviated code for a given routine must be completely defined with each data record that is passed to the routine. NM-TRAN now supports recursive definition of random variables in $PRED, $PK and $ERROR blocks. Examples of recursively defined random variables are given in the following fragments of code.
Example 1 - random variable retains value from previous data record. This example illustrates how one can use abbreviated code when WT is included only on some (e.g. the first) data records of an individual record. (Of course, this can lead to problems with developing plots involving WT.) Here, K is defined in terms of ETA(1), and so it is a random variable.
IF (WT.GT.0) THEN
K=THETA(1)*WT*EXP(ETA(1))
ELSE
K=K
ENDIFExample 2 - bolus dose at time 0 This example illustrates how one can use abbreviated code to implement recursive kinetics in $PRED assuming that TIME is the elapsed time since the previous data record.
K=THETA(1)*EXP(ETA(1))
IF (TIME.EQ.0) OLDA=AMT
A=OLDA*EXP(-K*TIME)
OLDA=AExample 3 - multiple bolus doses This example further illustrates how one can use abbreviated code to implement recursive kinetics in $PRED assuming that TIME is the elapsed time since the previous data record.
K=THETA(1)*EXP(ETA(1))
IF (TIME.EQ.0) THEN
A=AMT
ELSE
A=A*EXP(-K*TIME)+AMT
ENDIF5. The variables mentioned in sections 2 and 3: F_FLAG, YLO, YUP, CTLO, CTUP, NIREC, NDREC, NINDR, INDR1, INDR2, LREC, PRED_, RES_, WRES_, RPTI, RPTO, RPTON, PRDFL, and SKIP_ are all available with abbreviated code, as described in those sections.
6. Other variables that now may be used (as right-hand quantities) in abbreviated code are:
NEWL2 (from common ROCM17)
TEMPLT(n) (from common ROCM31)
The TEMPLT(n) variables refer to the items of the template data record. They may be used in data average blocks (ICALL=6) and $MIX blocks. The items of the template record may be referred to by position or by label, e.g., TEMPLT(1) or TEMPLT(ID).
(See ROCM17 and ROCM31 Help Items.)
7. With Version VI, the variables S1SC and S2SC of NONMEM read-only common ROCM14 are no longer recognized in initialization/finalization blocks; rather, the variables S1NUM and S2NUM are used.
(See ROCM14 and $SUPER Help Items.)
8. User-written functions FUNCA, FUNCB and FUNCC (called abbreviated functions) may now be used as right-hand quantities in abbreviated codes. Such a function may depend on arguments which may be random variables, in which case the function too becomes a random variable. Elements of vectors (VECTRA(n), VECTRB(n), VECTRC(n)) may be defined as left-side quantities in abbreviated code. A vector may be used as an argument to an abbreviated function. The code for the function itself must be written by the user in FORTRAN.
(See the ABBREVIATED FUNCTION Help Item.)
9. The functions TAN, ASIN (arcsin), ACOS (arccosine), ATAN (arctangent) may now be used in abbreviated code. The INT function may also now be used. When this function is used outside a simulation block, INT of a random variable is regarded as a non-random variable.
10. The NONMEM utility routine RANDOM may now be used in initialization/finalization blocks.
11. The value of the RECORDS option of the $DATA record may now be a label (appearing in the $INPT record) of a data item type. In particular, it may be ID (alternatively, IR, INDREC, or any initial substring of length 3 or more of INDIVIDUALRECORD). With this value NM-TRAN understands the data records for the problem to start with the first data record of the NM-TRAN data set (from the place where the NM-TRAN data set is positioned before data records are read; see the NOREWIND option) and to include all data records in the series of contiguous data records that follow and having the same value of the data item as does the first record. It counts the number of these data records (minus comment or dropped records) and puts this number in the NONMEM control file, so that these data records (or NM-TRAN-modified versions of them) become the data records used in the problem.
(See the $DATA Help Item.)
There are two obvious applications. First, during a checkout phase, one might want to see only the predictions for the first individual record, and therefore, use a data set comprised only of the data records therein. When RECORDS=ID is used, one need not count these data records. Second, one might want to analyze each subject’s data independently of the others. One way this can be done is by creating a single control stream with as many problems as there are individual records in the data, and including one each of the following series of $DATA records in the series of problem specifications:
$DATA filename RECS=n1
$DATA filename RECS=n2 NOREWIND
$DATA filename RECS=n3 NOREWIND
etc.where “nk” is the number of records in the kth individual record. It would be necessary to count the exact number of records. Now, these records can simply be coded
$DATA filename RECS=ID
$DATA filename RECS=ID NOREWIND
$DATA filename RECS=ID NOREWIND
etc.(See $DATA Help Item.)
12. With the INCLUDE record, the filename may now be followed by an integer n, whose default value is 1. Then NM-TRAN reads n copies of the named file.
If in the example above, where the problem specification for all subjects after the first are completely identical, a compact way of writing the control stream is possible. The control stream would contain the problem specification for the first individual, including the $SUBROUTINES record, abbreviated code, and the $DATA record for the first subject, and would end with (if there are e.g. 12 subjects in all)
INCLUDE ctlfile2 11The file ctlfile2 would contain one problem specification for one subject, with no $SUBROUTINES record or abbreviated code, but would include
$DATA filename RECS=ID NOREWIND(See INCLUDE Help Item.)
13. The INTERACTION option may now be used on the $ESTIMATION record along with METHOD=HYBRID, or METHOD=CONDITIONAL, LAPLACIAN, or METHOD=ZERO. The ETABARCHECK option may be used on the $ESTIMATION record. (see section I.2.1).
(See $ESTIMATION Help Item.)
14. The TRUE option may be used on the $SIMULATION record (see section 2.2 and the $SIMULATION Help Item).
15. With Version V, when the data are single-subject and the L2 data item is defined, NM-TRAN creates new data items and labels them .ID.. Now the ID data item is taken to be the L2 data item, and new .ID. items are not created. 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.
(See the L2 Help Item.)
However, if, as previously, 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 designation: For NONMEM, the items labeled L1 are taken to be the ID data items.
(See the ID and L2 Help Items.)
16. OMEGA(i,j) and SIGMA(i,j), where the subscripts i and j are integer constants, can now be used as right-hand quantities in $PRED, $PK, $ERROR and $INFN abbreviated codes. For example, when PREDPP is used with a slope-intercept residual error model, the computation of individual weighted residuals (with F evaluated at η=0) could be done as follows:
$ERROR
Y=F+EPS(1)+F*EPS(2)
IF (COMACT.EQ.1) THEN
STD=SQRT(SIGMA(1)+F**2*SIGMA(2))
IWRES=(DV-F)/STD
ENDIFWhen the two subscripts i and j are the same, only one subscript is needed. The OMEGA and SIGMA elements may be listed in WRITE and PRINT statements in initialization and finalization blocks.
(See the ROCM22 and INITIALIZATION-FINALIZATION BLOCK and WRITE/PRINT Help Items.)
17. SETHET(i,j), SEOMEG(i,j) and SESIGM(i,j), where the subscripts are integer constants, can now be listed in WRITE or PRINT statements in finalization blocks. These are elements of the estimated standard error arrays for the final estimates of THETA, OMEGA and SIGMA.
(See ROCM7 Help Item.)
18. Each of the array names THETA, OMEGA, SIGMA, SETHET, SEOMEG, SESIGM, and ETA - without subscripts, may be listed in a WRITE or PRINT statement, and then the entire array is written. With a WRITE statement, the format should either be omitted or be “*“; NM-TRAN creates a suitable format. E.g., either of
WRITE (99) THETA,SETHET
WRITE (99,*) THETA,SETHETmay be used. In such a statement, only arrays may be listed, and only if these arrays share the same dimensions. The array names THETA and ETA may be listed within any block of abbreviated code in which the elements of these arrays may appear on the right (e.g. $PRED and $INFN). The array names OMEGA and SIGMA may be listed within any initialization/finalization block. The array names SETHET, SEOMEG and SESIGM may be listed within any finalization block.
With arrays OMEGA, SEOMEG, SIGMA and SESIGM, the option (BLOCK) or (DIAG) must be given to indicate if the full array or just the diagonal elements are to be written. If the (BLOCK) option is used, the array is displayed in full symmetric form. E.g.,
IF (ICALL.EQ.3) WRITE (99) OMEGA(BLOCK)may be used.
(See the ROCM7 and ROCM22 and INITIALIZATION-FINALIZATION BLOCK and WRITE/PRINT Help Items.)
19. Character constants may be included in WRITE and PRINT statements in abbreviated code. E.g.
PRINT *, 'CLEARANCE EQUALS: ', CLE(See the WRITE/PRINT Help Item.)
20. The statements OPEN(u), CLOSE(u), REWIND(u), where u is a I/O logical unit number, are now usable in abbreviated codes. The unit number must be an integer constant between 40 and 99. A file name may be included with the OPEN statement, i.e. OPEN(u,FILE=filename). With OPEN and CLOSE, the NONMEM utility routine FILES is automatically called.
(See the Abbreviated Code and FILES Help Items.)
21. Copying blocks of abbreviated code begin with tests of the reserved variable COMACT, as follows:
IF (COMACT.EQ....) THEN
....
ENDIFUnlike with Version V, η-derivatives are no longer computed in a copying block. COM(i) variables that are used on the left in a copying block are referred to as “explicit” save variables. They are automatically stored in the SAVE region (a subregion of the reserved region of common NMPRD4). When COM(i) variables are defined in a copying block, the reserved region of common NMPRD4 must be explicitly set up with the use of the COMRES option on the $ABBREV record, but the COMSAV option need not be used.
Variables other than COM(i) variables may be used on the left in a copying block, and they are referred to as “implicit” save variables. These may not be defined along with COM(i) variables. Implicit save variables too are automatically stored in the SAVE region, and in this case, a reserved region of common NMPRD4 is automatically created; neither the COMRES nor COMSAV options can be used on the $ABBREV record. Use of implicit save variables can obviate the need for a $ABBREV record.
(See the COM COMACT COMSAV COMRES Help Item.)
22. A new NM-TRAN record concerns the computation of raw data averages. Heretofore, a data item occurring in the data record after the DV data item was not used in template matching. Now, by default it is. If a data item is to be excluded from template matching, the label or synonym for this item should be included in the new record - $OMIT. E.g.
$OMIT TIMEAs always, data items required by NONMEM are automatically excluded from template matching. The label of such an item may be included in the $OMIT record, but this is unnecessary.
(See the $OMIT Help Item.)
23. With Version V, the OTHER option on the $SUBROUTINES record could be used at most three times. Now it can be used at most forty times.
1.1 NM-TRAN datafiles: LAST20=50
With NONMEM VI 1.0, a change was made to constant LAST20 in NM-TRAN’s ABLOCK. Previously, it had the value -1. Two-digit dates were assumed to be in the 1900’s. Now, the default value is 50. Two digit years are interpreted by default as follows:
00-50 = 2000-2050
51-99 = 1951-1999(See the $DATA Help Item.)
1.2 NM-TRAN input files: 160 characters per line
With NONMEM VI 1.0, a change was made to NM-TRAN. Previously, it read only 80 characters per line of the NM-TRAN control stream. This could lead to errors when the NM-TRAN control stream contained more than 80 characters in a line. Now, it reads 160 characters per line. However, generated code (including that generated for lines of verbatim code) still contains 72 characters per line.
1.3 NM-TRAN datafiles: Ill-formed files
It is possible to create a file whose last line contains non-blank characters, but which does not end with carriage return/line feed characters (or, in the Unix environment, a newline character). This can be done using some editors (e.g., Wordpad, Notepad, Staroffice). Such a line is referred to here as an ill-formed line. What happens when an ill-formed line is read by the Fortran I/O library routines is not specified by the Fortran 77 standard. Compilers differ. Here are a few examples.
- gfortran - GNU Fortran 95 compile on Linux. f90: WorkShop Compilers 5.0 98/12/21 FORTRAN 90 2.0 on Solaris.
These compilers take the correct action: the characters on the last line are read normally, and the subsequent read command gets an End-of-file indication. In effect, the Fortran I/O routines have inserted the missing newline.
- g77 - GNU Fortran for Windows. f77: WorkShop Compilers 5.0 98/12/15 FORTRAN 77 5.0 on Solaris.
An End-of-file occurs when the last line is read, but the characters on the last line are actually read prior to the end-of-file condition occurring.
- It is possible that some compilers might ignore the characters on the ill-formed line entirely, and produce an EOF condition without first transferring any data. It is not known if there are any such compilers.
With compilers such as (2) and (3), and all previous versions of NM-TRAN, the characters on the last line are ignored. A data file that ends with an ill-formed line will, in effect, contain one line fewer than expected. If a control file ends with an ill-formed line, any task or options specified on that line will not be performed.
NM-TRAN has been modified so that, with compilers such as (2), it now detects when non-blank characters are read prior to an EOF, and generates an error message 589 (for a control or include file) or 590 (for a data file). The user should repair the file.
Note that with compilers (1), NM-TRAN continues to work correctly. It will see the last line, as before, and will not produce an error message.
1.4 NM-TRAN datafiles: Blank lines in files (BLANKOK)
Blank lines in the NM-TRAN data set are no longer permitted by NM-TRAN. A new option of the $DATA record, BLANKOK, restores the previous behavior.
(See the $DATA Help Item.)
1.5 NM-TRAN datafiles: Filenames
Filenames on NM-TRAN control records may now contain embedded spaces if the file is opened by NM-TRAN (rather than NONMEM). Filenames are now restricted to the number of characters that can be used by NM-TRAN (80) or NONMEM (71). Previously, embedded spaces were not permitted, and file names larger than the maximum would be truncated.
(See the $DATA Help Item.)
1.6 NM-TRAN datafiles: Tab and ^M
Previously, NMTRAN did not allow a character in the control stream or the input data set that is less than the space character in the computer’s collating sequence (“low-value character”). In particular, this meant that tab (ASCII 011) and carriage return (ASCII 015) characters were not permitted. (An exception is a data set for which a FORTRAN format specification is provided on the $DATA record; NMTRAN did not detect low-value characters. The result is platform-dependent, i.e., it depends on the action taken by the Fortran library I/O subroutines.)
Tab characters can arise with text editors that save tab as an explicit character, rather than expanding it to spaces. They are also present in data that is cut and pasted from Excel to an ASCII file, or saved directly from Excel to “Text (tab delimited)” format. (Previously, only the CSV (comma delimited) format was acceptable to NM-TRAN.) Carriage return is typically seen as “^M” at end of lines when a file is copied from MS-DOS to Unix with ftp’s binary option or as an email attachment.
Now, NMTRAN will permit such characters, as follows:
In the NMTRAN control stream, all such characters are converted to spaces, with the exception of verbatim code, which is left as-is.
When NMTRAN is reformatting the input data set (i.e., there is no format specification), they are treated as field delimiters, exactly the same as a comma.
E.g., let T stand for the tab character.
"1T2" and "1,2" are read as "1 2"
"1TT2" and "1,,2" are read as "1 0 2"- When there is a format specification for the input data set, NMTRAN attempts to detect low-value characters and warn the user. Low-value characters at the end of a line of data are ignored, unless the line is otherwise blank. This too is platform dependent.
Thanks to Steve Shafer for suggesting these changes. They have been tested on Solaris, Linux, and MS-DOS, on ASCII computers. It is expected that they will work the same on EBCDIC computers. However, the user should check carefully what happens on a particular platform before including tabs in files for NMTRAN.
(See the $DATA Help Item.)
1.7 $DATA record: RECORDS option
A change has been made to option RECORDS=n of the $DATA record. The value of n may now be as large as 99999999. Previously, n could not be larger than 9999. Note that if the RECORDS=n option is omitted, NM-TRAN reads the file to end-of-file, which with past versions was the only way that a files could have more than 9999 records. Now, this may be specified explicitly.
1.8 $PRIOR record
A new NM-TRAN record $PRIOR may be used instead of a user-written PRIOR subroutine.
(See the $PRIOR Help Item.)
1.9 $ESTIM record: NOOMEGABOUNDTEST option
There are new options THETABOUNDTEST, OMEGABOUNDTEST, SIGMABOUNDTEST, as well as NOTHETABOUNDTEST, NOOMEGABOUNDTEST, NOSIGMABOUNDTEST.
(See the $ESTIMATION Help Item.)
1.10 $ESTIM record: MAXEVAL option
The MAXEVALS option may now be as large as 99999999. Previously, the largest value permitted was 9999.
1.11 $TABLE and $SCATTER: G and H elements
Elements of G and H can be displayed in $TABLE and $SCATTER without the use of verbatim code. E.g.,
$TABLE G11 G21 G31 H11 H21(See the $TABLE and $SCATTER Help Items.)
1.12 Abbreviated code: PHI
The NONMEM utility function PHI may be used in all blocks of abbreviated code. The argument may be a random variable.
(See the PHI and Abbreviated Function Example Help Items.)
1.13 Abbreviated code: ROCM50
Arrays CNTID and IIDX from ROCM50 may be used on the right in abbreviated code in $ERROR, $INFN, $PK, and $PRED blocks. When used in a WRITE statement, "IIDX,CNTID" may be specified. Pairs of values are written, one pair per line, one pair for each individual record.
CAUTION: With NONMEM VI 2.0, do not define common ROCM50 in verbatim code. Verbatim code will no longer access ROCM50 correctly.
(See the ROCM50 example Help Item.)
2 I.4.2 PREDPP related
1. The variable A_0FLG is a new reserved variable in $PK abbreviated code, which may be tested as a right-hand quantity (see section 3). When A_0FLG=1, compartment amounts may be initialized:
IF (A_0FLG.EQ.1) THEN
compartment initialization block
ENDIFA_0(i) also is now a reserved variable which may be used as a left-hand quantity in a compartment initialization block. Specifically, A_0(i) is the compartment initialization value of A(i), i.e., the value to which the ith compartment amount is to be set when A_0FLG=1. A_INITIAL(i) is a synonym for A_0(i). The above is referred to as an explicit use of A_0FLG. There may be implicit uses.
(See the COMPARTMENT INITIALIZATION BLOCK Help Item.)
2. Variables A(n) may now be used as right-hand quantities in $PK abbreviated code, where they denote the latest computed compartment amounts. That is, the A(n) are the amounts at the previous event time, or if at a later time (but before the event time for which it may be that PK is being called) a lagged or additional dose was given, or a regular infusion was terminated, or an event occurred at a modeled event time, then the A(n) are the amounts at the latest such time. The time at which the A(n) are in fact computed is found in the variable TSTATE (from PREDPP read-only common PROCM9), also a right-hand quantity in $PK.
If ETA variables and A(n) variables are used in $PK abbreviated code, then any $OMEGA records referring to these ETA variables should precede the $PK record, or if an $MSFI record is used, this record should precede the $PK record and include the option NPOP=m, where m is the number of population ETA variables.
(See the $PK and PROCM9 Help Items.)
3. A new NM-TRAN record, $INFN, allows abbreviated code to substitute for user-written FORTRAN code. NM-TRAN generates the FORTRAN INFN routine (there is also an NM-TRAN Library INFN routine). In an $INFN block, ICALL may be tested for initialization/finalization values 0, 1 and 3:
IF (ICALL.EQ.0) THEN
run initialization block
ENDIF
IF (ICALL.EQ.1) THEN
problem initialization block
ENDIF
IF (ICALL.EQ.3) THEN
problem finalization block
ENDIFICALL may now also be tested for these values in $PK and $ERROR blocks, in which case the run initialization, problem initialization, or problem finalization block is moved to an INFN routine.
(See $INFN and INITIALIZATION-FINALIZATION BLOCK Help Items.)
2.1 $MODEL and $PK: I_SS option (Initial Steady State)
With NONMEM VI 2.0, the $MODEL record has a new option, I_SS. The $PK block has a new reserved variable, I_SS. See I.3.5 above.
(See the PRDPK4 and $MODEL and $PK Help Items.)