58 Support Utilities

Support utilities: data processing, table comparison, etc.

1 DDEXPAND

MEANING: DDEXPAND program

CONTEXT: NONMEM run

USAGE:

..\util\ddexpand < original.ctl > new.ctl

DISCUSSION:

With NONMEM 7.4, The utility program ddexpand in the ..\util directory will expand an NM-TRAN template control stream to propagate and incorporate delay differential equations (dde).

EXAMPLE:

ddexpand dde3.dde dde3.ctl

The destination file dde3.ctl will be produced, and a finedata control stream file (fine.ftl) will be produced and submitted to finedata utility to add extra doses to the data file identified in the dde3.dde control stream.

For details and examples, See INTRODUCTION TO NONMEM 7, ddexpand Utility Program.

REFERENCES: Guide Introduction_7

2 DOEXPAND

MEANING: DOEXPAND program

CONTEXT: NONMEM run

USAGE:

..\util\doexpand < original.ctl > new.ctl

DISCUSSION:

With NONMEM 7.4, The utility program doexpand augments abbreviated code in an NM-TRAN control stream file that has been annotated with DOE (which stands for DO expand) and ENDDOE (which stands for ENDDO expand) directives. This is useful for repetitive code statements that differ only by increments of indices. For example, it is useful for replicating derivative equations that differ only by their indices to DADT() and A(). These may occur with time delay and transit compartment differential equations.

For details and examples, See INTRODUCTION TO NONMEM 7: doexpand Utility Program. See also The DOPDE Method of Modeling PDE’s.

REFERENCES: Guide Introduction_7

3 FINEDATA

MEANING: FINEDATA program

CONTEXT: NONMEM run

USAGE:

..\util\finedata fineplot.ftl
..\util\finedata < fineplot.ftl

DISCUSSION:

The utility program finedata augments an NM-TRAN data file to incorporate additional, non-observation, time values spaced at regular increments so that when a table is generated, NONMEM can fill these records with predicted values, from which smooth prediction curves may be plotted. If data items DV, EVID and/or MDV are listed in $INPUT and are present in the input data records, inserted records will be given the following values by default

DV=.
EVID=0
MDV=1

This may be over-ridden by a data item specification, such as $FINEDATA EVID=2. See also the EXAMPLE below.

Alternately, finedata can be used to fill in missing covariate values, but not to add any additional records.

fineplot.ctl is the name of a control stream file containing special commands for the finedata program.

The only records that finedata pays attention to is $INPUT, from which it obtains the column names, $DATA, from which it obtains the input data file, $FINEDATA, which contains instructions, and $PROB by which problems are separated.

With NONMEM 7.4, the $EXTRADOSE record may be used to add additional non-observation dose records to those already existing, but it allows items such as compartment number, or EVID, etc., to vary. The EXTRADOSE has particular value when adding time-delay compartments to a model, to deal with time-delay problems. For details: See INTRODUCTION TO NONMEM 7, finedata Utility Program

All other control stream records are ignored. All options of $DATA are ignored, including RECORD and IGNORE options. (Input records whose first non-blank character is alphabetic are copied to the output file but not used otherwise.) Thus, a way to create a control stream is to copy the first records describing the data layout from an existing NONMEM control stream file, and then adding the $FINEDATA record.

Multiple data sets may be processed by one finedata control stream file, by using $PROB records to separate the problems.

The options to $FINEDATA are as follows:

$FINEDATA
FILE = filename
AXIS = label[(LIN) | (LOG)]
NEVAL = [n | label] | [TDELTA = [x | label]
[TSTART = [x | label | FIRST]]
[TSTOP = [x | label | LAST]]
[OCC = label]
[item = list] ...
[item = [PREV | NEXT] [LIN | LINLIN | LOG | LOGLIN]] ...
[DELIM = s | DELIM = t | DELIM =,]
[MISSING = list]

$EXTRADOSE ...

SAMPLE:

$FINEDATA TSTART = 0 TSTOP = 50 NEVAL = 100 AXIS = TIME(LIN) CMT = 1,3
FILE = example6b.csv

OPTIONS:

FILE=filename: Required. The name of the output file.
AXIS= label[(LIN) | (LOG)]: Required. Name of column containing times, usually TIME. Optionally, designate (LIN) or (LOG) in parenthesis, to indicate linear or geometric time incrementing when new records are incorporated.

If LIN: additive time increment = (tstop - tstart)/(neval+1)
If LOG: multiplicative time increment = (tstop/tstart)**(1/(neval+1))

Times may be entered as numerical values, or in hh:mm:ss format. Data sets with DATE/TIME records may also be processed (but then TSTART and TSTOP must be in numerical hours or hh:mm:ss format).

NEVAL= [ n | label ]: The number of additional incremental time records to be created per subject. Either an integer value n, or the label of a data item in the original data set containing the NEVAL value. When NEVAL=-1, then missing values will be filled in for specified items, but no additional records will be created. If NEVAL/=-1, only the inserted records will have filled in interpolated values, and the original records will remain untouched. Optional. One of NEVAL or TDELTA is required.
TDELTA= [x | label ]: The increment in time. Either a number, or the label of a data item in the original data set containing the TDELTA value. Optional. One of NEVAL or TDELTA is required.
TSTART= [ x | label | FIRST ]: Optional. Default: FIRST. The start time for creating incremental time records. Either a real or integer numeric value x, or the label of a data item in the original data set containing the start time. If TSTART is not a number and is not FIRST, then it is interpreted as the label of a data item in the original data set containing the start time. If omitted or coded as FIRST, then the time of the first record of the subject. When TSTART is given by a data item, it can differ according to occasion. The same holds true for TSTOP and NEVAL (See below) if they are obtained from the data file.
TSTOP= [ x | label | LAST ]: Optional. Default: LAST. The stop time for creating incremental time records. Either a numeric value real or integer x, or the label of a data item in the original data set containing the stop time, or LAST, in which case the last record of the subject or occasion or time section is used.

Finedata stops inserting records when occasion changes (if OCC= was given), or if EVID=3 or 4, or after a re-initialization of time (indicated by the time in the data record being less than that of the previous record). TSTART will be the next TIME value.

OCC= label: Optional. Restart the time incrementing when the occasion changes, in addition to the other conditions listed above.
item= list: List of values for data item ITEM for which there is to be a record at each time increment. May be a list of values such as 1,3 etc. This can be done for a series of data items. For example, if you enter $FINEDATA CMT=1,3 EVID=2,2 then two records per time point are inserted, one with CMT=1, EVID=2, and the other with CMT=3, EVID=2.
item= [LAST | NEXT] [LIN | LINLIN | LOG | LOGLIN ] ...: A scheme to determine how to supply values to various data items for these inserted records may also be given. The following may be interspersed with numeric values.

NEXT: When inserting records between two consecutive original records of time t1 (PREV) and t2 (NEXT), the PREDPP’s default of using the covariate value of the t2 (NEXT) record is used for the inserted records. NEXT is the default.

PREV: When inserting records between two consecutive original records of time t1 (PREV) and t2 (NEXT), the covariate value of the t1 (PREV) record is used for the inserted records. (LAST may be coded instead of PREV, to be consistent with the options of the $BIND record. Note that the $BIND record is not used by finedata.)

LIN, or LINLIN: A covariate-linear, time-linear interpolation is used for the covariate value for the inserted records. LINT or LINLINT (T for truncate) produces truncated integer values, LINR or LINLINR (R for round) produces values rounded to the nearest integer.

LOG, or LOGLIN: A covariate-logarithmic, time-linear interpolation is used for the covariate value for the inserted records. A T or R suffix results in truncated or rounded integer values, respectively.

LINLOG: A covariate-linear, time-logarithmic interpolation is used for the covariate value for the inserted records. A T or R suffix results in truncated or rounded integer values, respectively.

LOGLOG: A covariate-logarithmic, time-logarithmic interpolation is used for the covariate value for the inserted records. A T or R suffix results in truncated or rounded integer values, respectively.

DELIM=x: Optional. DELIM=delimiter of output data file, if it is to be different from the input data file. DELIM=S is space, DELIM=t is tab, DELIM=, is comma.
MISSING=list: Optional. List is a comma delimted list of symbols that denote missing values. By default, a period (.) and space (s) are considered missing values. Values such as 0 or -99 may be present in the data as symbols for missing values. They may be described with MISSING=0 or MISSING=-99. During interpolation, missing values will be skipped, and only records with non-missing values will be used for interpolation.

EXAMPLE:

With NONMEM 7.3 and higher, if an MDV is set to a value greater than or equal to 100, it is converted to that value minus 100 upon input, but will also not be used at all during estimation, only for table outputting. This option allows you to use the same enhanced data file for estimation and Table outputs, without significantly slowing down the estimation. So, the finedata control stream file might include

$FINEDATA TSTART = 0 TSTOP = 50 NEVAL = 100 AXIS = TIME(LIN)
CMT = 1,3 MDV = 101,101 FILE = example6b.csv

See Guide Introduction_7 for details and examples.

REFERENCES: Guide Introduction_7

4 LBLR

MEANING: Insert User-Defined Labels in Additional Files (NM75)

CONTEXT: NONMEM run

DISCUSSION:

The label substitution process is described in

I.28.General New Options for $ESTIMATION Record (NOSUB=0)
I.6.Expansions on Abbreviated and Verbatim Code and Other Items

It is normally done only in the NONMEM report file, but not in the additional files, such as the .ext, .cov, .coi, .phi, etc. These additional files need often be read by 3rd party software, which may rely on traditional names for thetas, omegas, sigmas, phi, eta, etc. Nonetheless, one may wish to make label substitutions on these additional files, which can be done after the NONMEM analysis, using the label_replace utility.

USAGE:

lblr file1 file2 file3 [S|T|C] [0|1|2]

OPTIONS:

file1: Input file to have label substitutions done. Typically this is the name of the NONMEM report file (e.g., root.res).
file2: NONMEM report file containing label substitution patterns, or any file containing label substitution patterns such as:

THETA(1) = THETA(CL)
ETA(2) = ETA(ETV1)
EPS(1) = EPS(RSW)

file3: The results are written to file3.
Option 1: Option 1 may be summarized as [S|T|C]

S=Expand and adjust with spaces (default)
T=Do not expand, and truncate label if necessary
C=Expand, and compress so there are no spaces (suitable only for comma del

Option 2: Option 2 may be summarized as [0|1|2]

0=Full name of parameter type (THETA/OMEGA/SIGMA/ETA/EPS/PHI/ETC/PHC) (def
1=two letter truncation of parameter type name (TH/OM/SG/ET/EP/PH/EC/PC)
2=single letter truncation of parameter type name (T/O/S/E/P/H/C/C)

Truncated parameter type name (1 or 2) works well with T, when no label expansion is permitted, and you want to make the label as compact as possible.

If the user specified NOSUB=1, then the thetas, omegas/etas, and sigmas/eps will not have been label substituted during the NONMEM execution. The user may wish to make the label substitution afterword with label_replace. For example,

 lblr myresult.res myresult.res myresult_new.res T 2

Notice in this example that the report file myresult.res serves as the input file, and the file from which to get label substitution pattern.

If you also want to perform an lpcc, do lblr first, then the lpcc utility.

See INTRODUCTION TO NONMEM 7, lblr: Insert User-Defined Labels in Additional Files

REFERENCES: Guide Introduction_7

5 LPCC

MEANING: Line Printer Controls Converter Program (NM75)

CONTEXT: NONMEM run

DISCUSSION:

The utility program Line Printer Controls Converter will convert the line printer control characters in the NONMEM report file into their proper actions. The line printer control characters are in the first character in each line, and at one time was interpreted by old 132 column line-printers.

USAGE:

lpcc inputfile outputfile codes ...

OPTIONS:

Inputfile: Should be the name of the NONMEM report file (e.g., root.res).
outputfile: The results are written to outputfile.
codes ...: A list of 1 or more codes.

The conversion is acted upon only between the lines NM-TRAN MESSAGES and just before Stop Time: as the lines before and after these do not use column 1 as a line-printer control column.

The code command characters are interpreted by lpcc as follows:

Code	Acting on Option Control character	Action
A0	`+`	Advance 0 lines (overprint on (merge with) previous line)
A1	space	Advance 1 line (no action is taken)
A2	`0`	Advance 2 lines (insert a blank line)
A3	`-`	Advance 3 lines (insert 2 blank lines) Not used in NONMEM
AS		Remove action character column once code is acted upon (But will not remove character in col 1 if not one of the above)
FF	`1`	Advance page (insert Form feed character)
FFA	`1`	Advance page and add blank line (insert Form feed with a next line)
FFA2	`1`	Advance page and add 2 blank lines
FF1	`1`	Replace ‘1’ as ’ ’ (interpret FF as A1)
FF2	`1`	Replace ‘1’ as ‘0’ (interpret FF as A2)
FF3	`1`	Replace ‘1’ as ‘-’ (interpret FF as A3)
ALL		FF,A0,A1,A2,A3
ALLS		FF,A0,A1,A2,A3,AS

After an action, the control character is replaced with a space. That space will be printed unless AS is requested. So AS shifts the line one column to the left.

An N followed by the code prevents that action from occurring.

EXAMPLE (options are acted upon in order):

lpcc example1.res example1.lst FF A0

Only replace “1” in column 1 with form feed, and merge line with ‘+’ with previous line.

lpcc example1.res example1.lst ALL FFA

Act on all codes, and replace “1” with FF/next line.

lpcc example1.res example1.lst ALLS FFA

Act on all codes, replace “1” with FF/next line, and shift line one column to the left.

See INTRODUCTION TO NONMEM 7, lpcc: Line Printer Controls Converter Program

REFERENCES: Guide Introduction_7

6 NEFF, NEFFI

MEANING: NEFF and NEFFI programs

CONTEXT: NONMEM run

DISCUSSION:

With NONMEM 7.4, the NEFF and NEFFI utility programs are used to analyze the quality of a MCMC run. NEFF stands for “Number of EFFective samples”. NEFFI stands for “NEFF for individual”.

For details and examples, See INTRODUCTION TO NONMEM 7: NEFF and NEFFI Utility Programs.

REFERENCES: Guide Introduction_7

7 NMFE UTILITY PROGRAM

MEANING: The name of a computer program

CONTEXT: NONMEM support utility routine

USAGE:

nmfe75 controlfile reportfile [-background]
             [-prsame] [-prcompile]
             [-prdefault] [-prseq] [-do2test]
             [-tprdefault]
             [-trskip] [-nobuild]
             [-maxlim=1] [-maxlim=2] [-maxlim=3]
             [-rundir=directoryname] [-runpdir=directoryname]
             [-parafile=filename]
             [-parafprint=n]
             [-nmexec=filename] [-xmloff]
             [-licfile=filename]
             [-locfile=filename]
             [-simparon] [-flushtime>=0.0]

Default, if used in the run directory:

nmfe75 controlfile reportfile
-prsame (if possible; else -prcompile)
-rundir=run
-runpdir=temp_dir -nmexec=nonmem
-licfile=../license/nonmem.lic

Options may need to be in quotes, e.g.,

nmfe75 CONTROL5 REPORT5.res "-prsame"

The name of the command indicates the version of NONMEM, e.g. nmfe74 denotes NONMEM 7.4. The command will be shown generically as nmfe7 in this help file. For details specific to an earlier release than NONMEM 7.4.0, see the help file for that release.

OPTIONS:

controlfile: Name of the input file containing the NM-TRAN control stream.
reportfile: Name of the output file into which NONMEM writes the results. Also called “the standard results” file.
-prcompile, -prsame, -prdefault, -tprdefault: By default, nmfe7 copies the required PREDPP routines from the nonmem ..\pr and ..\resource directories into a subfolder temp_dir of the current directory and compiles the routines there. (Some of these routines are needed even when $PRED is used.) This is referred to as “pr recompilation”. The resulting object files are then linked with NONMEM, and the nonmem executable is created. In a subsequent run, nmfe7 will skip the pr recompilation if the same ADVAN/TRANS (or a $PRED) are used, and the size of the problem (e.g., size of OMEGA and SIGMA) has not changed.
-prcompile: Force pr recompilation, in case the run does not appear to execute properly when no pr recompilation occurs.
-prsame: Force the skipping of pr recompilation. Used when nmfe7 detects a change in the previous run from the present run, but the user is convinced there is no significant change. Uses the compiled files from the previous run.
-prdefault: Do not recompile any routines other than FSUBS. Use the precompiled routines in ..\pr and ..\resource directories. May be used if it is sufficient to use default values in sizes.f90 for the various parameters (See ..\util\prsizes.f90 for the list of those that are used.). Any NONMEM parameters that are not used (that is, those not listed in prsizes.f90) will still be dynamically sized.
-tprdefault: Tests if is okay to do -prdefault. If it is not okay, then it will test if there are compiled pr routines in temp_dir directory, and if they are appropriate for the present model. If so, it will not recompile those pr routines, and use those that are already there. If not, it will perform a fresh PREDPP compile. May be combined with either -prcompile or -prsame.
-tprdefault -prcompile: Tests if is okay to do -prdefault. If it is not okay, then it will perform a fresh compile of the particular ..\pr routines, even if there were appropriate ones in temp_dir already. (-prcompile forces a compile regardless of whether it was necessary).
-tprdefault -prsame: Tests if is okay to do -prdefault. If it is not okay, then it will use those in temp_dir, assuming that they are appropriate for the present problem.
-prseq: As of nm75, the option -prseq is available to cause the PREDPP files to be compiled sequentially, rather than in parallel (default). Sometimes the parallel method of compiling may actually take longer, or the compiler license may limit the number of simultaneous instances of the compiler that are permitted to be operating at once.
-do2test: As of nm7.5.1, the option -do2test is available that has NMTRAN check the control stream file for requirement of analytical 2nd derivatives. If required, NMTRAN will build FSUBS with analytical 2nd derivatives, otherwise it will build FSUBS without it, equivalent to the user entering $ABBR DERIV2=NO. For complicated control streams, inserting analytical 2nd derivative equations can take a long time to produce the FSUBS code. Problems use 2nd derivatives when $EST LAPLACE NOINTERACTION without NUMERICAL, or $SIM REQUESTSECOND.
-trskip: Requests that the NMTRAN step be skipped. The -trskip option is useful if you wish to modify FSUBS.f90 created by a previous run, and insert extra debug lines into FSUBS.f90, and prevent your modified FSUBS.f90 from being over-written by NMTRAN (it will still be compiled).

-trskip and any one of -prskip, -prnoskip, or -prstatic options may be used together, or -trskip may be used by itself.

-nobuild: Prevents a new nonmem executable from being built, particularly useful for a series of nonmem runs during boostrap procedures.
-maxlim=[1|2|3]: With maxlim=1, then LIM1, LIM3, LIM4, LIM13, and Lim15 (those used during estimation, and therefore by workers in a parallelization problem), will be set to the size needed to assure no buffer files are used, and everything is stored in memory, for the particular problem. With -maxlim=2, then LIM1, LIM2, LIM3, LIM4, LIM5, LIM6, LIM7, LIM8, LIM13, LIM15, and LIM16 are also sized to what is needed to assure that buffer files are not needed. With -maxlim=3, then MAXRECID will also be sized, to MAXDREC, the largest number of records in any individual. With maxlim=3, it is preferred to also use -tprdefault, or -prcompile, but not -prdefault, as NMTRAN’s optional resizing of the PREDPP size parameter MAXRECID may conflict with the -prdefault option.
-rundir=directoryname: Specifies a directory for the NONMEM run if it is different from the present working directory. The directory must exist, and must contain all necessary input files, such as the controlfile, msf files, and data files.
-runpdir=directoryname: Specifies a directory for the compile if it is different from temp_dir. This is useful if you are repeatedly going between two or more problems, so that often they need to be pr recompiled, and you want to save time. Specify a unique temporary directory for the compilation for each problem.
-parafile=filename: Name of the “parallel file” (the parallelization profile) that controls parallelization (distributed computing). Default file name if not specified: parallel.pnm. For details on the content, see the INTRODUCTION TO NONMEM 7. Versions prior to NONMEM 7.2 do not support parallel computing.
-parafprint=n: Sometimes the parallelization log files can become very large during the $EST and $COV steps. Each of these records have parafprint options to control the print intervals. Or, you can control the print iterations globally with the -parafprint option at the command line.
-locfile=filename: Name of a file to override the default file called nmloc or nmloc.bat. This is the location file, which gives the path for compiler or MPI system. The nmfe7 script will display a statement as to what path it uses. E.g., “Pathlist information for compiler and MPI systems are located in nmpathlist.txt” where nmpathlist.txt describes which version of nmloc is being used.
-nmexec=filename: Specifies an alternate name for the NONMEM executable instead of the default nonmem.exe (windows) or nonmem (Linux). Note that when parallelization is used, this name must be specified in the pnm file. Example:

nmfe7 controlfile reportfile -nmexec=nonmem2 -parafile=mpi2.pnm

Suppose mpi2.pnm is based on mpilinux_onecomputer.pnm, which contains

1:mpirun -wdir "$PWD" -n 1 ./nonmem $*
2:-wdir "`$PWD`/wrk_mpi" -n 1 ./nonmem <control_stream> <licfile>

Then mpi2.pnm must be changed as follows:

1:mpirun -wdir "$PWD" -n 1 ./nonmem2 $*
2:-wdir "`$PWD`/wrk_mpi" -n 1 ./nonmem2 <control_stream> <licfile>

-background: If -background is present NONMEM does not poll the terminal for ctrl characters. (See below.)
-xmloff: Turns off production of the XML output file root.xml, where root is the root name of the control stream file. This may speed up fast computational problems such as $SIM on simple models and small data sets.
-simparon: Turn on parallelization during simulation step.
-flushtime>=0.0: File buffer contents are flushed to file not more frequently than flushtime seconds (1.0 second is default). Floating number allowed.

DISCUSSION:

NMFE7.bat and NMFE7 are front-end tools for running NONMEM 7. Their use is optional. NMFE7.BAT is a MS-DOS batch program. NMFE7 is a UNIX C-shell script. Both are supplied on the NONMEM 7 distribution medium.

They should be placed in a directory in the user’s path. Both make use of the support utilities nmlink7 and compile7, which are also supplied on the NONMEM 7 distribution medium.

Both execute the following steps, stopping after any step in which errors occur:

NM-TRAN processes the NM-TRAN control stream, which is found in a file whose name is given as the first command-line argument. With NONMEM 7.2 and higher, both lower and upper case may be used for all user-defined and reserved words in the control stream. With NONMEM 7.3 and higher, & may be used at the end of any line of the control stream to indicate that the line is to be continued, including control records as well as abbreviated code. Lines may be longer than 160 characters long. The maximum length is given by FSD in resource/SIZES.f90. (FSD=67000 with NONMEM 7.3). This step is omitted if option -trskip is used.
NMLINK7 creates the file LINK.LNK (a list of object files to be included in the NONMEM executable). With NONMEM 7, compile7 creates the file compile7.lnk (a list of PREDPP routines to be re-compiled with the current array sizes) and a work directory temp_dir is created. All files listed in compile7.lnk are copied to temp_dir and compiled. They are then copied to the current run directory. The recompilation of PREDPP routines can take a noticeable amount of time. This step is skipped if option -prsame or -prdefault is used. (See $sizes.ctl).
If a file FSUBS.f90 of generated and/or user-supplied FORTRAN code was created by NM-TRAN, it is compiled by the FORTRAN 90 compiler.
Utility program nonmem_mpi.exe is called to check if parallel processing is requested, what transfer type is to be used, and make sure the parallel file is syntactically okay. Either of two sets of messages will appear at the console:

Exit status = 1
IN MPI

This indicates that parallel processing using the MPI method is requested. MPI libraries will be included in the NONMEM executable.

Exit status = 0
IN REGULAR/FILE TRANSFER

This indicates that no parallel processing was requested, or parallel processing uses the FPI (file transfer) method. No MPI library is needed.

The NONMEM executable nonmem.exe (nonmem in UNIX) is created.
The NONMEM executable is run. It is passed an option -licfile, which tells it where to find the NONMEM license file. Typically, this is the file nonmem.lic in the subdirectory license of the directory in which NONMEM was installed. First, arrays are allocated dynamically, according to information supplied by NM-TRAN in files FSIZES. (See Section 50.41). Processing may be performed as a single CPU process, or distributed among multiple cores or nodes, as specified in the parallel file. (See parallel). The output file whose name is given as the second command-line argument is created. During the run, NONMEM output can be found in the file OUTPUT. When the run terminates, file OUTPUT is copied to the output file and then removed.

While NONMEM 7 and higher is running, the following may be used if -background was not present:

ctrl-J: Turn console iteration printing on/off during the Estimation Step (Default is on).
ctrl-K: Stop the Estimation Step, which completes its output, and goes on to next mode or estimation method.
ctrl-E: Exit program gracefully.
ctrl-T: Monitor the progress of each individual during an estimation by toggling ctrl-T. Wait 15 seconds or more to observe a subject’s ID, and individual objective function value. It is also good to test that the problem did not hang if a console output had not been observed for a long while.

The signal program may be used in situations where NONMEM does not respond to the ctrl key. (See Section 58.11).

EXAMPLES OF USAGE:

nmfe7 CONTROL5 REPORT5.res
nmfe7 CONTROL5 REPORT5.res -background >& consout &

(Trailing & is used in UNIX to run the command in the background.)

Other files are created by nmfe7 and NONMEM:

FSUBS_MU.F90: Contains SUBROUTINE MUMODEL2. This subroutine contains only the code that is needed to compute any MU parameters (MU_1, MU_2, etc.) that were defined in $PK or $PRED abbreviated code. It is also included in FSUBS.
FSUBS and FSUBS.f90: These are identical. They contain both the content of FSUBS as it was in previous versions of NONMEM (generated subroutines PK, PRED, MODEL, etc., plus any user-supplied code), and also subroutine MUMODEL2. Note that user-supplied code must be in Fortran 90 format.

With NONMEM 7 and higher, additional output files are created, with names controlfile.xxx, where xxx is ext, cov, etc. (See Section 52.1). (See Section 52.7).

REFERENCES: Guide III, section IV.1.0, V.7.0; Guide Introduction_7

8 NMTEMPLATE

MEANING: NMTEMPLATE program

CONTEXT: NONMEM run

USAGE:

..\util\nmtemplate source-template-file destination-file var1=val1 var2=val2 ...

where var1=val1 is a variable name, and value to substitute in the template file. The variable var1 must in turn appear as <var1> in the template file, and is case sensitive. Similarly for var2, var3, etc.

DISCUSSION:

The utility program nmtemplate in the ..\util directory will perform variable substitution on appropriately tagged control stream template files, and produce executable control stream files.

SAMPLE:

nmtemplate nmtemp.nmt nmtemp.ctl NMID=47 TH1=1.7 TH2=1.4 TH3=0.8 TH4=2.0

The lines of interest in file ..\util\nmtemp.nmt are:

$DATA nmtemp2.csv IGNORE = C ACCEPT = (ID == <NMID>)
$`THETA` <TH1> <TH2> <TH3> <TH4>

Note that <NMID> is to be replaced with a particular NONMEM ID number by nmtemplate, and the <THX> are to be replaced with specific values of thetas. The resulting file nmtemp.ctl will have the various values substituted into the various <> placeholders, and is ready to be read by NMTRAN:

nmfe7 nmtemp.ctl nmtemp.res

In the above nmtemp.nmt example, because FNLETA=2, then NONMEM will simply evaluate the IPRED values using the inputted etas from the $ETAS record without performing an estimation.

Another example template file is example6.nmt listed in the ..\util directory, that you may inspect for other ideas.

Actually, nmtemplate is a general variable substitution program, and can process any text file in the manner shown above. Consider a FINEDATA control stream file template (nmtemp.fnt):

`$INPUT` C SET ID JID TIME DV = CONC AMT = DOSE RATE `EVID` `MDV`
CMT CLX V1X QX V2X SDIX SDSX

$DATA nmtemp.csv IGNORE = C
$FINEDATA AXIS = TIME(LIN) TSTOP = <TSTOP> TSTART = <TSTART>
NEVAL = <NEVAL> FILE = nmtemp2.csv

in which the tstart, tstop, and neval parameters are to be inserted:

nmtemplate nmtemp.fnt nmtemp.fnd TSTART=0 TSTOP=100 NEVAL=200

resulting in the FINEDATA control stream file nmtemp.fnd:

`$INPUT` C SET ID JID TIME DV = CONC AMT = DOSE RATE `EVID` `MDV` CMT
CLX V1X QX V2X SDIX SDSX

$DATA nmtemp.csv IGNORE = C
$FINEDATA AXIS = TIME(LIN) TSTOP = 100 TSTART = 0 NEVAL = 200
FILE = nmtemp2.csv

Note that only words that match the variable list at the nmtemplate command line, and have enclosing brackets <>, will be replaced with the suggested values. The values may also be text with no spaces in them.

Nmtemplate may be used with a DOS patch script (which could also be converted to an R/S-PLUS script or function).

Another feature of nmtemplate is that the user may request a random number to be generated to serve as a value, by referring to ~R(a1,a2,a3). R(a1,a2,a3) is a special function of nmtemplate, which obtains a uniform random variate between a1 and a2. If a seed a3 is given that is not 0, it means to initialize the seed. The initialization should be done once in a series.

For example, the following line sets the seed:

nmtemplate wexample12.nmt dummy.ctl SAMPLE=~R(1,10000,113345)

to be substituted wherever <SAMPLE> shows up in the template file with a throw-away result file dummy.ctl. The template file wexample12.nmt may contain:

`$EST` METHOD = CHAIN FILE = wexample12.txt NSAMPLE = 0 `ISAMPLE` = <SAMPLE>

and the resulting files will contain random ISAMPLE values.

See Guide Introduction_7 for details and examples.

REFERENCES: Guide Introduction_7

9 PARALLEL COMPUTING

MEANING: The parallel computing feature of NONMEM

Parallel computing is described in the INTRODUCTION TO NONMEM 7.

(See nmfe).

REFERENCES: Guide Introduction_7

10 PRIORGET

MEANING: Transfer Results of an Analysis to NMTRAN Prior Information (NM75)

CONTEXT: NONMEM run

This utility extracts results from a raw output file (.ext) and a previous analysis into informative prior values for a subsequent analysis.

USAGE:

priorget root.ext root.cov myprior.ctl PRIORTYPE TBLN
s/,/t

where root.ext and root.cov are input the files from a previous analysis.

PRIORTYPE=

N if the previous analysis (source of prior information) was maximum likelihood/nlme (FOCE/Laplace/IMP/SAEM/ITS).
B if the previous analysis was Bayesian (BAYES/NUTS).
S if the previous analysis was Bayesian, and you want the SCALE() option of $OMEGAP/$SIGMAP used instead of modifying the matrix elements (letting NMTRAN scale the elements).
I if the previous analysis was Bayesian, and you want to use the inverse of the average of the inverse of OMEGA/SIGMA of the previous analysis, and their variances for degrees of freedom assessment. According to statistical theory, the inverse of OMEGAS/SIGMAS from a Bayesian analysis are Wishart distributed, and they tend to be more similar in value to the mode of Omegas estimated in nlme analyses. See A Note on Setting up Prior Information in the Introduction to NONMEM7 Guide.

TBLN is the table number, as these input files may have several tables to choose from. Delimiter can be , t for tab, or s for space. Optional if delimiter is space. The order of the parameters in the input files must be in the default TSOL (lower triangular) order.

EXAMPLE:

priorget example3.ext example3.cov prior3.ctl N 5 s

extracts information from table 5 of the population mixture problem example3, and places it in NMTRAN $PRIOR control stream format in the output file prior3.ctl. See INTRODUCTION TO NONMEM 7, priorget: Transfer Results of an Analysis to NMTRAN Prior Information.

You can then patch (or “include”) this code into your control stream for the subsequent analysis. Any fixed thetas will have $THETAPV variances with value 0, so you will need to modify this as needed. The degrees of freedom for Omegas and Sigmas ($OMEGAPD, $SIGMAPD) are calculated according to the formula described in section “A Note on Setting up Prior Information.”

Be aware that the degrees of freedom may fall below the block dimension, or be above the total number of subjects, and the user may wish to modify the results accordingly before using them in an analysis. Results from priorget should always be treated as informational first, and then inspected and modified according to your intended purpose.

REFERENCES: Guide Introduction_7

11 SIGNAL

MEANING: SIGNAL program

CONTEXT: NONMEM run

Program SIGNAL is a NONMEM utility program. It allows the user to send a signal to NONMEM while it is running.

USAGE:

signal X

The following signals may be sent:

Print toggle: J, R, or P
Paraprint toggle: B, A, PA, or PP
Next: K or N
Stop: E or S
Subject Print toggle: T, U, or SU

DISCUSSION:

Sometimes NONMEM does not respond to user input via the ctrl key. This may occur during a parallel distribution run using MPI, or if the user began NONMEM with the -background switch. The user may open another console window, copy the program signal.exe (signal in UNIX) from the NONMEM util directory to your run directory, then enter any one of these commands:

Print toggle (monitor estimation progress):

signal J
signal R
signal P

Paraprint toggle (monitor parallel processing traffic):

signal B
signal A
signal PA
signal PP

Next (move on to next estimation mode or next estimation): signal K signal N

Stop (end the present run cleanly):

signal E
signal S

Subject print toggle:

signal T
signal U
signal SU

These create one of these files in the current (run) directory:

sig.print
sig.paraprint
sig.next
sig.stop
sig.subject

The multiple signals are synonyms. For example, ctrl-T is the keyboard switch, so signal t should match this. Also, since it is a subject toggle, signal s or signal su are synonyms, suggesting Subject.

The signal command creates the signal files, and the nonmem program detects the signal file, and immediately deletes it.

A second argument is permitted to specify the run directory, in case you are not executing the signal program from the run directory.

signal N ~/nonmem/

REFERENCES: Guide Introduction_7

12 TABLE_COMPARE

MEANING: TABLE_COMPARE program

CONTEXT: NONMEM run

The utility program table_compare compares the numerical values between two table files produced by the NONMEM $TABLE record. The user may specify the tolerance for the comparison.

USAGE:

table_compare table1.tab table2.tab <delimiter>, precision.xtl >differences.txt

where delimiter is {, t s} for {comma tab space}, and precision.xtl is a precision specification or control file. Default delimiter is space and default control file is table_compare.xtl. It is useful to redirect difference results to a file, in this example differences.txt.

EXAMPLE:

For example, the user may desire that only relative differences greater than 0.001 be reported. A very simple control file could be:

`$PRECISION`
ALL = 0.01,0.003

stating that all columns be compared with a relative difference of 0.01, and absolute difference of 0.003. Precision criteria for specific columns in the tables may also be given:

`$PRECISION`
ALL = 0.01,0.003 WRES = 0.1,0.2
CL = 0.05,0.02

The equation for comparison is

\[\mathrm{ABS}(X - Y) > R \cdot \mathrm{MAX}(\mathrm{ABS}(X), \mathrm{ABS}(Y)) + A\]

then the difference is reported, where $R$ is the relative difference tolerance, and $A$ is the absolute difference tolerance.

REFERENCES: Guide Introduction_7

13 TABLE_QUANT

MEANING: TABLE_QUANT program

CONTEXT: NONMEM run

The utility program table_quant transforms importance sampling (SIR) data in the NONMEM raw output file. Such data are present when the option SIRSAMPLE of the $COVARIANCE record is used. (See Guide Introduction_7, “Importance Sampling of the Variance-Covariance of the Parameter Estimates”). Table_quant produces a table file with frequencies and cumulative values.

USAGE:

table_quant inputfile outputfile delimiter start end

Inputfile name should be the NONMEM file (root.ext). Required.

The results are written to outputfile, which may be called root.qnt. (This name is needed if R script quantplot.R, or Splus script quantplot.ssc, available in Pdx-Pop 5.2, is used to view histograms and cdf plots from these result files.) The output file contains, for each item, the sorted value, its frequency (freq), and its quantile position or cumulative probability (cum).

Required.

Delimiter is that used in the input file (s for space, t for tab, comma default).

start and end are the range of iterations to be quantized (default is all non-negative iterations).

Table_quant uses the WEIGHT values record by NONMEM in the file. Bayes results, which do not have the WEIGHT column, can be processed with this utility, but the weight is then assumed constant among all samples.

The output file will contain for each item, the sorted value, its frequency (freq), and its quantile position or cumulative probability (cum). Also, make sure the input file contains just one table of information.

See also table_resample (tabresamp) program.

EXAMPLE:

REFERENCES: Guide Introduction_7

14 TABLE_RESAMPLE

MEANING: TABLE_RESAMPLE program

CONTEXT: NONMEM run

The utility program table_resample performs a resampling of importance sampling (SIR) data in the NONMEM raw output file. Such data are present when the option SIRSAMPLE of the $COVARIANCE record is used. (See Guide Introduction_7, “Importance Sampling of the Variance-Covariance of the Parameter Estimates”). Table_resample produces a table file. Samples are weighted according to the WEIGHT column. If no WEIGHT column is present, WEIGHT is assumed to be equal among all samples.

USAGE:

table_resample inputfile outputfile delimiter newsize seed start end

OPTIONS:

Inputfile name: Should be the raw NONMEM file (root.ext).
outputfile: The results are written to outputfile, which is required.
Delimiter: Same as the delimiters that is used in the input file (s for space, t for tab, comma default).
start and end: The range of iterations to be resampled (default is all non-negative iterations).
newsize: Size of the new samples, when seed > 0.
seed=0: Non-randomized expansion of the samples, based on WEIGHT column.
seed>0: Randomized starting at seed, with repeated samples allowed. If the user chooses seed>0, then newsize samples will be generated randomly and with replacement, in proportion to the WEIGHT column.
seed<0: Randomized starting at abs(seed), with repeated samples not allowed.

If the user chooses seed=0, then newsize samples will be generated, each line of the original root.ext file being repeated in proportion to its WEIGHT value, and these repeated samples will be placed in root_new.ext. Thus the weight of each sample is physically expressed in the manner of repeated rows of that sample. To assure that integer truncation does not render the smaller weighted samples to be not at all expressed, newsize should be something like 10000, or even 100000. The resulting file, root_new.ext, will have the same structure as a BAYES result file, without the WEIGHT column, and the R script bayesplot.R or Splus script bayesplot.ssc, available in Pdx-Pop 5.1, may be used to view histograms, quantile plots, and quantile tables.

The seed<0 should be used only if newsize << min(oldsize of original file, end-start+1) that is, you just want a to pick a few samples.

See also table_quant (tabquant) program.

EXAMPLE:

REFERENCES: Guide Introduction_7

15 TABLE_TO_XML

MEANING: TABLE_TO_XML program

CONTEXT: NONMEM run

Program TABLE_TO_XML is a NONMEM utility program in the ..\util directory. It converts additional output table files produced by NONMEM to XML Formatted files.

USAGE:

table_to_xml inputfile outputfile <delimiter>,

where the delimiter is {, t s} for {comma tab space}. Default delimiter is space. The rules (schema, document type definition) by which the xml file is constructed are given in table.xsd and table.dtd in the ..\util directory.

EXAMPLE:

table_to_xml my_results.cov my_results_cov.xml

REFERENCES: Guide Introduction_7

16 XML_COMPARE

MEANING: XML_COMPARE program

CONTEXT: NONMEM run

The utility program xml_compare compares the contents of two NONMEM report XML files that are produced by NONMEM.

USAGE:

xml_compare myresult1.xml myresult2.xml <delimiter> myprecision.xtl >mydifferences.txt

where delimiter is {, t s} for {comma tab space}, and myprecision.xtl is a precision specification or control file. Default delimiter is space and default control file is xml_compare.xtl. It is useful to redirect difference results to a file, in this example mydifferences.txt.

The control file can be quite elaborate, but it allows specification of various precision values for the many different types of values in the NONMEM report XML file, and to ignore certain entries as well. An example xml_compare.xtl file is in the util directory, and has the following contents:

$IGNORE
monitor
elapsed_time
datetime
covariance_status
termination_status
nonmem(version)
$PRECISION
GENERAL = 0.2,0.2 OBJ_BAYES = 2.0,0.0 OBJ_SAEM = 0,100.0
OBJ_ITS = 0,5.0 OBJ_IMP = 0,10.0 OBJ_F = 0,5.0
DIAG = 0.3,0 OFFDIAG = 0,0.5 COR = 0.0,0.3 VAR = 0.3,0.1 COV = -1.0
EIGENVALUES = 2.0,0 OBJ_DIRECT = 0,100.0
correlation_o = -1.0 INVCOVARIANCE_O = -1 INVCOVARIANCE_D = -1
etashrink = 0,20 epsshrink = 0,10
METHOD = DIRECT ALL = -1
METHOD = `SAEM` epsshrink = 0,20

The $IGNORE record will ignore all elements that are listed, or just a specific attribute of an element, such as nonmem(version). Under the $PRECISION record, a

GENERAL=R,A

can be given for most items, where relative is the relative tolerance, and absolute is the absolute tolerance. Following the GENERAL specification, tolerances may be specified for other items. Two items of identical element and attributes are compared between the two files, where the equation for comparison is, between value X of xml file 1 and value Y of xml file 2,

\[\mathrm{ABS}(X - Y) > R \cdot \mathrm{MAX}(\mathrm{ABS}(X), \mathrm{ABS}(Y)) + A\]

The OBJ_BAYES is given a special test, as it has a standard deviation with it:

\[\mathrm{STD}(X, Y) = \sqrt{\mathrm{STD}(X)^2 + \mathrm{STD}(Y)^2}\]

\[\mathrm{ABS}(X - Y) > R \cdot \mathrm{STD}(X, Y) + A\]

In the above example OBJ_BAYES=(2,0) means that if the Bayes objective functions in the two files differ by more than 2 standard deviations, then the difference is noted.

To ignore an item for comparison, specify -1. To specify an exact comparison, use 0,0. To refer to a particular optimization method, then enter METHOD=SAEM for example, and thereafter, all entries of items pertain to that estimation method, until METHOD is changed.

The METHOD attribute may have one of the following settings:

`FOCE`, `ITS`, `IMP`, `SAEM`, DIRECT, `BAYES`

For the total list of items, and their scope:

See INTRODUCTION TO NONMEM 7, xml_compare Utility Program and its Use for Installation Qualification.

Because of the versatility of selecting which items are to be compared and with what precision, the xml_compare program can be used for batch processing installation qualification procedures, in comparing NONMEM results of a test run against a reference run. All results given in the standard NONMEM output file are also reported in the XML file.

REFERENCES: Guide Introduction_7