50 NM-TRAN Control Records

The $XXX-prefixed NM-TRAN control records, alphabetical.

1 `$ABBREVIATED`

MEANING: Provides instructions about abbreviated code.

CONTEXT: NM-TRAN Control Record

USAGE:

$ABBREVIATED [COMRES = n1] [COMSAV = n2]
[DERIV2 = NO] [DERIV2 = NOCOMMON] [DERIV1 = NO]
[FASTDER | NOFASTDER]
[CHECKMU | NOCHECKMU]
[DES = COMPACT|DES = FULL]
[REPLACE left_string = right_string] ...
[DECLARE [type] [DOWHILE] name [(dimension [,dimension])] ...
[PROTECT]
[FUNCTION function_name(input_vector_name,dimension[,usage])]
[VECTOR input_vector_name(dimension)]

SAMPLE:

COMRES = 2
$ABBREVIATED

DISCUSSION:

Optional. May be used when $PK, $ERROR, or $PRED abbreviated code is present. Must precede all blocks of abbreviated code. With NONMEM 7.4, may also be used when there is no abbreviated code. For example, $ABBR REPLACE may be used for label substitution in NONMEM report files.

OPTIONS:

COMRES=n1 (‘common reserve’): COMRES gives instructions to NM-TRAN. Values of n1:

-1 Do not store any variables in the global variable array, VRBL, in the NMPRD4 module.
0 Store variables in NMPRD4 with no reserved positions (the default).
n1 Store variables in NMPRD4, but reserve the first n1 positions.

With abbreviated code, the Ith position in NMPRD4 is referenced by COM(I).

This option is intended for advanced users of NONMEM, e.g., when abbreviated code is combined with user-supplied subroutines or verbatim code. A user-supplied subroutine may reserve the first n1 positions in NMPRD4 for its use, in which case the option COMRES should be set to n1 to instruct NM-TRAN to skip these positions; the first position used by NM-TRAN for storing variables defined in abbreviated code will be position n1 + 1.

$TABLE and $SCATTER may explicitly reference variables in reserved positions 1 through n1 by COM(1) through COM(n1), respectively, in addition to listing variables defined in abbreviated code by name.

An individual block of abbreviated code (e.g. $PK) may include the pseudo-statement COMRES=-1, which prevents any variable defined in that particular block from being stored in NMPRD4.

COMSAV=n2 (‘common save’): Values of variables displayed in tables and scatterplots are obtained from NMPRD4. There are particular times when data records are passed to PRED for the purpose of obtaining these values; these are called copying passes. The SAVE region of NMPRD4 is the initial part of this array. If a variable is stored in the SAVE region, then the value of the variable computed with a given data record during a copying pass will be found in NMPRD4 when the same record is passed during the next copying pass, i.e. it will have been saved from the previous copying pass. This is in contrast to the usual behaviour, where with a given data record, the value in NMPRD4 is the value computed with the previous data record.

n2 is the initial size of the SAVE region, i.e. the number of positions in this region. n2 = 0 is the default value. n2 may not exceed n1. The SAVE region has size n2 initially, but NM-TRAN may extend it if SAVE variables are used. However, if n2 = -1, the SAVE region is not to be extended, and there is to be no SAVE region altogether. (See Section 53.22).

When PREDPP is used, and a $PK block is present, NM-TRAN inserts code into the PK routine that stores the value of COMSAV at ICALL=1. If no $PK block is present, and a $ERROR block is present, the code is inserted into the ERROR routine. When PREDPP is not used, and a $PRED block is present, the generated or library PRED routine stores the value of COMSAV at ICALL<=1.

DERIV1=NO (NM74): Prevents the computation of first derivatives. For example, may be used when only SAEM or BAYES is performed, or IMPMAP/ITS/FOCE are performed using OPTMAP>0 and ETADER>0. The global variable NOFIRSTDERCODE is set to 1.
DERIV2=NO: Prevents the computation of second derivatives, which are needed only for the Laplacian method.
DERIV2=NOCOMMON: Permits the computation of these derivatives, but prevents them from being stored in the global variable NMPRD4. $ESTIMATION METHOD=COND LAPLACIAN may be specified, but variables representing second derivatives are not stored in NMPRD4. Therefore, they cannot be displayed in tables and scatterplots. In addition, no variables computed in the $PK block may be referenced in the $ERROR block. This is true whether or not these variables happen to have second derivatives, and whether or not the Laplacian method is used.
FASTDER, NOFASTDER: With NONMEM 7.2 and higher, NM-TRAN collects statements that compute first-partial eta-derivatives together in FSUBS, and they are performed only when NONMEM sets IFIRSTEM=1. NOFASTDER prevents NM-TRAN from doing this, and restores the order of statements in FSUBS to what it was in previous versions.

FASTDER requests that the statements be collected, and is the default. (See Section 53.73).

CHECKMU, NOCHECKMU: With NONMEM 7.2 and higher, NM-TRAN checks the MU model statements in abbreviated code and issues warning messages if they appear to contain mistakes. This can take a long time for large control streams. Also, in the examples directory, there are control streams for which the check is too difficult for NMTRAN (tdist6_sim.ctl and tdist7.ctl), and some for which the warnings are inappropriate (the “superid” control streams that use $LEVEL). NOCHECKMU can be used to prevent NM-TRAN from attempting to check the MU model statements.

CHECKMU requests that MU model statements be checked, and is the default. Neither option affects the generated code.

DES=FULL: Arrays of the DES routine are stored in non-compact form. With $ESTIMATION METHOD=COND LAPLACIAN, the option NUMERICAL is also required. DES=FULL is the default with ADVAN9 and ADVAN15 and ADVAN17. (Prior to NONMEM 7.4, FULL was required with ADVAN13.)
DES=COMPACT: Arrays of the DES routine are stored in compact form. Required with Laplacian method; optional otherwise. This is the default, except with ADVAN9 and ADVAN15 and ADVAN17.
REPLACE left_string = right_string: There are several different forms of the REPLACE option. They do not affect verbatim code. Case is ignored.

Simple replacement REPLACE left_string = right_string

May be used in all blocks of abbreviated code and $TABLE and $SCATTER records. left_string is replaced by right_string. The search is “anchored” by a Fortran identifier. That is, left_string is parsed for the first Fortran identifier and the abbreviated code is searched for the same identifier. Following the identifier, the entire left_string must match the abbreviated code. Single or double quotes around a string are optional. They are necessary if the string contains punctuation such as a comma. A given line of abbreviated code may have multiple replacements; they are applied in the order that they appear in the NM-TRAN control stream.

Examples:

$ABBR REPLACE PI = 3.14159265
$ABBR REPLACE THETA(CL) = THETA(4)
$ABBR REPLACE ETA(CL) = ETA(5)
$ABBR REPLACE K34 = "3,4"

...
CL = PI * THETA(CL) * EXP(ETA(CL))
PRINT *,OMEGA(K34)

The post-replacement code is

CL = 3.14159265 * THETA(4) * EXP(ETA(5))
PRINT *,OMEGA(3,4)

With this feature, subscripts of THETA, ETA, and EPS and ERR may be given symbolic names in abbreviated code, and $ABBR REPLACE is used to replace them with integer subscripts. With NONMEM 7.4, this feature also requests label substitution in NONMEM report files and table files. For example, the following will cause all appearances of ETA(CL) to be replaced by ETA(3) in the generated subroutine, and will cause ETA(3) to be replaced by ETA(CL) in the NONMEM report and any table file in which ETA(3) is listed.

$ABBR REPLACE ETA(CL) = ETA(3)

Label substitution can be turned off for an entire problem with NOSUB=1 option of the $DEFAULT record. Label substitution can be turned off for a specific NONMEM task (and all subsequent tasks) with the NOSUB=1 option of $TABLE, $SCAT, and $ESTIMATION.

Substitutions will never be made in the additional output files *.ext, .phi, etc., to maintain their third party software readability.

With this feature, compartment names may be used instead of compartment numbers. For example,

$ABBR REPLACE A(DEPOT) = A(1)
$ABBR REPLACE DADT(DEPOT) = DADT(1)

...
$DES
DADT(DEPOT) = -KA * A(DEPOT)

This is called “explicit” compartment name substitution. With NONMEM 7.5, compare the “implicit” compartment name substitution feature of the $MODEL record.

See INTRODUCTION TO NONMEM 7, Symbolic Label Substitutions of Model Compartments.

Replacement with selection by data item $ABBR REPLACE VAR(d)=VAR(n1,n2,..,nk) May be used in $PK, $ERROR, $PRED blocks only. VAR must one of ETA, EPS, THETA. (ERR is not permitted.) d must be a data item. The integer value of d (i.e., INT(d)) is used to select one of n1,n2,..,nk. If any of the ni is 0, that position is skipped. The effective code is:

IF (d.eq.1) VAR(d)=VAR(n1)
IF (d.eq.2) VAR(d)=VAR(n2)
  ...

The actual generated code uses Q-type indicator variables, and variables such as THETA_OCC_ in place of THETA(OCC).

Example: Suppose OCC is a data item that takes values 1 and 2.

$ABBR REPLACE THETA(OCC) = THETA(4,7)

...
$PK
TVCL = THETA(OCC)

The effective code after replacement is

IF (OCC==1) TVCL = THETA(4)
IF (OCC==2) TVCL = THETA(7)

A user-defined variable can be given a default value in case the implied selection is not satisfied. E.g., suppose there are 3 doses per subject (DOSN=1,2,3) and the model is:

$PK ...
IF(DOSN == 1) F1 = 1
IF(DOSN == 2) F1 = 1 * EXP(ETA(2))
IF(DOSN == 3) F1 = 1 * EXP(ETA(3))

The model can be implemented using implied selection as follows:

$ABBR REPLACE ETA(DOSN) = ETA(0,2,3)

$PK ....
F1 = 1
IF (DOSN>1) F1 = 1 * EXP(ETA(DOSN))

Replacement with selection by data item and parameter $ABBR REPLACE VAR(p_d)=VAR(n1,n2,..,nk) p is a user-defined variable in the abbreviated code. The order may be p_d or d_p. This allows a given data item d to be used as a selection variable for more than one parameter, with a different choice of elements of VAR.

Example 1:

$ABBR REPLACE THETA(SID_KA) = THETA(4,6)
$ABBR REPLACE THETA(SID_CL) = THETA(5,7)

...
$PK
KA = THETA(SID_KA)
CL = THETA(SID_CL)

which is equivalent to

$PK
IF (SID==1) KA = THETA(4)
IF (SID==2) KA = THETA(6)
IF (SID==1) CL = THETA(5)
IF (SID==2) CL = THETA(7)

Example 2:

$ABBR REPLACE ETA(OCC_CL) = ETA(5,3)
$ABBR REPLACE ETA(OCC_V) = ETA(6,4)

...
$PK
CL = TVCL * EXP(ETA(1) + ETA(OCC_CL))
V = TVV * EXP(ETA(2) + ETA(OCC_V))

which is equivalent to

$PK
IF (OCC==1) CL = TVCL(EXP(ETA(1) + ETA(5))
IF (OCC==2) CL = TVCL(EXP(ETA(1) + ETA(3))
IF (OCC==1) V = TVV(EXP(ETA(2) + ETA(6))
IF (OCC==2) V = TVV(EXP(ETA(1) + ETA(4))

The number of values specified for the selection data item must be consistent for all parameters in which it is used.

Replacement for multiple variables $ABBR REPLACE VAR( p1, p2,..., pk )=VAR(n1,n2,...,nk ) This form is new to NONMEM 7.4. The pi are character strings separated by commas. A character string may not contain an embedded space. The lists on both left and right sides must be of the same length. VAR( pi) is replaced by VAR(ni). For example,

$ABBR REPLACE THETA(CL,V1,Q,V2) = THETA(1,2,3,4)

This is equivalent to:

$ABBR REPLACE THETA(CL) = THETA(1)
$ABBR REPLACE THETA(V1) = THETA(2)
$ABBR REPLACE THETA(Q) = THETA(3)
$ABBR REPLACE THETA(V2) = THETA(4)

Label substition occurs with this form, as with Simple replacement (1).

Short-hand notation A short-hand notation may be used to describe a series of values of ni. An ascending sequence of ni can be described as

,start TO end [BY interval]

BY is optional and must be > 0. Default is 1. TO is required. If end < start, the sequence is ignored. At least one comma must appear, so NMTRAN knows it is a number list, not a variable name. With NONMEM 7.4, the character : may be used instead of TO, and the value of BY may be negative.

EXAMPLES:

$ABBR REPLACE THETA(SID_KA) = THETA(10:4 by 3) ; order: 10,7,4
$ABBR REPLACE THETA(SID_KA) = THETA(4 to 10 by - 3) ; order: 10,7,4
$ABBR REPLACE THETA(SID_KA) = THETA(10 to 4) ; order: 10,9,8,7,6,5,4

$ABBR REPLACE THETA(SID_KA) = THETA(,4 to 13 by 3,25 to 37 by 4)

is identical to

$ABBR REPLACE THETA(SID_KA) = THETA(4,7,10,13,25,29,33,37)

Files FORIG and FREPL When $ABBR REPLACE is coded, NM-TRAN produces two files: FORIG Contains the original (pre-replacement) abbreviated code, and task specification records $TABLE and $SCATTER. FREPL Contains the new (post-replacement) abbreviated code and task specification records. These may be helpful for debugging.

DECLARE [INTEGER] [DOWHILE] name [(dimension [,dimension])] ...: One or names may be coded. They are referred to as “declared variables.” If INTEGER or DOWHILE is coded, the type of the variable is integer. Otherwise, the type of the variable is double precision. If one or two dimensions are declared, the variable being declared is an array. Each dimension may be a number or a variable or an expression. Constants defined in SIZES (e.g., NO, LVR) may be used. Multiple DECLARE options may be coded. The characters DECLARE are optional after the first. Commas are ignored, and type and dimensions must be respecified as needed. No other options of $ABBR may appear after the DECLARE option(s). Declared variables are global, i.e., are defined in all blocks of abbreviated code. The number of subscripts must agree with the number of dimensions in the declaration. Declared variables that are not INTEGER or DOWHILE will be random variables if they are assigned in a statement whose right-side involves ETA’s or EPS’s.

EXAMPLE:

$ABBR DECLARE A,B(10),C(1,NO - 1),INTEGER I J

Only I is INTEGER.

Variables may be declared as INTEGER or DOWHILE for use as subscripts of declared arrays or reserved variables that are arrays (but not of ETA, ERR, or EPS).

Variables used as looping indices in DOWHILE statements must be declared as DOWHILE variables.

Declared variables are automatically initialized to 0.

Elements of a declared array may be displayed in WRITE/PRINT statement, but not the entire array. E.g., the following is permitted

PRINT *,B(1),B(2)

but not

PRINT *,B

Neither individual elements nor the entire array may be listed in $TABLE. The workaround is to code, e.g.,

... code assigning values to B(1) etc. ...
B1 = B(1)
$TABLE B1

(See Section 53.35).

PROTECT: With NONMEM 7.4, a series of routines are available that protect against domain violations, divide by zero, and floating point overflows. Each of these routines start with the letter P, followed by the name of the mathematical operation they are to perform. For example, PLOG is the protective code routine that performs the LOG operation. With $ABBR PROTECT, NMTRAN will automatically replace all relevant function names with the P name.

(See Section 53.90).

FUNCTION function_name(input_vector_name,dimension[,usage]): With all versions of NONMEM since NONMEM VI, user-supplied functions are permitted in abbreviated code with reserved names such as FUNCA, FUNCB, …, and argument vectors with reserved names such as VECTRA, VECTRB, …. With NONMEM 7.4, extended reserved names are recognized. These are FUNCxy and FUNCxyz, where each of x, y, z stands for an alphabetic character A-Z, e.g., FUNCAB or FUNCABC. Similar extended reserved names for vectors are also recognized: e.g., VECTRAB or VECTRABC. Reserved argument vectors and arrays have dimension 9 and each reserved function may appear in abbreviated code at most 9 times. (See Section 53.2).

In NONMEM 7.4 the $ABBR FUNCTION option allows user-defined function names and user-defined argument vector names. The dimensions of the argument vector and the maximum number of times a given function name may appear in abbreviated code is user-specified.

A user-defined function may be declared as follows:

$ABBR FUNCTION function_name(input_vector_name,dimension,usage)

function_name is the name of the function.

input_vector_name is the name of an input vector that may be used to pass arguments to the function.

dimension specifies how many input arguments function_name will use, and defines input_vector_name as a vector with this length. “Dimension” is a property of both the function and of the input vector.

usage is the maximum number of times the function may appear in the abbreviated code, that is, the maximum number of occurances of function_name. It is not an error if there are fewer occurances. If usage is omitted, NMTRAN will supply the exact number. If usage is coded, NMTRAN will generate an error message if function_name appears in abbreviated code more than usage number of times.

A vector and its length may be declared independently of a function,

$ABBR VECTOR input_vector_name (dimension)

input_vector_name is the name of an input vector.

dimension is the length of the vector. The dimension of a vector should be no less than the dimension of all the functions which which it is used.

Example:

$ABBR FUNCTION BIVARIATE(VBI,5,3)

A vector VBI is defined of length 5. There is a function called BIVARIATE. When BIVARIATE is used, the value 5 is passed to it as argument NDIM. BIVARIATE uses 5 elements from the input vector. Function BIVARIATE may appear in abbreviated code at most 3 times. BIVARIATE should be present in a source code file listed in the $SUBROUTINES record:

$SUBROUTINES OTHER = filename

Instructions for coding both reserved functions and user_defined functions are in Abbreviated Function.

Here is an example of abbreviated code that uses BVI and BIVARIATE:

$PK ...
VBI(1) = RHO
VBI(2) = 5
VBI(3) = 6
VBI(4) = 1 ;** * 0 = Upper tail as in Drezner & Wesolowsky
; 1 = Bottom tail***;
VBI(5) = 1 ;** * 0 = 3 pt approximation
; 1 = 5 point approximation***;
BV = BIVARIATE(VBI)

There is a fully worked out example. (See Section 60.17). Files are in the examples directory: bivariate.ctl, bivariate.csv, bivariate.f90.

By default, there may be up to 100 different user-defined functions, which includes functions with reserved names and user-defined names. There may also be up to 100 different vectors of input arguments, which includes vectors with reserved names and user-defined names. Constants NFUNCX and NVECX in SIZES may be used to change these numbers.

It is preferable that a unique vector should be associated each function to assure that each vector-function pair are set up with comparable dimensions. This is not necessary. Any user-defined vector or function may be used with any reserved vector or reserved function, subject to the same restriction. For example:

$ABBR FUNCTION BIVARIATE(VBI,5)
$ABBR FUNCTION BIVARIATEQ(VQI,10)

In abbreviated code, any of the following are permitted:

BVI=BIVARIATE(VBI)
BVQ=BIVARIATE(VQI)
BVQI=BIVARIATEQ(VBI)
BVQQ=BIVARIATEQ(VQI)

NM-TRAN gives a warning:

(WARNING 133) DIMENSION OF VECTOR IS LESS THAN
              WHAT IS EXPECTED BY FUNCTION
BVQI=BIVARIATEQ(VBI(001),FNC002_1(1,001),FNC002_2(1,1,001),10)

This is because vector VBI has dimension 5 and function BIVARIATEQ was declared with dimension 10. Note that the results will be correct if BIVARIATEQ does not use more than 5 positions in the argument vector.

A vector and its length may be declared independently of a function, and vice versa. The asterisk is used as a placeholder, e.g.,

$ABBR FUNCTION BIVARIATE(*,5)
; when BIVARIATE is called, NDIM will be 5
$ABBR FUNCTION BIVARIATEQ(*,10)
; when BIVARIATEQ is called, NDIM will be 10
$ABBR VECTOR VQI(15)

The $ABBREV FUNCTION record may be used to override the default settings for any of the reserved function or vectors. For example,

$ABBR FUNCTION FUNCA(VECTRA,25,5)

VECTRA will be defined with length 25, not 9 as for a reserved function. The code for the function should have NDIM as an argument:

FUNCTION VECTRA(X,X1,X2,NDIM)

NDIM should be used instead of 9 for vector and array dimensions, as shown in the Abbreviated Function help item.

REFERENCES: Guide IV, section III.B.7, IV; Guide Introduction_7

2 `$AES`

MEANING: Marks the beginning of abbreviated code for the AES routine.

CONTEXT: NM-TRAN Control Record

USAGE:

$AES
abbreviated code

DISCUSSION:

The $AES record is used to compute algebraic expressions which can be regarded as specifying equilibrium kinetics. It is used with PREDPP’s ADVAN9 and ADVAN15 and ADVAN17. (See Section 50.3). General rules for abbreviated code are documented elsewhere (See Section 53.1). Specific rules follow.

ASSIGNMENT AND CONDITIONAL STATEMENTS

Left-hand quantities in assignment statements:

E(ncm1+1), E(ncm1+2), … (Required. Expressions which, when set to 0, constitute the system of algebraic expressions describing the equilibrium kinetics. ncm1 is the number of nonequilibrium compartments.) The indices (...) may be omitted, in which case NM-TRAN will supply them according to the order in which the expressions appear. Indices are required when the expressions are defined conditionally (i.e., using an IF statement).
AES-defined (i.e., PRED-defined) items.

Right-hand quantities in assignment statement and in conditions:

A(1), A(2), … (Current compartment amounts; may be random variables.)
P(1), P(2), … (Post-translation basic PK parameters; may be random variables.)
PK-defined items (Implicit basic PK parameters; may be random variables.)
T (Time; may be random variable. T takes values continuously over an integration interval.)
AES-defined variables that appeared earlier as left-hand quantities in $AES, and similarly from the $AESINITIAL record. (Caution: AESINITIAL-defined variables that depend on compartment amounts will depend on the initial values of these compartment amounts, not the current values.)
Data item labels specified on the $INPUT statement.
THETA(n).
Global Variables in Modules

Certain variables in FORTRAN modules can be used. (See Section 53.111) The following are of particular interest.

DOSTIM DOSTIM is the time of a lagged dose or additional dose to which the system is being advanced. Abbreviated code in $AES may test DOSTIM. It may use DOSTIM on the right, unless DOSTIM is a random variable. However, it may be used on the right in a $PK block to define a random variable which may in turn be used on the right in the $AES block.

DOSREC DOSREC is the dose record corresponding to the dose entering at DOSTIM. Abbreviated code in $AES may test items in DOSREC in a logical condition, and DOSREC may always be used on the right.

ISFINL During simulation or a copying pass, and during the advance to a particular time (event or non-event time), ISFINL=1 at a final call to AES at that time. Otherwise, ISFINL=0.

Forbidden Variable Names:

IR DA DP DT ETA(n) EPS(n) ERR(n)

RECORD ORDER: Follows $SUBROUTINES $INPUT $MODEL $PK. Follows $AESINITIAL. (See Section 53.6, Section 56.12, advan9_17).

REFERENCES: Guide IV, section V.C.9; Guide VI, section VI.E

3 `$AESINITIAL`

MEANING: Marks the beginning of abbreviated code for the AES routine.

CONTEXT: NM-TRAN Control Record

USAGE:

$AESINITIAL
abbreviated code

DISCUSSION:

The $AESINITIAL record is used to compute the amounts in the equilibrium compartments at the beginning of an integration interval. It is used with PREDPP’s ADVAN9, ADVAN15, and ADVAN17. May also be coded $AES0. (See Section 53.6). General rules for abbreviated code are documented elsewhere (See Section 53.1). Specific rules follow.

ASSIGNMENT AND CONDITIONAL STATEMENTS

Left-hand quantities in assignment statements: A(ncm1+1), A(ncm1+2), … (Required. The amounts in the equilibrium compartments at the beginning of the integration interval. ncm1 is the number of nonequilibrium compartments.)

INIT (Initialization flag.)

INIT=0: The A(n) are approximate.
INIT=1: The A(n) are exact (the default).

AESINITIAL-defined (i.e., PRED-defined) items.

Right-hand quantities in assignment statement and in conditions:

A(1), A(2), … (Current compartment amounts; may be random variables.)
P(1), P(2), … (Post-translation basic PK parameters; may be random variables.)
PK-defined items (Implicit basic PK parameters; may be random variables.)
T (Time at the beginning of the integration interval; may be random variables.)
AESINITIAL-defined items that appeared earlier as left-hand quantities.
Data item labels specified on the $INPUT statement.
THETA(n).
Global Variables in Modules. Certain variables in FORTRAN Modules can be used. (See Section 53.111).

Forbidden Variable Names:

IR DA DP DT E(n) ETA(n) EPS(n) ERR(n)

PSEUDO ASSIGNMENT STATEMENTS

COMRES=-1

CALLFL=-1: Call ADVAN and AES with every event record (default). CALLFL=1: Call ADVAN and AES once per individual record.

(CALLFL may be used only when the TIME data item is not defined.) The pseudo assignments statements may be enclosed in parentheses. If both are present within the same set of parentheses, separate them with a semicolon. Within parentheses, a calling protocol phrase may be used instead of CALLFL, and either upper or lower case may be used. E.g.,

$AESINIT (ONCE PER IR) ; same as CALLFL = 1
$AESINIT (EVERY EVENT) ; same as CALLFL = -1 (default)

(See calling protocol).

RECORD ORDER:

Follows $SUBROUTINES $INPUT $MODEL $PK. Precedes $AES.

REFERENCES: Guide IV, section V.C.8; Guide VI, section VI.E

4 `$ANNEAL`

MEANING: Sets starting diagonal Omega values to facilitate EM search methods.

CONTEXT: NM-TRAN Control Record

USAGE:

$ANNEAL number-list1:value1 number-list2:value2 ...

SAMPLE:

$ANNEAL 1-3,5:0.3 6,7:1.0

DISCUSSION:

Sets starting diagonal Omega values for purposes of simulated annealing by NONMEM subroutine CONSTRAINT. In the above example, initial values of OMEGA(1,1), OMEGA(2,2), OMEGA(3,3), and OMEGA(5,5) are set to 0.3, while initial OMEGA(6,6) and OMEGA(7,7) are set to 1.0. A number-list may contain a single integer, a range of integers (with -), or a series of integers and ranges separated by comma. Required. A value may be any numeric value. Optional; default is 0.

When $EST CONSTRAIN>=4, an algorithm in subroutine CONSTRAINT will initially set the omegas to these values, and then shrink these OMEGA values more and more with each iteration, and eventually shrinks the OMEGA’s to 0, the intended target value for that Omega. This is a technique that may be used especially with SAEM, to provide an annealing method for moving thetas that have 0 omega values associated with them. The default is the use of gradient methods, which are good for problems starting near the solution, whereas the annealing method is more suitable for problems starting far from the solution.

Subroutine CONSTRAINT obtains values entered via $ANNEAL record in the array OMEGANNL. Any value that is set to 0 in $ANNEAL is given the default value of .3. This record is optional. If omitted, the starting values of Omega are those specified in the $OMEGA record.

NONMEM’s default CONSTRAINT.f90 is identical to Subroutine source/CONSTRAINT.f90.

See INTRODUCTION TO NONMEM 7, $ANNEAL to facilitate EM search methods.

REFERENCES: Guide Introduction_7

5 `$BIND`

MEANING: Define data values used by $PK, $DES, and $AES.

CONTEXT: NM-TRAN Control Record

USAGE:

$BIND [value1] [value2] ...

DISCUSSION:

$BIND is optional. It may be used when $PK abbreviated code is present and this code requests that the PK subroutine be called at additional or lagged dose times (CALLFL=-2). It is used to override the default values of user-defined variables used in the code when the PK routine is called at these particular dose times. It is also used to override the default values of user-defined variables used in $DES and $AES abbreviated code during an advance to an additional or lagged dose time.

$BIND has no effect when PK is called at a model event time (MTIME).

Let t be a time at which an additional or lagged dose enters the system. If t1 is the greatest event time not exceeding the time t, then the “last event record” is the last event record with event time t1, and the “next event record” is the event record following the last event record. (The term “last” is similar to the word “previous” in this context.) The event time on the next event record will exceed time t.

OPTIONS:

The positions of the values correspond to the positions of data items in the $INPUT record in a 1-to-1 manner. Each value is one of:

DOSE (Use the value from the dose record.)
NEXT (Use the value from the next event record.)
LAST (Use the value from the last event record.)
SKIP (Ignore this data item.)
DROP (Ignore this data item.)
- (Default.)

For user (concomitant) data items, the default is NEXT but any of DOSE, NEXT, LAST may be specified.

For the PREDPP data item TIME, the default is NEXT. Only - or NEXT may be specified.

For all other PREDPP or NONMEM data items, the default is DOSE. Only - or DOSE may be specified.

Option DROP in the $BIND record is optional. It is ignored by NM-TRAN, but helps the user maintain a 1-to-1 relationship between positions in $BIND and positions in $INPUT.

A $BIND record with all defaults specified, such as

$BIND - - - - - - -

has the same effect as if no $BIND record were present.

EXAMPLE:

$INPUT ID TIME DATE = DROP AMT DV WGT PREP X HGT
$BIND - - DROP - - NEXT DOSE LAST -

ID, AMT, DV have the values from the initiating dose record. TIME has the value from the next event record. WGT and HGT have values from the next event record. PREP has the value from the initiating dose record. X has the value from the last event record. This record will be the dose record if there is no other event record between the dose record and the next event record.

$INPUT and $BIND records can be interleaved to help maintain a visual relationship. The above example could have been coded:

$INPUT ID TIME DATE = DROP
$BIND - - DROP
$INPUT AMT DV WGT PREP X HGT
$BIND - - NEXT DOSE LAST -

$BIND may not specify a position beyond the last position defined via $INPUT. It may specify fewer positions, in which case defaults apply to the remaining data items.

Changes to $BIND, like changes to $INPUT, cause changes to generated code. Thus, an existing NONMEM executable cannot be re-used when the $BIND and/or $INPUT records are changed.

The $BIND record only applies under the following circumstances:

There exists a dose that is either one or both of the two following types of doses:

An additional dose, subsequent to the initiating dose (ADDL>0, II>0 in the dose event record). Such a dose enters the system at the “additional dose time.”
A lagged dose. (With the corresponding dose event record, PK specifies ALAGi>0, where i is the index of the dose compartment). Such a dose enters the system at the “lagged dose time.”

The PK subroutine computes parameters that depend on values in the data record which are not constant for the individual, i.e., parameters depend on time-varying data items.
The PK subroutine is called when the dose enters the system. That is, $PK contains the pseudo-statement CALLFL=-2, requesting that the PK routine be called to compute values of the PK parameters at additional and lagged dose times. When $PK does not contain this pseudo-statement, there is no such call, and at an additional or lagged dose time, the PK parameters have those values computed with the next event record.

When the $PK code is implemented with an event record, the variable DOSTIM is 0. When it is implemented at an additional or lagged dose time, the value of this variable is the time in question. By default, data items used in abbreviated code have values from either the initiating dose record (DOSREC) or the next event record (EVTREC), according to this rule:

NONMEM data items and PREDPP data items (other than TIME) have values from the original dose event record (DOSREC). These are:

DV MDV ID L2 MRG_ RAW_ REPL_ EVID AMT RATE SS II CMT PCMT CALL
CONT ADDL DATE DAT1 DAT2 DAT3

TIME and all user-defined data items have the values from the next event record (EVTREC). This default can be overridden using the $BIND record.

EXAMPLE:

The $BIND record is a convenience; it does nothing that cannot be accomplished with abbreviated code. Suppose X is a user-defined data item. The following three fragments of code create a variable XB with the same values at calls with additional and lagged doses that X would have if there were a $BIND record specifying the following for X.

DOSE:

IF (DOSTIM == 0) THEN
 XB = X
ELSE
 XB = DOSREC(X)
ENDIF

XB=X

LAST:

IF (DOSTIM == 0) THEN
 XB = X
ENDIF

In this case, when DOSTIM>0, XB retains its value from the previous call to PK. (See Section 60.16).

REFERENCES: Guide IV, section V.C.2, V.C.5

6 `$CHAIN`

MEANING: Supplies initial estimates for an entire problem.

CONTEXT: NM-TRAN Control Record

USAGE:

$CHAIN [FILE = filename]
[FORMAT = s] [ORDER = xxxf]
[NOTITLE = [0|1]] [NOLABEL = [0|1]]
[ISAMPLE = n][NSAMPLE = n]
[SEED = n]
[CLOCKSEED = [0|1]]
[SELECT = n]
[RANMETHOD = [n|S|m]]
[CTYPE = [0|1|2|3|4]]
[DF = n]
[DFS = n]
[IACCEPT = x]
[TBLN = n]

SAMPLE:

$CHAIN FILE = example1_previous.txt NSAMPLE = 0 ISAMPLE = -1000000000

DISCUSSION:

Option METHOD=CHAIN of the $ESTIMATION record will only set thetas, omegas, and sigmas for initial values of the estimation process. Its scope is therefore limited in that it will not impact the parameters used in simulating data for the Simulation step. To introduce initial THETAs omegas and sigmas that will cover the entire scope of a given problem, use the $CHAIN record.

The options have the same meanings as for the $ESTIMATION record. Setting SEED or CLOCKSEED or RANMETHOD in a $CHAIN record does not propagate to $EST METHOD=CHAIN or any other $EST record. (See Section 50.14). (See $ESTIMATION_record).

REFERENCES: Guide Introduction_7

7 `$CONTR`

MEANING: Defines values for certain user-supplied routines.

CONTEXT: NM-TRAN Control Record

USAGE:

$CONTR DATA = ([label1|0] [label2|0] [label3|0])

The data item with the Jth label (J=1,2,3) and from the Ith observation record of an individual record is available in DATA(I,J). If 0 is used instead of a label, then a zero appears in DATA(I,J).

SAMPLE:

$CONTR DATA = (0,TYPE)

DISCUSSION:

Optional. Used only with user-supplied routines such as MIX and CONTR and CCONTR that use data items stored in the DATA array. This record gives labels (or synonyms) defined in the $INPUT record of one to three types of data items to be made available to the subroutine(s) in the DATA array. These routines are called with individual records. An array DATA is available in NONMEM module ROCM_REAL and changes value with each individual record.

With the above sample $CONTR record, the following code might be present in a double precision MIX routine. The code loops through the observation records of the NREC’th individual record. For each of the NOBS observation records, the local variable TYPE is given the value of the TYPE data item from that data record. The 0 in the sample is a place-holder which causes the first column in the DATA array to be skipped. The value of TYPE for the Ith observation record is therefore available in DATA(I,2). The DATA array is found in ROCM_REAL. NO is a constant giving the maximum number of observations per individual record. NOBS is the number of observations in the current individual record. (See Section 50.41).

USE SIZES, ONLY: NO,DPSIZE
USE ROCM_REAL, ONLY: DATA=>RDATA
USE ROCM_INT, ONLY: NOBS=>NOBSIND2
...
INTEGER I
REAL(KIND=DPSIZE) :: TYPE
...
DO 100 I=1,NOBS
TYPE=DATA(I,2)
...
100 CONTINUE
...

REFERENCES: Guide IV, section III.B.4

8 `$COVARIANCE`, `$COVR`

MEANING: Instructions for NONMEM Covariance Step

CONTEXT: NM-TRAN Control Record

USAGE:

$COVARIANCE [SPECIAL] [MATRIX =] [PRINT = [E][R][S]
[COMPRESS]
[SLOW|NOSLOW|FAST]
[TOL = n] [ATOL = n]
[SIGL = n] [SIGLO = n]
[NOFCOV]
[PARAFILE = [filename|ON|OFF] [PARAFPRINT = n]
[THBND = n]
[SIRSAMPLE = [numberlist] [SIRNITER = n] [SIRCENTER = n]
[IACCEPT = x] [IACCEPTL = x]
[SIRDF = n] [RANMETHOD = [n|S|m|P]]
[SIRPRINT = n] [FILE = filename] [FORMAT = s]
[SIRTHBND = n]
[SIRMINWT = x] [SIRMAXWT = x] [SIR_CAPCORR = x]
[SIRSEED = n] [SIRCLOCKSEED = [0|1]]
[SIRPARAFILE = [filename|ON|OFF] [SIRPARAFPRINT = n]
[PRECOND = n] [PRECONDS = TOS] [PFCOND = n] [PRETYPE = n]
[FPOSDEF = n]
[CHOLROFF = n] [KNUTHSUMOFF = n]
[POSDEF = n]
[RESUME]
[CONDITIONAL|UNCONDITIONAL]
[OMITTED]

SAMPLE:

$COVARIANCE

DISCUSSION:

Optional. Requests that the NONMEM Covariance Step be implemented. This step outputs: standard errors, covariance matrix, inverse covariance matrix, and the correlation form of the covariance matrix. May also be coded $COVR.

If $COV is specified, then for IMP, IMPMAP, and ITS methods, standard error information will be supplied for every $EST statement. Standard error information for the classical methods (METHOD=0, METHOD=1) will be given only if they are the last estimation method, and only if NOFCOV is not specified.

OPTIONS:

SPECIAL: The special computation will be used in the Covariance Step with a recursive PRED subroutine. A recursive PRED subroutine is such that, with single-subject data, the PRED computation with a data record depends on information passed to it with any of the previous data records. This is the default when PREDPP is used.
MATRIX=c: Specifies that the covariance matrix will be different from the default (R-1SR-1). MATRIX=R requests that 2 times the inverse R matrix be used. MATRIX=S requests that 4 times the inverse S matrix be used. (R and S are two matrices from statistical theory, the Hessian and Cross-Product Gradient matrices, respectively.) With MATRIX=R the standard errors will be more consistent with other nonlinear regression software implementations. MATRIX=R should not be used with option SPECIAL. MATRIX has no relevance to the Covariance step results for a BAYES method.
PRINT=[E][R][S]: Additional outputs will be printed besides the defaults. E: print the eigenvalues of the correlation matrix. R: print the matrix .5*R. S: print the matrix .25*S. PRINT=R (or S) is not needed with MATRIX=R (or S).
COMPRESS: Covariance Step arrays are printed in compressed format, even if their size is such that NONMEM would normally print them in the usual format.
SLOW: Requests a slower method of computation. Required when either a mixture model was used along with CENTERING on the $ESTIMATION record, or NUMERICAL was used on the $ESTIMATION record. If not present, the option will be automatically supplied in these two cases.
NOSLOW: Requests a faster method of computation. This is the default (but see SLOW).
FAST (NM74): This is equivalent to FAST for the $EST record. If $EST FAST is set, then $COV will be set to FAST, unless SLOW or NOSLOW is specified.
TOL=n (NM72): Tolerance. Used only with General Nonlinear (differential equation solver) ADVAN’s. Sets NRD=TOL. By default, the value set on $SUBROUTINES record (or $TOL or TOL subroutine) is used. If TOL is coded on $COVARIANCE, it overides the default. With NONMEM 74, this feature is deprecated. A user-supplied TOL subroutine should test NM_STEP and set NRD accordingly. TOL has no relevance to the Covariance step results for a BAYES method.
ATOL=n (NM72): Absolute tolerance. Used only with ADVAN9, ADVAN13, ADVAN14, ADVAN15, ADVAN16, ADVAN17, ADVAN18, for which TOL is a relative tolerance. Sets ANRD=ATOL. The default is 12 (that is, accuracy is 10**(-12)). Usually the problem runs quickly when using this setting. On occasion, however, you may want to reduce ATOL (usually set it equal to that of TOL), and improve speeds of up to 3 to 4 fold.

By default, the value set on $SUBROUTINES record (or $TOL or TOL subroutine) is used. If ATOL is coded on $ESTIMATION, it overrides the default for that step. If ATOL is coded on $COVARIANCE, it overrides $ESTIMATION and/or the default for that step. With NONMEM 74, this feature is deprecated. A user-supplied TOL subroutine should test NM_STEP and set ANRD accordingly.

SIGL=n SIGLO=n (NM72): These options may be used to specify different values for the Covariance step. The step size for evaluating the R matrix (central difference second derivative) is set to SIGL/4. If only the S matrix is evaluated (central difference first derivative), the step size is set to SIGL/3. SIGLO is the precision to which individual etas are optimized. Classical NONMEM methods in particular often require a different significant digits level of evaluation (usually more stringent) during the Covariance step than during Estimation Step. For example, during the Estimation step, NSIG=2, SIGL=6, TOL=6 may be sufficient, but during the Covariance step, you may need SIGL=12 TOL=12 to avoid positive definiteness issues. By default, values specified on the $ESTIMATION record are used. (See Section 50.15). SIGL and SIGLO have no relevance to the Covariance step results for a BAYES method.
NOFCOV (NM72): No $COV step for any classical estimation steps. This would be useful if you wanted EM estimation analyses performed, and a final FOCE analysis performed, but did not want the program to spend time on standard error assessments for FOCE, which can take a long time relative to the other methods.
PARAFILE=filename: Name of the “parallel file” (the parallelization profile) that controls parallelization (distributed computing). Default file name if not specified: parallel.pnm or parafile name specified on nmfe command. PARAFILE=ON turns on parallelization for this $COVARIANCE record. PARAFILE=OFF turns off parallelization for this $COVARIANCE record.
PARAFPRINT=n (NM74): The print iteration intervals to the parallelization log file can be controlled by this option during parallelization of the $COV step. See also $ESTIMATION record and nmfe7 command. Default is PARAFPRINT=1.
THBND=n (NM74): If THBND=1, any theta boundaries specified in the $THETA record causes NONMEM to impose a non-linear transformation of the theta parameters so that the transformed parameters may vary from -infinity to infinity. It does this with logistic transformations. This is suitable during the estimation step, but may be desirable have this off (THBND=0) for covariance assessment, and assess partial derivatives of the objective function with respect to the thetas themselves, or some linear transformation of these thetas. By default THBND=1, in keeping with the behavior of earlier NONMEM versions, which effectively has THBND=1. Usually boundaries that are fairly wide will not impact how the variance-covariance is assessed, such as when a lower bound of 0 is given, but if you have very narrow boundaries set, then this can impact the assessment of the variance-covariance of the estimates considerably, and you may wish to set THBND=0. If no lower or upper bounds are given to thetas in $THETA record, this option has no impact.
SIRSAMPLE=[numberlist] (NM74): Option SIRSAMPLE requests the Sampling-Importance-Resampling algorithm (SIR) (See Guide Introduction_7, “Importance Sampling of the Variance-Covariance of the Parameter Estimates”). By default SIRSAMPLE=-1, so SIR process does not occur. SIRSAMPLE should be set between 300 and 10000, to indicate the number of random samples to be generated for each of the SIRNITER iterations. This will produce SIRSAMPLE importance samples, each of which will be placed in the raw output file. As of nm75, SIRSAMPLE may contain a list of integers, one for each of the SRNITER iterations (use double quotes around the list): SIRSAMPLE="1000,200,500". If there are fewer than SIRNITER values, the last value in the list will be used as the SIRSAMPLE value for the remaining iterations. Utility programs table_quant (frequency and quantile sorting) and table_resample (resampling) may be used to analyze $COV Sampling-Importance-Resampling data.
SIRNITER=n (NM74): The number of times SIR sampling should occur. Default is 1.
SIRCENTER=n (NM74): Where the sampling (proposal) density is to be centered. On the first iteration, the mean of the sampling density is at the estimate. On subsequent iterations, the mean of the sampling density is at the estimate (SIRCENTER=0) or at the mean of the (transformed) samples of the previous iteration (SIRSAMPLE=1). Default is 0.
SIR_CAPCORR=x (NM75): Limit the correlation of omegas and sigmas generated form the proposal density to have |correlation| of SIR_CAPCORR or less. This is similar to PSN’s cap_correlation option.
SIRMINWT=x (NM75): 8.1 SIRMAXWT=x (NM75)

Limit the weight range that a sample may relative to the proposal density, to avoid extreme values. Default values are SIRMINWT=0.001, SIRMAXWT=1000.0.

SIRSEED=n (NM75): Starting seed for SIR analysis (default=11456).
SIRCLOCKSEED=[0|1] (NM75): If SIRCLOCKSEED=1 (default is 0), actual starting seed will be 10000*(seconds after midnight)+SEED. This allows a control stream to produce different stochastic results for automated replications, without the need to modify the seed value in the control stream file in each replication.
IACCEPT=x (NM74): The acceptance ratio acts similarly to importance sampling in EM analysis. Default is 1.
IACCEPTL=x (NM74): IACCEPTL=0 (NM74) Default is 1. The IACCEPTL option performs the same as listed for IACCEPTL in “Monte Carlo Importance Sampling EM”. Default is 0.
SIRDF=n (NM74): The proposal density is to be a t distribution with n degrees of freedom. Default is 0, a normal density.
RANMETHOD=[n|S|m|P] (NM74): See the corresponding option of the $ESTIMATION record for importance sampling in EM analysis.
SIRPRINT=n (NM74): Set the console print iterations interval. This does not impact the iterations listed in the raw output file. Default SIRPRINT=0.
FILE=filename (NM74): By default, the raw output file is whatever was listed in the $EST step, or root.ext, where root is the root name of the control stream file. You can re-direct SIR sample listings to an alternative file with this option.
FORMAT=s (NM75): By default, the format for the raw output file and all additional output files is whatever FORMAT was specified for the $EST step. You can change its format with the FORMAT option. s defines the delimiter [,|s(pace)|t(ab)] followed by a Fortran format specification. The default is s1PE12.5. For more details, see the format help item: (See Section 50.54). See INTRODUCTION TO NONMEM 7, FORMAT=s1PE11.4
SIRTHBND=n (NM74): As with the deterministic covariance assessment step, by default the transformed parameters are sampled, so that no sample is below the $THETA lower bound specification, and no higher than the $THETA upper bound specification. To allow a boundariless search in the original theta domain, set SIRTHBND=1. You should also set THBND=1, so that the deterministc covariance matrix used as the proposal density is also not hindered or contorted by the boundaries. Default is the value of THBND, which in turn is 0 by default.
SIRPARAFILE=filename: Name of the “parallel file” (the parallelization profile) that controls parallelization during SIR sampling (distributed computing). Default file name if not specified: parallel.pnm or parafile name specified on nmfe command. SIRPARAFILE=ON turns on parallelization for this $COVARIANCE record during SIR sampling. SIRPARAFILE=OFF turns off parallelization for this $COVARIANCE record during SIR sampling.
SIRPARAFPRINT=n (NM74): The print iteration intervals to the parallelization log file can be controlled by this option during parallelization of the SIR sampling portion of the $COV step. See also $ESTIMATION record and nmfe7 command. Default is SIRPARAFPRINT=1.
PRECOND=n (NM74): Options PRECOND through PRETYPE affect the preconditioning of the R Matrix. (See Guide Introduction_7, “Preconditioning the R Matrix to Improve Precision and Success Rate of $COV Step”). By default, PRECOND (Preconditioning cycles) is 0, and no preconditioning of the R matrix is performed. When PRECOND=n, then up to n preconditioning cycles are performed. This is used in combination with the PFCOND setting.
PRECONDS=TOS (NM74): By default, if preconditioning is performed, it is done on Thetas (T), Omegas (O), and Sigmas (S). Specify PRECONDS (Preconditioning types) =T to do only thetas, PRECONDS=TO to do only thetas and omegas, etc.
PFCON=n (NM74): PFCOND means ‘forced’ precondition cycles. Preconditioning occurs exactly PFCOND times, without testing if the R matrix is positive definite or not on each preconditioning cycle. On the remaining PRECOND-PFCOND cycles, the R matrix is tested for positive definiteness, and upon success, will terminate the preconditioning cycles. Default is PFCOND=0.
PRETYPE=n (NM74): By default PRETYPE (preconditioning type) =0 and the R matrix corrector is V*square_root(eigenvalue). If you set PRETYPE=1, then the corrector is V*square_root(eigenvalue)*Vtranspose. If you set PRETYPE=2, then the corrector is the correlation version of PRETYPE=1.
FPOSDEF=n (NM74): By default FPOSDEF (forced positive definite) =0. If FPOSDEF=1, then if the R matrix is not positive definite, it will be forced positive definite. If PRECOND>0, this will occur after the PRECONDth try.
CHOLROFF=n (NM74): If CHOLROFF is set to 1, then one part of the R matrix evaluation (before inversion) will be evaluated in the manner of earlier versions of NONMEM. This is strictly for comparison with earlier versions for diagnostic purposes. If CHOLROFF=0, then a part of the R matrix evaluation will undergo cholesky decomposition, and if not positive definite, only then will it undergo evaluation according to earlier versions of NONMEM. If CHOLROFF=2, then if cholesky decomposition fails, it will be slightly adjusted to be positive definite. The CHOLROFF=0 is the safest option, in that the Cholesky decomposition (if positive definite) provides more precision in evaluating the R matrix. The CHOLROFF=2 setting is useful if you wish to increase the rate of success in obtaining an R matrix (followed by its inverse) that could be suitable for SIR sampling. If you use CHOLROFF=2, then positive definiteness has been corrected before the inverse occurs, so POSDEF will have no additional effect. If you use POSDEF, then CHOLROFF should be 0 or 1. Default is 0.
KNUTHSUMOFF=n (NM74): In NONMEM 7.4, the Knuth summing method is used to allow the most accurate summation of individual objective function values, even with large variations in values of the individual objective function. To turn this off, and allow a standard summation (not recommended except for comparison purposes from earlier versions), set KNUTHSUMOFF=1. If KNUTHSUMOFF was set in the $EST step, but not in the $COV step, the KNUTHSUMOFF value of the last $EST record will be used. Default is 0.
POSDEF=n (NM75): If POSDEF=1, then if the R matrix is not positive definite, it will be forced positive definite, by method of shifting the eigenvalues by an amount slightly greater than the most negative eigenvalue. If POSDEF=2, then R matrix is made positive definite by making the negative valued eigenvalues approximately 1/100 of the least positive eigenvalue. If POSDEF=3, then R matrix is made positive definite by using the absolute values of the eigenvalues. POSDEF is 0 (no correction) by default for classical covariance step, and 3 for EM methods. The preconditioning method is a more sophisticated, but time-consuming method of making the R matrix positive definite (See PRECOND). Default is 0.
CONDITIONAL: The Covariance Step is implemented, but only when the Estimation Step terminates successfully (in this run or in a run continued via $MSFI). This is the default.
UNCONDITIONAL: The Covariance Step is implemented regardless of how the Estimation Step terminates (in this run or in a run continued via $MSFI).
RESUME (NM73): If MSFO=msfile was specified in the Estimation Step for the FO/FOCE/Laplace method and analysis was interrupted during the Covariance Step, then the Covariance Step may be resumed where it was interrupted in a subsequent problem. Use the $MSFI record to specify the MSFO file of the interrupted analysis, and the RESUME option of the $COV record:

$MSFI = msfile
...

$COV RESUME

OMITTED: The Covariance Step is not implemented.

EXAMPLE:

$COV UNCONDITIONAL TOL = 10 SIGL = 10 SIGLO = 11

REFERENCES: Guide IV, section III.B.15; Guide V, section 9.4.2, 10.6

9 `$DATA`

MEANING: Describes the NM-TRAN data set

CONTEXT: NM-TRAN Control Record

USAGE:

$DATA [filename| *] [(format)] [IGNORE = c1] [NULL = c2]
[IGNORE = (list)...|ACCEPT = (list)...]
[PRED_IGNORE_DATA]
[NOWIDE|WIDE] [CHECKOUT]
[RECORDS = n1|RECORDS = label]
[LRECL = n2] [NOREWIND|REWIND]
[NOOPEN] [LAST20 = n3] [TRANSLATE = (list)]
[BLANKOK]
[MISDAT = r ...]
[FDATACSV...]
[REPL = n...]

SAMPLE:

$DATA DATAFILE

DISCUSSION:

This record specifies the data set to be used. It is required with the first problem specification. It must precede any other NM-TRAN control record that refers to specific data item types. May also be coded $INFILE.

Optional with the second or subsequent problem specifications. If omitted, NONMEM re-uses the data set from the previous problem (which will include any modifications made via transgeneration, e.g., via use of NONMEM’s PASS, or via simulation).

OPTIONS:

filename: Name of the file containing the data set. Must be the first option. If it contains commas, semicolons, or parentheses, then it must be surrounded by single quotes ' or double quotes ". Filename may also contain equal signs if it is enclosed in quotes. If the file is opened by NM-TRAN, filename may contain embedded spaces if it is enclosed in quotes, and may contain at most 80 characters. If the file is opened by NONMEM, the filename may not contain embedded spaces, and may contain at most 71 characters. If filename is the same as any option of the $DATA record, it must be enclosed in quotes.

* may be coded in a problem subsequent to the first. This has the same effect as omitting the $DATA record (NONMEM is told to re-use the previous data set), but allows the CHECKOUT option to be included. With *, no other option may be included.

(format): FORTRAN format specification to be used to read the data. Format codes F, E, and X may be used, but not I. When a format is provided, the label DROP cannot be used on the $INPUT record and options WIDE and NULL may not be coded. If omitted, NM-TRAN will generate a suitable FORMAT specification.
RECORDS=n1: The number of records to be read from the NM-TRAN data set. Comment records are not counted. If NM-TRAN does not drop any records from its data set, then n1 is also the number of records written to the NONMEM data set. If NM-TRAN drops records, then the total number of records written to the NONMEM data set is n1 minus the number of dropped records. With NONMEM 7.5, records may also be dropped using the PRED_IGNORE_DATA block of abbreviated code.

If omitted, the records written to the NONMEM data set are all the records in the NM-TRAN data set up to the end-of-file (or up to a NONMEM FINISH record) minus the number of comment and dropped records. May also be coded NRECORDS, RECS, or NRECS.

If the option is coded as RECORDS=label, where label is a data item label, NM-TRAN understands the data records for the problem to start with the first data record of the NM-TRAN data set, and to include subsequent contiguous data records having the same value of the data item as the first record.

In particular, the ID label may be used (or alternatively, the option may be coded RECORDS=IR, RECORDS=INDREC, or RECORDS=INDIVIDUALRECORD). If a label other than ID is used, the $INPUT record must precede the $DATA record.

LRECL=n2: The number of characters in a logical record. Needed for certain operating systems (e.g., IBM/CMS).
IGNORE=c1: Specifies that any data record having the character c1 in column 1 should be ignored. Also permitted: IGNORE='c' or IGNORE="c", where c may be any character except space. IGNORE=# is the default.

IGNORE=@ signifies that any data record having an alphabetic character or @ as its first non-blank character should be ignored. This permits a table file having header lines to be used as an NM-TRAN data set.

IGNORE=(list): “List” is a list of one or more data item labels, with logical operators and values, of the form “label=value”, “label.EQ.value”, “label.NE.value”, “label.GT.value”, “label.GE.value”, “label.LT.value”, and “label.LE.value”. Fortran 90 logical operators such as ==, /=, <, <=, >, >= may also be used. With NONMEM 7.3, “label.NEN.value” and “label.EQN.value” are permitted. If the logical operator is omitted, the default is “=”. Up to 100 different conditions altogether can be specified.

E.g. IGNORE=(GEN.EQ.1,AGE.GT.60). Records having GEN equal to 1 or AGE greater than 60 are dropped.

ACCEPT=(list): The ACCEPT list option is identical to the IGNORE list option, except that it specifies conditions for acceptance of records. An ACCEPT list cannot be used together with an IGNORE list.

E.g. ACCEPT=(GEN.EQ.1,AGE.GT.60). Records having GEN equal to 1 or AGE greater than 60 are accepted. All others are dropped.

PRED_IGNORE_DATA (NM75): Informs NONMEM that a PRED_IGNORE_DATA pass through the data set is required. If the abbreviated code uses variables PRED_IGNORE_DATA or PRED_IGNORE_DATA_TEST, this option is supplied.
NULL=c2: Specifies that null data items in the NM-TRAN data set are to be replaced in the NONMEM data set by the character c2. E.g., NULL=0 or NULL=.. If this option is omitted, NM-TRAN replaces each null with a space.
NOWIDE: Requests that NM-TRAN attempt to limit FDATA to 80-character records. This is the default.
WIDE: Requests that FDATA contain single-line records, and that at least one space separate columns.
NOREWIND|REWIND: With the first problem specification in a control stream, the file is positioned at its initial point so that the first NM-TRAN data set in the file is used. REWIND: Reposition the file at its intial point so that the first NM-TRAN data set in the file is re-used. NOREWIND: Leave the file at its current position so that the next NM-TRAN data set in the file is used. This is the default.
CHECKOUT: Requests that NONMEM implement the data checkout mode. May also be coded CHECKDATA. With NONMEM 7.5, an additional file, FDATA.csv is produced.
NOOPEN: NM-TRAN will not open the named data file. With NOOPEN, a format specification is required.
LAST20=n3: Override the LAST20 constant in resource/TRGLOBAL.f90 (default: 50). One or two digit years > LAST20 are assumed to be in the 1900’s, one or two digit years <= LAST20 are assumed to be in the 2000’s. LAST20=-1 can be used when two digit years span the year 2051.
TRANSLATE=(list): “list” describes modifications to be made to the contents of the data file. It may contain one of: TIME/F, TIME/F/D and/or one of II/F, II/F/D.

F (“factor”) may be an integer or a real value. The number of digits may be specified explicitly by D (“digits”). The maximum value of D is 12.

BLANKOK: Specifies that blank lines are permitted in the NM-TRAN data set. BLANKOK must be coded in full.
MISDAT=r (NM74): A numerical value indicating a missing data value in the data set, which is displayed on $TABLE table outputs, but is safely interpreted as 0 by other steps of NONMEM. May be used up to 20 times.
REPL=n (NM75): When the REPL=n option of $DATA is coded, the NONMEM data set is considered to be a template data set. NONMEM itself replicates the template data set n times at the start of the problem. The REPL option and REPL_ data item are meant to be used with $SIMULATION or $DESIGN.
NOFDATACSV (NM760): The creation of FDATA.csv can be prevented by adding the option NOFDATACSV on the $DATA record.

NOTE: The character “:” in TIME or II data items requests day-time translation of TIME or II values. These values must have the form hh:mm. With NONMEM 7.3, values may also have the form hh:mm:ss.

REFERENCES: Guide IV, section III.B.5; Guide V, section 6.4; Guide Introduction_7

10 `$DEFAULT`

MEANING: Specifies certain defaults for NONMEM

CONTEXT: NM-TRAN Control Record

USAGE:

$DEFAULT [NOSUB = [-1|0|1]]

SAMPLE:

$DEFAULT NOSUB = 1

DISCUSSION:

$DEFAULT is optional. If present, it must appear following $PROB.

Specifies certain defaults for NONMEM. If more than one $DEFAULT record is present in a given problem, the one used by NONMEM is the last one in the problem.

OPTIONS:

NOSUB=[-1|0|1]: With NOSUB=0, label substitution will be performed for all tasks in the problem. This is the default. (See Section 50.1). With NOSUB=1, label substitution will not be performed. With NOSUB=-1, revert to NONMEM default.

If the NOSUB option is also specified on a task specification record ($TABLE, $SCATTER), then this value of NOSUB applies only for the current task.

May also be coded $DEFAULTS.

REFERENCES: Guide Introduction_7

11 `$DES`

MEANING: Marks the beginning of abbreviated code for the DES routine

CONTEXT: NM-TRAN Control Record

USAGE:

$DES
abbreviated code

SAMPLE:

Suppose differential equations were used for ADVAN2, rather than the analytic solution. The $DES block would be as follows:

$DES
DADT(1) = -P(3) * A(1)
DADT(2) = P(3) * A(1) - P(1) * A(2)

DISCUSSION:

The $DES record is used to compute differential equations. It is used with PREDPP’s general non-linear models (ADVAN6, ADVAN8, ADVAN9, ADVAN13, ADVAN14, ADVAN15, ADVAN16, ADVAN17, ADVAN18).

Left-hand quantities in assignment statements: DADT(1), DADT(2), … (Required. Derivative of each compartment amount with respect to time.)

Right-hand quantities: A(1), A(2), … (compartment amounts); P(1), P(2), … (basic PK parameters); T (time); THETA(n); data item labels.

Fortran functions that are continuous, such as SIN and COS, may be used. The INT, MOD, and ABS functions should not be used in the $DES block. Instead, use model event times MTIME in the $PK block.

DOSTIM: DOSTIM is the time of a lagged dose or additional dose to which the system is being advanced. Abbreviated code in $DES may test DOSTIM.
DOSREC: DOSREC is the dose record corresponding to the dose entering at DOSTIM.
ISFINL: During simulation or a copying pass, ISFINL=1 at a final call to DES at that time. Otherwise, ISFINL=0.

Forbidden Variable Names: IR DA DP E(n) ETA(n) EPS(n) ERR(n)

PSEUDO ASSIGNMENT STATEMENTS: COMRES=-1

RECORD ORDER: Follows $SUBROUTINES $INPUT $MODEL $PK

REFERENCES: Guide IV, section V.C.7; Guide VI, section VI.C

12 `$DESIGN` (NM75)

MEANING: Instructions for Clinical Trial Design Evaluation and Optimization

CONTEXT: NM-TRAN Control Record

DISCUSSION:

The optimal design process can help you in designing or evaluating a clinical trial. It may be desired to evaluate specified time points, or find the optimal time points, dose levels, and number of time points appropriate for a particular sub-design, etc. The design algorithms have been modeled after POPED by Hooker et al., and PFIM by Mentre et al. (See references [22-27]) in Introduction to NONMEM 7.

USAGE:

$DESIGN Record Options
[APPROX = [FO|FOI|FOCE|LAPLACE|LAPLACEI]]
[OFVTYPE = [0|1|2|3|4|5|6|7|8]]
[OFVDIMSCALED = [0|1]]
[GROUPSIZE = n]
[FIMTYPE = [0|1|2|3]]
[FIMDIAG = [0|1|2|3]]
[VARCROSS = [0|1]]
[EOPTD = 1]
[SEED = n]
[CLOCKSEED = [0|1]]
[MODE = [0|1|2|3]]
[DATASIM = [0|1]]

Additional Control Options for $DESIGN
[SIGL = n] [SIGLO = n]
[ABORT|NOABORT|NOHABORT]
[MAXEVALS = n]
[PRINT = n]
[NUMERICAL|NONUMERICAL]
[LIKELIHOOD|-2LOGLIKELIHOOD|-2LL]
[SLOW|NOSLOW|FAST]
[POSTHOC|NOPOSTHOC]
[NOPRIOR = [0|1]]
[FILE = filename]
[FORMAT|DELIM = s3]
[FNLETA = n]

Options for Setting up Types of Optimal Design
[NELDER] [FEDOROV] [RS] [STGR]
[DISCRETE] [DISCRETE_RS] [DISCRETE_SG]
[DESEL = label] [DESELSTRAT = label]
[DESELMIN = label] [DESELMAX = label]
[NMIN = label] [NMAX = label]
[STRAT = label] [STRATF = label]

SAMPLE:

$DESIGN APPROX = FOCEI MODE = 1 NELDER FIMDIAG = 0
DATASIM = 1 GROUPSIZE = 32 OFVTYPE = 0

will produce the most empirical, clinical trial simulation (CTS) style covariances, complete with simulated etas and eps, and standard FIM is assessed. If FIMDIAG>0, then a y-expectation covariance will be evaluated, but mode will be evaluated with the simulated data.

DISCUSSION:

The record name can be shortened to $DESI. Another name for the record is $OPTDESIGN, which can be shortened to $OPT.

The options are described in the following sections:

$DESIGN Record Options
Additional Control Options for $DESIGN
Options for Setting up Types of Optimal Design

OPTIONS:

APPROX=FO (default): The nlme approximation method is specified here. First order (no interaction) is the default. Other options are: FOI (first order interaction with interaction), FOCE (first order conditional estimation), FOCEI (first order conditional estimation with interaction), LAPLACE (Laplace conditional estimation), LAPLACEI (Laplace conditional estimation with interaction).
OFVTYPE=1 (default): The objective function types are comparable to those of PopED:

0,1,3,4,5: design type: d-optimality, -log(det(FIM))
2: design type: a-optimality, -1/tr(1/FIM)
6: design type: ds-optimality, -log(det(FIM))+log(det(FIMunintersting))
7: design type: r-optimality (relative standard error), -1/tr(sqrt(1/FIM)/Paramer))
8: optimal design type: Individual Bayesian FIM, -log(det(Bayes FIM))
9: Same as option 2, and using the UNINT filter.
10: Same as option 7, and using the UNINT filter.

OFVDIMSCALED=0 (default) (nm760)

If OFVDIMSCALED=1, then the objective function is scaled to be per parameter, the dimension of the FIM.

GROUPSIZE=1 (default)

The GROUPSIZE is comparable to that of POPED, in which the FIM is multiplied by this number to provide the subject number size of the dataset template.

FIMTYPE or FIMDIAG=0

0 (default): Full information matrix. Uses finite difference assessment for Theta, Omega, and Sigma variances and covariances.

1 Create a block diagonal information matrix of the estimates
2 Create a block information matrix
3 Create a full information matrix

VARCROSS=0 (default): Standard NONMEM residual variance modeling.
VARCROSS=1: Residual Standard Deviation Modeling. VARCROSS=1 means to treat the residual variance model in the manner of PFIM 4.0. FIMTYPE=1 VARCROSS=1 is equivalent to fim.calc.type=4 in POPED, and diagonal option in PFIM.
EOPTD=1: For each iteration, this creates a random sample of thetas, omegas, or sigmas, using the prior information. $PRIOR NWPRI prior information is required, and PLEV=0.999 must be specified. Best used with STGR.
SEED=223345: Set the starting seed for any random samples to be created, whether for EOPTD=1, or for FOCE type FIM in creating random etas.
CLOCKSEED=0 (default): As of nm75, the actual starting seed will be 10000*(seconds after midnight)+SEED if CLOCKSEED=1.
MODE=0 (default), 1, 2, or 3: Used for specifying data and prediction value type when specifying APPROX=FOCEI. MODE=0 means FOCEI with data at F(ETAsim), and predicted function evalauted at f(ETAsim). MODE=1 means FOCEI with data at F(ETAsim), and predicted function evaluated at the mode, f(ETAhat). MODE=2 means linearized FOCEI, with data at F(ETAsim)-G*ETAsim, and predicted function at F(ETAsim).
DATASIM=0 (default): Normally, y-expectation evaluation of the FIM is performed. To actually simulate data, set DATASIM=1.

The following options may be set within the $DESIGN record, and they operate exactly as their equivalents in the $EST record: SIGL, SIGLO, ABORT/NOABORT/NOHABORT, MAXEVAL, PRINT, NUMERICAL/NONUMERICAL, -2LL/LIKELIHOOD/LLIKELIHOOD, SLOW/NOSLOW/FAST, POSTHOC, NOPRIOR, FORMAT, FILE, FNLETA.

NELDER: Use Nelder method to search for optimal continuous parameters.
FEDOROV: Use to find ideal set of discrete time points from a larger set of possible time points.
RS: Random Search method to find optimal continuous parameters.
STGR: Stochastic Gradient method to find optimal continuous parameters.
DISCRETE: Find optimal number of time points for each sub-design (subject template), and use NELDER method to find optimal continuous parameters.
DISCRETE_RS: Find optimal number of time points for each sub-design, and use RS method to find optimal continuous parameters.
DISCRETE_SG: Find optimal number of time points for each sub-design, and use STGR method to find optimal continuous parameters.
DESEL=label: The data item (column) that contains the design element (DESEL) values that are to be modified and optimized.
DESELSTRAT=label: The data item (column) indicating stratification.
DESELMIN=label: The data item (column) containing the minimal value.
DESELMAX=label: The data item (column) containing the maximal value.

All four DESEL items must be specified: DESEL, DESELSTRAT, DESELMIN, DESELMAX.

NMIN=label: The name of the data item (column) containing minimal number of time points to the subject.
NMAX=label: The name of the data item (column) containing maximal number of time points to the subject.
STRAT=label: The data item (column) containing grouping or stratification number pertaining to that subject.
STRATF=label: The data item (column) containing starting fraction representation for the stratification value in column STRAT.

In addition, $DESIGN sets up the covariance step as $COV MATRIX=R UNCONDITIONAL without the user requiring this record entered in the control stream.

RECORD ORDER: Same as $ESTIMATION or $SIMULATION

REFERENCES: Guide Introduction_7

13 `$ERROR`

MEANING: Marks the beginning of abbreviated code for the ERROR routine

CONTEXT: NM-TRAN Control Record

USAGE:

$ERROR
abbreviated code

DISCUSSION:

The $ERROR record is used to model intra-individual error in observed values. It is used with PREDPP. It can also be used to convert predictions from PREDPP, i.e., scaled drug amounts, to other types of predictions (for example, to obtain the prediction of a drug effect as a function of concentration, in a pharmacodynamic study).

ASSIGNMENT AND CONDITIONAL STATEMENTS

Left-hand quantities in assignment statements:

Y (Required. The modeled value for the dependent variable under the statistical model.)
ERROR-defined (i.e., PRED-defined) items.
Left-hand quantities from the $PK block, if they are not random variables and neither $PK nor $ERROR include the COMRES=-1 pseudo-assignment statement.

Right-hand quantities:

F (Required. The value of the scaled drug amount in the observation compartment.)
Data item labels specified on the $INPUT statement.
THETA(n)
ETA(n) (Required if the data are single-subject, and can be coded ERR(n). Optional if the data are population.)
EPS(n) (Required if the data are population, and can be coded ERR(n).)
ERROR-defined items that appeared earlier as left-hand quantities.
Left-hand quantities from the $PK block.

NEWIND: Same as the NEWIND argument passed by NONMEM to PREDPP. NEWIND=0: First record of the data set. THETA value may differ from value at last call with this record. NEWIND=1: First record of the data set, THETA value does not differ from value at last call with this record, and PRED is nonrecursive (See I_REC), or, First record of a subsequent individual record. NEWIND=2: Subsequent data record of an individual record.
NEWL2: NEWL2=1: First record of an L2 record. NEWL2=2: Otherwise.
ICALL: Same as the ICALL argument passed by NONMEM to PREDPP. ICALL=1: Initialization. ICALL=2: Normal call. ICALL=3: Finalization. ICALL=4: Simulation. ICALL=5: Expectation. ICALL=6: Data Average.
A(n): Amount in compartment n. (See State Vector A) Note: If there is no verbatim code and no explicit use of a subscripted variable A in the $ERROR block, then the symbol A can be used as a data item label or as a name of an ERROR-defined item.

Forbidden Variable Names: IDEF IREV EVTREC NVNT INDXS G HH DADT(n) E(n) P(n)

PSEUDO ASSIGNMENT STATEMENTS

COMRES=-1

CALLFL=-1: Call with every event record.
CALLFL=0: Call with every observation record.
CALLFL=1: Call once per individual record.
CALLFL=2: Call once per problem.

Of the last three, CALLFL=-1 is the default, except when the abbreviated code consists of one line specifying a simple additive or proportional error model, and no verbatim code is present.

Pseudo-assignments statements may be enclosed in parentheses. If two of them are present in the same set of parentheses, separate them with a semicolon. A calling protocol phrase may be used within parentheses instead of a pseudo-assignment statement:

$ERROR (ONCE PER IR) ; same as CALLFL = 1
$ERROR (ONLY OBSERVATIONS) ; same as CALLFL = 0
$ERROR (EVERY EVENT) ; same as CALLFL = -1 (default)

RECORD ORDER:

Follows $SUBROUTINES and $INPUT. Follows $MODEL (if a general model such as ADVAN6 is used). Follows $PK (if present).

REFERENCES: Guide IV, section V.C.6; Guide V, section 8; Guide VI, section IV

14 `$ESTIMATION` RECORD OPTIONS

MEANING: Instructions for the NONMEM Estimation Step

CONTEXT: NM-TRAN Control Record

List of $ESTIMATION Record Options and Their Relevance to Various Methods.

Classical methods are the First order method (METHOD=0 or METHOD=FO), the Conditional method (METHOD=1 or METHOD=FOCE) and the Hybrid method (METHOD=HYBRID). All other methods are EM (Expectation-Maximization) / Bayesian methods and are new to NONMEM 7.

The following table lists options and their applicability to estimation methods:

Table 1: Applicability of $ESTIMATION options to estimation methods.

Option	Classical	`ITS`	DIRECT	`IMP`	`IMPMAP`	`SAEM`	`BAYES`
`-2LL`						X	X
`ATOL +`	X	X	X	X	X	X	X
`AUTO`						X	X
`BAYES_PHI_STORE`	X	X	X	X	X		X
`BIONLY`						X	X
`BOOTDATA`		X	X	X	X	X	X
`CALPHA`							X
`CENTERING`	X	X	X	X	X	X	X
`CINTERVAL`						X	X
`CITER/CNSAMP`		X	X	X	X	X	X
`CLOCKSEED`						X	X
`CONDITIONAL`	X					X	X
`CONSTRAIN`						X
`CTYPE`		X	X	X	X	X	X
`DF`		X	X	X	X	X	X
`DFS (CHAIN only)`							X
`EONLY`			X	X	X	X	X
`ETABARCHECK`						X	X
`ETADER`	X	X	X	X	X		`BAYES`
`ETASAMPLES`						X	X
`ETASTYPE`		X	X	X	X	X
`EVALSHRINK`						X	X
`FAST`	(`CTYPE` 4) X	X	X	X	X	X
`FILE`						`SAEM`	X
`FNLETA`			X	X	X	X
`FPARAFILE`				X	X	X
`GRD`			X	X	X	X
`GRID (Stieltjes)`	X
`IACCEPT`	X	X		X	X
`IKAPPA`	X	X	X	X	X
`INTERACTION`	X	X	X	X	X	X	X
`ISAMPEND`			X	X	X	X
`ISAMPLE`				X	X	X	X
`ISAMPLE_M1`						X	X
`ISAMPLE_M1A`						X	X
`ISAMPLE_M1B`						X	X
`ISAMPLE_M2`						X	X
`ISAMPLE_M3`						X	X
`ISCALE_MAX`			X	X	X	X	X
`ISCALE_MIN`			X	X	X	X	X
`KNUTHSUMOFF`	X	X	X	X	X	X	X
`LAPLACE`	X	X	*	*	X	*	*
`LEVCENTER (for $LEVEL)`	X	X	X	X	X	X	X
`LEVOBJTYPE (for $LEVEL)`	X	X	X	X	X	X	X
`LEVWT (for $LEVEL)`	X	X	X	X	X	X	X
`LIKE`	X	X	X	X	X	X	X
`LNTWOPI`	X	X	X	X	X	X	X
`MAPCOV`				X	X
`MAPINTER`				X	X
`MAPITER`				X	X
`MAPITERS`						X	X
`MASSRESET`	***						X
`MAXEVAL`	X
`MCETA`	X	X	X	X	X
`MSFO`	X	X	X	X	X	X	X
`MUM`		X	X	X	X	X	X
`NBURN`						X	X
`NITER/NSAMPLE`		X	X	X	X	X	X
`NOABORT`	X	X	X	X	X	X	X
`NOCOV**`		X	X	X	X	X	X
`NOHABORT`	X	X	X	X	X	X	X
`NOLABEL`	X	X	X	X	X	X	X
`NONINFETA`	X
`NOOMEGABOUNDTEST`	X
`NOPRIOR`	X	X	X	X	X	X	X
`NOSIGMABOUNDTEST`	X
`NOSLOW`	X	X
`NOSUB`	X	X	X	X	X	X	X
`NOTHETABOUNDTEST`	X
`NOTITLE`	X	X	X	X	X	X	X
`NSIG/SIGDIGITS`	X	X
`NUMDER`	X	X	X	X	X	X	X
`NUMERICAL`	X	X	*	*	X	*	*
`NUTS_EPARAM`	***						X
`NUTS_GAMMA`	***						X
`NUTS_INIT`	***						X
`NUTS_MASS`	***						X
`NUTS_MAXDEPTH`	***						X
`NUTS_SPARAM`							X
`OACCEPT`							X
`OLKJDF`							X
`OMEGABOUNDTEST`	X	X	X	X	X	X	X
`OPTMAP`	X	X	X	X	X
`ORDER`	X	X	X	X	X	X	X
`OSAMPLE_M1`							X
`OSAMPLE_M2`							X
`OSAMPLE_M3`							X
`OVARF`							X
`PACCEPT`							X
`PARAFILE`	X	X	X	X	X	X	X
`PARAFPRINT`	X	X	X	X	X	X	X
`POSTHOC`	X	X	X	X	X	X	X
`PREDICTION`	X	X	X	X	X	X	X
`PRINT`	X	X	X	X	X	X	X
`PRIORC`	X	X	X	X	X	X	X
`PSAMPLE_M1`							X
`PSAMPLE_M2`							X
`PSAMPLE_M3`							X
`RANMETHOD=nSmP`	X	X	X	X	X	X	X
`REPEAT`	X
`REPEAT1`	X
`REPEAT2`	X
`SADDLE_HESS`	X
`SADDLE_RESET`	X
`SEED`		X	X	X	X	X	X
`SIGL`	X	X	X	X	X	X	X
`SIGLO`	X	X	X	X	X	X	X
`SIGMABOUNDTEST`	X	X	X	X	X	X	X
`SLKJDF`							X
`SLOW`	X	X
`STDOBJ`	X
`SVARF`				X	X
`THETABOUNDTEST`	X
`TPU`	X
`ZERO`	X					`SAEM`	X

+ — ADVAN9, ADVAN13, ADVAN14, ADVAN15, ADVAN16, ADVAN17, ADVAN18.
* — May be needed to suppress error messages from NMTRAN or NONMEM.
** — When last estimation step.
*** — In prep for NUTS.

(See Section 50.15).

REFERENCES: Guide Introduction_7

15 `$ESTIMATION`, `$ESTM`

MEANING: Instructions for the NONMEM Estimation Step

CONTEXT: NM-TRAN Control Record

USAGE:

$ESTIMATION
[ABORT|NOABORT|NOHABORT]
[ATOL = n]
[AUTO = [0|1|2|3]]
[BAYES_PHI_STORE = [0|1]]
[BIONLY = [0|1]]
[BOOTDATA = [0|1]]
[CALPHA = n]
[CENTERING|NOCENTERING]
[CINTERVAL = n]
[CITER = n | CNSAMP = n]
[CONSTRAIN = n]
[CTYPE = [0|1|2|3|4]]
[DERCONT = [0|1]]
[DF = n] [DFS = n]
[EONLY = [0|1]]
[ETABARCHECK|NOETABARCHECK]
[ETADER = n]
[ETASAMPLES = 0 | ETASAMPLES = 1]
[ETASTYPE = 0 | ETASTYPE = 1]
[EVALSHRINK = n]
[FILE = filename] [FNLETA = n]
[FORMAT|DELIM = s]
[FO|NOFO]
[FPARAFILE = [filename|ON|OFF]
[GRD = s] [GRDQ = s]
[GRID = (nr,ns,r0,r1)]
[IACCEPT = x] [IACCEPTL = x] [IKAPPA = x]
[INTERACTION|NOINTERACTION]
[ISAMPEND = n] [ISAMPLE = n]
[ISAMPLE_M1 = n] [ISAMPLE_M1A = n] [ISAMPLE_M1B = n]
[ISAMPLE_M2 = n] [ISAMPLE_M3 = n]
[ISCALE_MAX = x] [ISCALE_MIN = x]
[KAPPA = x] [KNUTHSUMOFF = n]
[LAPLACIAN|NOLAPLACIAN]
[LEVCENTER = [0|1]] [LEVOBJTYPE = [0|1]] [LEVWT = n]
[LIKELIHOOD|-2LOGLIKELIHOOD]
[LNTWOPI]
[MADAPT = n] [MAPCOV = n] [MAPINTER = n] [MAPITER = n]
[MAPITERS = [0|1]] [MASSRESET = n]
[MAXEVALS = n] [MCETA = n]
[METHOD = kind] [MSFO = filename] [MUM = s]
[NBURN = n] [NITER = n]
[NOCOV = [0|1]] [NOLABEL = [0|1]]
[NONINFETA = [0|1]] [NOPRIOR = [0|1]]
[NOSUB = [0|1]] [NOTITLE = [0|1]]
[NUMDER = [0|1|2|3]] [NUMERICAL|NONUMERICAL]
[NUTS_BASE = x] [NUTS_DELTA = x] [NUTS_EPARAM = n]
[NUTS_GAMMA = x] [NUTS_INIT = x]
[NUTS_MASS = [B|F|D|BD|DB|BBD|BBB]]
[NUTS_MAXDEPTH = n] [NUTS_OPARAM = n]
[NUTS_REG = x] [NUTS_SPARAM = x]
[NUTS_STEPINTER = n] [NUTS_STEPITER = n]
[NUTS_TERM = x] [NUTS_TEST = n] [NUTS_TRANSFORM = n]
[OACCEPT = n] [OLKJDF = n] [OLNTWOPI]
[OMEGABOUNDTEST|NOOMEGABOUNDTEST]
[OMITTED]
[OPTMAP = n] [ORDER = xxxf]
[OSAMPLE_M1 = n] [OSAMPLE_M2 = n]
[OVARF = x] [PACCEPT = n]
[PARAFILE = [filename|ON|OFF]
[PARAFPRINT = n] [PHITYPE = n]
[POSTHOC|NOPOSTHOC] [PREDICTION]
[PRINT = n] [PRIORC]
[PSAMPLE_M1 = n] [PSAMPLE_M2 = n] [PSAMPLE_M3 = n]
[PSCALE_MAX = n] [PSCALE_MIN = n]
[RANMETHOD = [n|S|m|P]]
[REPEAT|NOREPEAT] [REPEAT1|NOREPEAT1] [REPEAT2|NOREPEAT2]
[SADDLE_HESS = n] [SADDLE_RESET = n]
[SEED = n] [CLOCKSEED = [0|1]]
[SELECT = n] [SIGDIGITS|NSIGDIGITS = n]
[SIGL = n] [SIGLO = n]
[SIGMABOUNDTEST|NOSIGMABOUNDTEST]
[SLKJDF = x] [SLOW = 1|SLOW = 2] [SLOW|NOSLOW|FAST]
[SORT|NOSORT] [STDOBJ = x] [STIELTJES] [SVARF = x]
[TBLN = n] [THETABOUNDTEST|NOTHETABOUNDTEST]
[THIN = n] [TPU = n] [TTDF = n]
[ZERO = list]

SAMPLE:

$ESTIMATION MAXEVAL = 450 PRINT = 5

DISCUSSION:

Optional. Requests that the NONMEM Estimation Step be implemented. May also be coded $ESTM or $ESTIMATE. The Estimation Step obtains parameter estimates. With NONMEM 7, multiple Estimation Steps can be implemented in a single problem. A sequence of two or more Estimation Steps will result in the sequential execution of each. Options specified in an $ESTIMATION record will carry over to the next $ESTIMATION record unless a new option is specified. If a particular option is not used by the method then the option will be ignored. The final parameter estimates from an Estimation Step will be passed on as the initial estimates for the next Estimation Step. (See Section 50.14).

See also “Reserved Variables that are of Interest During the Estimation Step”, at the end of this help item.

OPTIONS:

ABORT: During the Estimation Step, NONMEM does not implement theta-recovery when PRED sets the error return code to 1. (The PRED error return code n is set by the statement “EXIT n [k]” in abbreviated code, or by the statement IERPRD=n in user-supplied code, or by PREDPP when it detects errors.) This is the default.
NOABORT: During the Estimation Step, NONMEM implements theta-recovery, i.e., attempt to avoid values of theta which result in PRED error return code 1. In addition, most non-positive Hessian matrices will be forced to be positive definite, allowing the program to continue, and abnormal termination of the estimation step will occur less often.
NOHABORT: Perform positive definite correction at all levels of the estimation. This can hide a serious ill-posed problem, so use with care.
ATOL=n (NM72): Absolute tolerance. Used only with ADVAN9, ADVAN13, ADVAN14, ADVAN15, ADAN16, and ADVAN17, ADVAN18, for which TOL is a relative tolerance. Sets ANRD=ATOL. The default is 12. If ATOL is coded on $ESTIMATION, it overrides the default for that step.
AUTO=0 (NM73): NONMEM does not provide best settings of certain options. This is the default.
AUTO=1 (NM73): Several options will be set by NONMEM that will allow best settings to be determined. The AUTO option is ignored by the FO/FOCE/Laplace methods.
AUTO=2 (NM74): AUTO=2 may be user with NUTS estimation to setup the alternative sampling strategy “Matt trick”.
AUTO=3 (NM74): AUTO=3 may be user with NUTS estimation to setup the alternative sampling strategy of eta sampling.
BAYES_PHI_STORE=[0|1] (NM75): If BAYES_PHI_STORE=1 then phi and eta values from each BAYES iteration will be stored in root.iph.
BIONLY=[0|1] (NM75): BIONLY stands for Bayesian individual parameters only, and when set to 1, will create new samples of individual parameters only, but will keep the population parameters fixed.
BOOTDATA=[0|1] (NM75): By default (BOOTDATA=0), when data are selected based on $SIML BOOSTRAP, the randomly selected subjects are analyzed during the subsequent estimation method. If BOOTDATA=1, then the subjects not selected are analyzed.
CALPHA=n: n is a value between 0.01 and 0.05. Alpha error rate to use for linear regression test to assess statistical significance. Default is 0.05.
CENTERING: Requests that the average conditional estimates of each eta be constrained to be close to 0. May only be used with METHOD=1. Not permitted with INTERACTION.
NOCENTERING: Requests that the average conditional estimates of each eta not be constrained. This is the default.
CINTERVAL=n: Every n iterations is submitted to the convergence test system. If CINTERVAL=0, then a best CINTERVAL will be found, then used.
CITER=n: n is the number of latest PRINT or CINTERVAL iterations on which to perform a linear regression test. Default is 10. May also be coded CNSAMP.
CONSTRAIN=n (NM72): Requests simulated annealing for parameters to slow the rate of reduction of the elements of OMEGA during the burn-in phase of the SAEM method. Values for n are: 0 or 4 No simulated annealing; 1 or 5 Requests simulated annealing for OMEGA; 2 or 6 Requests simulated annealing for SIGMA; 3 or 7 Requests simulated annealing for both OMEGA and SIGMA. Default is 1. When CONSTRAIN>=4, simulated annealing is also performed on diagonal elements of OMEGA that are fixed to 0. Simulated annealing is performed by subroutine CONSTRAINT. The $ANNEAL record facilitates EM search methods. (See Section 50.4).
CTYPE=[0|1|2|3|4]: CTYPE is used to define the termination test to be applied to the burn-in phases for SAEM and BAYES methods and to the estimation phases for the ITS, IMP, and IMPMAP methods. (CTYPE=4 Applies to classical methods FO/FOCE/Laplacean.) CTYPE=0 indicates no termination test, the default. CTYPE=1 indicates test on objective function value, THETA’s and SIGMA’s but not OMEGA’s. CTYPE=2 indicates test on objective function, THETA’s, SIGMA’s and diagonal elements of OMEGA. CTYPE=3 indicates test on objective function, THETA’s, SIGMA’s and all OMEGA elements. CTYPE=4 indicates that NONMEM should test if the objective function has not changed by more then NSIG digits over 10 iterations.
DERCONT=[0|1] (NM73): The derivative continuity test (DERCONT) by default is off (0). When DERCONT=1, the partial derivative of the objective function with respect to thetas will perform an additional test to determine if a backward difference assessment is more accurate than a forward difference assessment. The DERCONT works only for the Monte Carlo EM algorithms such as IMP, DIRECT, IMPMAP, and SAEM.
DF=n: The proposal density is to be a t distribution with n degrees of freedom. Default is 0, a normal density. Used with the IMP and IMPMAP methods.
DFS=n (NM73): Degrees of freedom for the Sigma matrix for simulation purposes by CHAIN.

DFS=-1 (default): The cholesky elements are uniformly varied over the interval (1-accept)initial value and (1+accept)initial value. DFS=n: The SIGMA matrix is randomly created with an inverse Wishart distribution centered about the initial SIGMA values, with degrees of freedom DFS. DFS=0: As above, but the size of the SIGMA matrix is used as degrees of freedom. DFS=>1000000: SIGMA is fixed at its initial value.

EONLY=[0|1]: A value of 1 indicates the IMP objective function should be evaluated by performing only the expectation step without advancing the population parameters. Default is 0.
ETABARCHECK: There is an etabar statistic from a previous problem, and the P-value associated for the etabar statistic with the problem at hand relates to a hypothesis test that the true etabar is the same as that with the previous problem.
NOETABARCHECK: The P-value associated for the etabar statistic relates to a hypothesis test that the true etabar is 0. This is the default.
ETADER=n (NM73): For evaluating individual variances by numerical derivative methods. ETADER=0: Expected value V, using analytical first derivatives. ETADER=1: Expected value V, using forward finite difference numerical first derivatives. ETADER=2: Expected value V, using central finite difference numerical first derivatives. ETADER=3: 2nd derivative method of evaluating V, using numerical second derivatives of -log(L) with respect to etas.
ETASAMPLES=[0|1] (NM74): Used with $EST METHOD=SAEM or $EST METHOD=BAYES. ETASAMPLES=0 is the default. ETASAMPLES=1 causes individual ISAMPLE random eta samples per subject, to be written to root.ets.
ETASTYPE=0 (NM73): Eta shrinkage is averaged for all subjects. This is the default.
ETASTYPE=1: Eta shrinkage is averaged only among subjects that provided a non-zero derivative of their data likelihood with respect to that eta. (See Section 53.38).
EVALSHRINK=0 (NM760): By default, when MAXEVAL=0, and population parameters are not inputted from an MSF file, Etabar and shrinkage information is not calculated and displayed in the NONMEM report file. If you wish to have this information displayed when MAXEVAL=0, then set EVALSHRINK=1 on the $EST record.
FAST (NM74): The FAST option is available for FOCE/ITS methods. The FAST method allows use of analytical theta derivatives to facilitate FOCE analysis. All thetas should be MU-referenced.
FILE=filename: Name for the raw output file. Default: root.ext, where root is the name of the control file. Additional output files have extensions .ext, .phi, .phm, .shk, .shm, .grd, .xml, .cov, .cor, .coi, .cnv, .smt, .rmt, .imp, .npd, .npe, .npi, .fgh, .clt, .vpd, .vpt, .ets, .vpt, .bfm, .iph.
FNLETA=n (NM72): For a thorough discussion, see INTRODUCTION TO NONMEM 7. FNLETA=0 requests that the FNLMOD and FNLETA routines not be called after the Estimation and Covariance steps are completed. Post-hoc etas for METHOD=0 will not be computed. FNLETA=1 is the default. FNLETA=2 Requests that the estimation step not be done. FNLETA=3 (as of nm74) Like FNLETA=1, will call FNLETA, and all table outputs will use EBE’s from the FNLETA step.
FORMAT=s: Format for the raw output file and all additional output files. s defines the delimiter [,|s(pace)|t(ab)] followed by a Fortran format specification. The default is s1PE12.5. May also be coded DELIM.
DELIM=s: Same as FORMAT option.
FO: Requests that the First-Order Model be used with METHOD=1 and CENTERING. Cannot be used with LAPLACIAN.
NOFO: Requests that the First-Order Model not be used with METHOD=1 and CENTERING. This is the default.
FPARAFILE=filename (NM74): Final etas (empirical Bayes estimates; EBE’s) are evaluated after the last Estimation Step (when FNLETA=1). FPARAFILE=filename specifies a different parafile than was used for the Estimation Step. FPARAFILE=ON turns on parallelization. FPARAFILE=OFF turns off parallelization.
GRD=s: s is a string of [G|N|D|S]’s with each symbol representing a THETA or SIGMA parameter in numerical order. G indicates that the THETA should be Gibbs sampled. N indicates the THETA should be sampled using the Metropolis-Hasting algorithm. S indicates that the THETA is being used to model a SIGMA parameter. D (default) indicates the program will decide. Default is DDDD...
GRDQ=0 (NM74): Optional. The gradient quick option, called GRDQ, allows thetas that must be gradient assessed (such as those that are not mu-referenced) and SIGMAS to be more quickly evaluated by not evaluating the gradients for every one of the ISAMPLE random samples.
GRID=(nr,ns,r0,r1): Optional. May be used with STIELTJES. Constraints are nr<=100, ns<=9999, 0<r0<r1<1. The default values are: GRID=(3,1,.6,.9).
IACCEPT=x: Has different meanings, depending on the method. With SAEM and BAYES, the scaling of OMEGA is adjusted so that samples are accepted x fraction of the time. Default is 0.4. With Importance sampling, expand proposal density variance relative to conditional density so that on average conditional density/proposal density=IACCEPT.
IACCEPT=0: For importance sampling only, you may set IACCEPT=0.0, and NONMEM will determine the most appropriate IACCEPT level for each subject.
IACCEPTL=x (NM74): A scale to a second multi-variate normal density, to cover long tails in the posterior density.
IKAPPA=x (NM74): Used in computing weight for individual parameters in ISAMPLE_M1B mode. IKAPPA is 1.
INTERACTION: The dependence on etas of the model for intra-individual random error is preserved in the computation of the objective function. Cannot be used with CENTERING. With NONMEM 7.3, This is the default with EM/Bayes methods. With NONMEM 7.4, INTERACTION is not supplied if LIKELIHOOD is present.
NOINTERACTION: Always set etas to 0 during the computation of the model for intraindividual random error. This is the default with non-EM/Bayes methods.
ISAMPEND=n (NM73): For SAEM, if ISAMPEND is specified as an upper integer value (usually 10), then NONMEM will perform a ISAMPLE preprocess to determine the best ISAMPLE value.
ISAMPLE=n: When used with the IMP or IMPMAP methods n is the number of random samples per subject used for the expectation step. Default is 300. When used with the SAEM or BAYES method n is the number of chains used by the Metropolis-Hastings algorithm for individual parameter estimation. The default is 2 for SAEM and 1 for BAYES.
ISAMPLE_M1=n: n is the number of mode 1 iterations for the Metropolis-Hasting algorithm. Default is 2.
ISAMPLE_M1A=n (NM72): n is the number of mode 1A iterations for the Metropolis-Hasting algorithm. Default is 0.
ISAMPLE_M1B=n (NM74): n is the number of mode 1B iterations. Default is 2.
ISAMPLE_M2=n: n is the number of mode 2 iterations. Default is 2.
ISAMPLE_M3=n: n is the number of mode 3 iterations. Default is 2.
ISCALE_MIN=x ISCALE_MAX=x (NM72): In importance sampling, the scale factor used to vary the size of the variance of the proposal density is by default bounded by ISCALE_MIN of 0.1, and ISCALE_MAX=10.0. Defaults are (1.0E-06, 1.0E+06) for MCMC sampling.
KAPPA=x (NM74): Used with NUTS method. Default is 1.
KNUTHSUMOFF=n (NM74): The Knuth summing method is used to allow the most accurate summation of individual objective function values. To turn this off, set KNUTHSUMOFF=1. Default is 0.
LAPLACIAN: Use the Laplacian method, in which second derivatives with respect to eta are used. Laplacian may not be used with METHOD=0. Cannot be used with $ABBREVIATED DERIV2=NO unless NUMERICAL option is also specified.
NOLAPLACIAN: Do not use the Laplacian method. This is the default.
LEVCENTER=[0|1] (NM75): There is no default. Required with $LEVEL and $ESTIMATION. If LEVCENTER=1, this ensures the etas of super ID random levels sum to 0. If LEVCENTER=0, level etas are not forced to sum to 0.
LEVOBJTYPE=[0|1] (NM751): If LEVOBJTYPE=0, then for IMP/ITS/FOCE/Laplace, the reported ojective function is the average of two cycles of optimization. If LEVOBJTYPE=1, then the OBJ reported is only that of the second optimization cycle.
LEVWT=n (NM74): This option applies when $LEVEL record is present. By default, LEVWT=0. To weight according to number of subjects for that value, set LEVWT=1.
LIKELIHOOD: This is designed mainly for use with noncontinuous observed responses (“odd-type data”). Indicates that Y will be set to a (conditional) likelihood. Epsilon variables and the $SIGMA record may not be used.
-2LOGLIKELIHOOD: Indicates that Y is a -2 log (conditional) likelihood. May also be coded -2LLIKELIHOOD.
MADAPT=n (NM74): Used with NUTS method. Default is -1.
MAPCOV=1 (NM74): Unused. The default is 1.
MAPINTER=n (NM72): Every nth iteration, the MAP estimation should be used to provide parameters to the sampling density. If MAPINTER=-1, then mapinter will be turned on only if the objective function increases consistently over several iterations.
MAPITER=n (NM72): The first n iterations are to use MAP estimation to assess parameters for the sampling density. If MAPITER=0, then the first iteration will rely on conditional means and variances that are in memory.
MAPITERS=[0|1] (NM75): By default, no MAP estimation is performed with SAEM or BAYES. To get good individual parameter values near the mode of the posterior density for the first iteration of SAEM, you can set MAPITERS=1.
MASSRESET=n (NM74): Mass matrix information accumulation for NUTS method. Default is -1.
MAXEVALS=n: Maximum allowable number of evaluations of the objective function during the Estimation Step. MAXEVALS=-1 may be specified when a $MSFI record is present. MAXEVALS=0 requests that the Estimation Step be omitted. This is useful, for example, with POSTHOC.
MCETA=n (NM73): MCETA=0: Eta=0 is initial setting for MAP estimation. This is the default. MCETA=1: ETA=values of previous iteration is initial setting, or ETA=0, whichever gives lower objective function. MCETA>1: MCETA-1 Random samples of ETA are tested.
METHOD=kind: Values for kind are:

0 or ZERO: Always set etas to 0 during the computation of the objective function. Also called the “first order (FO) method.” This is the default.

1 or CONDITIONAL: Use conditional estimates for the etas during the computation of the objective function. METHOD=1 (without the LAPLACIAN option) is also called the “first order conditional estimation (FOCE) method.”

HYBRID: Use conditional estimates for the etas during the computation of the objective function, with the exception of those etas listed in the ZERO option.

The following methods are new to NONMEM 7:

ITS: Use the iterative two-stage method.

IMP: Use the Monte-Carlo Importance Sampling Expectation Maximization method.

IMPMAP: Use the Importance Sampling method assisted by Mode a Posteriori (MAP) estimation.

SAEM: Use the Stochastic Approximation Expectation Maximization method.

BAYES: Use the Markov Chain Monte Carlo (MCMC) Bayesian Analysis method.

DIRECT: Requests Monte Carlo Direct Sampling.

NUTS (NM74): Requests No U-Turn Sampling (NUTS) Markov Chain Monte Carlo (MCMC) Bayesian Analysis Method.

CHAIN: Allows the user to create a series of random initial values of THETAs and OMEGA’s.

LNTWOPI (NM74): The objective function is reported including the N*LOG(2pi) constant term.
MSFO=filename: A Model Specification File is output to a file with the given filename. Filename may contain at most 71 characters.
MUM=s: s is a string of [M|N|D|X]’s with each letter representing a THETA parameter in numerical order. M indicates that the THETA should be Mu modeled. N indicates not Mu modeled. D indicates the program will decide. X indicates that THETA is involved in a covariate-dependent mixture model. Default is DDDD...
NBURN=n: When used with the SAEM method n is the maximum number of iterations used to perform the stochastic phase. Default is 2000. When used with the BAYES method n is the maximum number of iterations used to perform the burn-in phase. Default is 4000.
NITER=n: When used with the ITS, IMP, and IMPMAP methods n is the maximum number of iterations. Default is 50. When used with the SAEM method n is the number of iterations for the non-stochastic accumulation phase. Default is 1000. When used with the BAYES method n is the number of iterations used to obtain the stationary distribution. Default is 10000. NITER may also be coded NSAMPLE.
NOCOV=[0|1] (NM73): If covariance estimation is not desired for a particular estimation step, set NOCOV=1. If NOCOV=1 is set for an FOCE/Laplace/FO step, this is equivalent to $COV NOFCOV setting.
NOLABEL=[0|1]: 1 indicates that the row of item names for FILE will not be written, otherwise 0, the default.
NONINFETA=[0|1] (NM73): Sometimes, gradients are not properly evaluated for classical NONMEM methods, when not all etas are used for all subjects. NONINFETA=0 is the default.
NOPRIOR=[0|1]: If prior information was specified using the $PRIOR statement, then normally the analysis is set up for three stage hierarchical analysis. By default NOPRIOR=0. If NOPRIOR=1, then for the particular estimation, the prior information is not included in the analysis.
NOSUB=[0|1] (NM74): With NOSUB=0, label substitution will be performed for final estimates in the NONMEM report file. This is the default.
NOTITLE=[0|1]: 1 indicates the header for FILE will not be written, otherwise 0, the default.
NUMDER=[0|1|2|3] (NM73): With NUMDER=1, NONMEM computes and displays numerically evaluated derivatives of Y or F with respect to eta and eps (G and H) in root.fgh. With NUMDER=0, file root.fgh is not produced. This is the default. With NUMDER=2, analytical derivatives values are stored in root.agh. With NUMDER=3, both root.agh and root.fgh are produced.
NUMERICAL: Requests that second eta-derivatives for the Laplacian method be obtained numerically.
NONUMERICAL: Requests that second eta-derivatives for the Laplacian method be computed by PRED. Not permitted with the combination LAPLACIAN and INTERACTION. Otherwise, this is the default.
NUTS_BASE (NM74): See Guide INTRODUCTION TO NONMEM 7. Default is 0.025.
NUTS_DELTA (NM74): Default is 0.8.
NUTS_EPARAM (NM74): Default is 0.
NUTS_GAMMA (NM74): Default is 0.05.
NUTS_INIT (NM74): Default is 0.075.
NUTS_MASS (NM74): Default is B.
NUTS_MAXDEPTH (NM74): Default is 10.
NUTS_OPARAM (NM74): Default is 1.
NUTS_REG (NM74): Default is 0.0.
NUTS_SPARAM (NM74): Default is 1.
NUTS_STEPINTER (NM74): Default is 0.
NUTS_STEPITER (NM74): Default is 1.
NUTS_TERM (NM74): Default is 0.05.
NUTS_TEST (NM74): Default is 0.
NUTS_TRANSFORM (NM74): Default is 0.
OACCEPT=n: Used only with the BAYES method. The scaling of degrees of freedom is adjusted so that samples are accepted n fraction of the time. Default is 0.5.
OLKJDF=n (NM74): Used with NUTS method, OLKJDF stands for Omega LKJ density degrees of freedom. When 0, the usual inverse Wishart prior is used for Omegas. When OLKJDF>0, then the LKJ density is used as the prior. Default is 0. See record $OLKJDF (NM75) to specify LKJ correlation degrees of freedom for each omega block.
OLNTWOPI (NM74): The objective function is reported including the NETA*NIND*LOG(2pi) constant term for SAEM and BAYES.
THETABOUNDTEST, OMEGABOUNDTEST, SIGMABOUNDTEST: With NONMEM VI, the estimation step sometimes terminates with the message PARAMETER ESTIMATE IS NEAR ITS DEFAULT BOUNDARY. These options request that the “default boundary test” be performed for THETA, OMEGA, and SIGMA, respectively. THETABOUNDTEST may also be coded TBT or TBOUNDTEST; OMEGABOUNDTEST may also be coded OBT or OBOUNDTEST; SIGMABOUNDTEST may also be coded SBT or SBOUNDTEST. These options are the defaults.
NOTHETABOUNDTEST, NOOMEGABOUNDTEST, NOSIGMABOUNDTEST: Instructs NONMEM to omit the “default boundary test” for this type of variable.
OMITTED: The Estimation Step is not implemented.
OPTMAP=n (NM73): For alternative MAP (eta optimization) methods.

OPTMAP=0: Standard variable metric (BFGS) optimization method. This is the default. OPTMAP=1: Variable metric method using numerical finite difference methods for first derivatives of F with respect to etas. OPTMAP=2: Nelder Mead method.

ORDER=xxxf: The values of x may be T (Theta), S (Sigma), and O (Order). The value of f may be U (Upper) or L (Lower). The default is TSOL: THETA, SIGMA, OMEGA in Lower triangular form.
OSAMPLE_M1=n: Used only with the BAYES method. Default is -1.
OSAMPLE_M2=n: Used only with the BAYES method. Default is -1.
OVARF=x (NM74): Used with NUTS method and OLKJDF option. OVARF is the weight factor to STD prior to the log sqrt OMEGA diagonal elements. Default is 1. See also $OVARF control record.
PACCEPT=n: Used only with the BAYES method. The scaling of variance is adjusted so that samples are accepted n fraction of the time. Default is 0.5.
PARAFILE=filename: Name of the “parallel file” (the parallelization profile) that controls parallelization. Default file name if not specified: parallel.pnm. PARAFILE=ON turns on parallelization. PARAFILE=OFF turns off parallelization.
PARAFPRINT=n (NM74): The print iteration intervals to the parallelization log file can be controlled by this option. Default is PARAFPRINT=1.
PHITYPE=n (NM74): Default is 0. By default, after an estimation is performed, the phi(), conditional means of the individual parameters, and their variances, are reported in the root.phi file. If you wish to have conditional mean etas reported, set PHITYPE=1.
POSTHOC: This option may be used when the FO method is used. After the Estimation Step terminates, the eta values are estimated for each individual.
NOPOSTHOC: Etas are not estimated. This is the default with METHOD=0. May not be used with METHOD=1.
PREDICTION: Indicates that Y will serve as a prediction variable. This is the default. Compare with LIKELIHOOD, -2LOGLIKELIHOOD options.
PRINT=n: Iteration summaries are printed for the 0th, every nth iteration, and last iteration. When n=0, no summaries are printed. Default: 9999.
PRIORC (NM74): The objective function is reported including the prior constant term.
PSAMPLE_M1=n: Used only with the BAYES method. Default is 1.
PSAMPLE_M2=n: Used only with the BAYES method. Default is -1.
PSAMPLE_M3=n: Used only with the BAYES method. Default is 1.
PSCALE_MIN=n, PSCALE_MAX=n (NM74): In MCMC sampling, the scale factor used to vary the size of the variance of the proposal density is by default bounded by PSCALE_MIN of 0.01, and PSCALE_MAX=1000.
RANMETHOD=[n|S|m|P] (NM72): See INTRODUCTION TO NONMEM 7, Reference [5] and [7].

n: the random number generator used for all Monte Carlo EM and Bayesian methods. 0: ran0 of reference [5], minimal standard generator. 1: ran1 of reference [5], Bays and Durham. 2: ran2 of reference [5]. 3: ran3 of reference [5], Knuth. (Default) 4: NONMEM’s traditional random number generator used in $SIMULATION.

S: sobol method without scrambling, used during importance or direct sampling.

m: the type of scrambing desired: 0: no scrambing; 1: Owen type scrambling; 2: Faure-Tezuka type scrambling; 3: Owen plus Faure-Tezuka type scrambling.

P: each subject will receive its own seed path. (NM74)

REPEAT: The search is repeated with the initial estimates being the final estimates from the first search. Cannot be used with STIELTJES.
NOREPEAT: The estimate obtained at the end of the minimization search is taken to be the final parameter estimate. This is the default.
REPEAT1: The search of the first stage of the Stieltjes method is repeated. May only be used with STIELTJES.
NOREPEAT1: The estimate obtained at the end of the search of the first stage is taken to be the final parameter estimate. This is the default.
REPEAT2: The search of the second stage of the Stieltjes method is repeated. May only be used with STIELTJES.
NOREPEAT2: The estimate obtained at the end of the search of the second stage is taken to be the final parameter estimate. This is the default.
SADDLE_HESS=n (NM74): SADDLE_HESS=0 selects the Hessian matrix last generated by the variable metric method. SADDLE_HESS=1 causes the full second derivative information matrix to be evaluated. Default is 0.
SADDLE_RESET=n (NM74): SADDLE_RESET is the number of times that a reset should occur in the course of the search. Normally, should be set to 1. Default is 0.
SEED=n: The initial seed for the random number generator used for the Monte-Carlo methods. Default is 14455.
CLOCKSEED=[0|1] (NM75): If CLOCKSEED=1 (default is 0), actual starting seed will be 10000*(seconds after midnight)+SEED.
SELECT=[0|1|2|3] (NM73): Used with METHOD=CHAIN and $CHAIN to specify how the sample is selected. SELECT=0: Default action; for $EST METHOD=CHAIN is to find the one giving the best OBJ at the initial values. SELECT=1: The sample is selected sequentially from ISAMPLE to ISAMPEND. SELECT=2: Uniform random selection of sample, without replacement. SELECT=3: Uniform random selection of sample, with replacement.
SIGDIGITS=n: Number of significant digits required in the final parameter estimate. Default: 3. May also be coded NSIGDIGITS.
SLKJDF=n (NM74): Used with NUTS method, SLKJDF stands for Sigma LKJ density degrees of freedom. Default is 0. See record $SLKJDF (NM75).
SIGL=n: n is used to calculate the step-size for finite difference derivatives independent of the SIGDIGITS value. SIGL should usually be 2 to 3 times the value of NSIG.
SIGLO=n (NM72): The precision to which the individual etas are optimized. By default, SIGLO is set to the same value as SIGL.
SIGMABOUNDTEST: See OMEGABOUNDTEST.
SLOW: Requests a slower method of computation. Required when either a mixture model is used along with CENTERING, or NUMERICAL is used.
SLOW=1: Same as SLOW.
NOSLOW: Requests a faster method of computation. This is the default.
SLOW=2: This option is permitted with STIELTJES.
SORT: Individual contribution to the objective function value and individual contributions to the gradients are sorted before they are summed.
NOSORT: Individual contributions are summed in the order in which the individual records appear in the NONMEM data set. This is the default.
STDOBJ=x (NM74): For importance sampling and direct sampling only, if ISAMPEND is specified as an upper integer value, and STDOBJ is set to a real value greater than 0, then NONMEM will vary the number of Monte Carlo samples.
STIELTJES: A set of tentative population estimates are first obtained using some 1st- or 2nd-order method. A tentative value for the integral is obtained. Then numerical integration is used to obtain second-stage estimates.
SVARF=x (NM74): Used with NUTS method and SLKJDF option. SVARF is the weight factor to STD prior to the log sqrt SIGMA diagonal elements. Default is 1. See also $SVARF control record.
TBLN=n (NM75): Used with $EST METHOD=CHAIN and $CHAIN records to allow selecting a table within a raw output file.
THETABOUNDTEST: See OMEGABOUNDTEST.
THIN=n (NM74): The Bayesian records retained in the raw output file may be adjusted by every THINth iteration. Default is 1.
TPU=n (NM75): If TPU>0, use THETA_PRIORU routine. Default is 0.
TTDF=n (NM74): TTDF stands for Theta t-density degrees of freedom. Used with NUTS method. Default is 0. See also $TTDF control record (NM75).
ZERO=list: Required with METHOD=HYBRID. A list of indices for etas which are fixed to zero during the Estimation Step.

Reserved Variables that are of Interest During the Estimation Step

MUFIRSTREC (NM74): The MUFIRSTREC option can speed up the NUTS method, and also ordinary BAYES, FAST FOCE, ITS, and the EM methods. Set MUFIRSTREC=1 in $PRED or $PK.
OBJQUICK (NM74): The OBJQUICK option can speed up the NUTS method, and also ordinary BAYES, FAST FOCE, ITS, and the EM methods. OBJQUICK=0: Default. Standard NONMEM processing. OBJQUICK=1: Certain tests and initializations are skipped. OBJQUICK=2: A simplified modeling process occurs, but which cannot be used when $LEVEL or $MIX is used.

REFERENCES: Guide I, section C.3.5.1; Guide II, section E, F; Guide IV, section III.B.14, IV.G; Guide V, section 9.4.1, 13.2; Guide VII, section I, II, III; Guide Introduction_7

16 `$ETAS`, `$PHIS`

MEANING: Specifies Initial Values for Etas or Phis

CONTEXT: NM-TRAN Control Record

USAGE:

$ETAS [[value1 [value2] [value3] ... [valuen]]
[FILE = filename [FORMAT|DELIM = s] [TBLN = n]] [ITERATION = n]]
$PHIS [[value1 [value2] [value3] ... [valuen]]
[FILE = filename [FORMAT|DELIM = s1] [TBLN = n]] [ITERATION = n]]

SAMPLE:

$ETAS 0.4 3.0 3.0 5.0
$PHIS 0.4 3.0 3.0 5.0
$ETAS FILE = myprevious.phi FORMAT = s1pE15.8 TBLN = 3
$PHIS FILE = myprevious.phi FORMAT = s1pE15.8 TBLN = 3
$ETAS FILE = myprevious.iph TBLN = 3 ITERATION = 123

NONMEM describes the use of these records with messages in the report file such as the following:

LOADED 3 PHI/ETA ITEMS FROM CONTROL STREAM

DISCUSSION:

By default, the initial value used for ETA’s in the Estimation Step search is 0. The $ETAS and $PHIS records provide different initial estimates. Optional.

OPTIONS:

There are two forms:

$ETAS value1 [value2] [value3] ...[valuen]: All of the subjects in the data set will be given these initial values of etas. If fewer values are listed than the number of etas in the problem, the value 0 will be used for the remaining etas. Any real value (positive, negative, zero) may be specified. When the record is $PHIS, values are entered as phi values, convenient for EM methods. The eta values will then be evaluated as eta(i) = phi(i) - mu(i) for each eta, where mu(i) = mu_i is evaluated according to their definitions in the $PK section.
FILE=filename FORMAT=s TBLN=n ITERATION=n: Uses initial etas and/or phis for an entire set of subjects from a file .phi, .phm (in the case of mixture problems) of a previous analysis, or .iph file.

With FORMAT, s defines the delimiter [,|s(pace)|t(ab)] followed by a Fortran format specification. The default is s1PE12.5. FORMAT should at least have the delimiter appropriate to read the file. May also be coded DELIM.

TBLN is the table number in the file. If TBLN is not specified, it defaults to 1.

ITERATION is the iteration number in a .iph file (not relevant for .phi or .phm file). As a .iph file has both ETA() and PHI() items, ETA()s will be selected for a $ETAS record, and PHI() will be selected for a $PHIS record. The first ITERATION>0 is selected, unless a particular iteration is specified.

In matching the etas/phis to the data set given in $DATA of the control stream file, the attempt will be to match ID numbers rather than subject numbers. The phc/etc variances will also be brought in.

One purpose to bringing initial eta/phi and etc/phc values is you can readily resume an analysis.

FURTHER DISCUSSION

The etas from $ETAS/$PHIS can be used in several ways.

In METHOD=0 (FO), they are ignored.

In METHOD=1 (FOCE), they are ignored unless MCETA>0. When MCETA>0, then various starting etas are tested, including a set from $ETAS, when available.

In Bayes, SAEM, IMP MAPITER=0 they are used as the starting etas.

In MAP estimation methods, such as METHOD=1, or ITS, or IMP MAPITER>0, or IMPMAP, and if MCETA>0, then these etas are one of the initial eta vector positions tested (during the first iteration), and the one giving the lowest OBJ is then selected.

In cases where FNLETA=2, the estimation step is skipped, and etas inputted from $ETAS are treated as if they were the final result of an estimation.

See INTRODUCTION TO NONMEM 7, $ETAS and $PHIS Record For Inputting Specific Eta or Phi values.

REFERENCES: Guide Introduction_7

17 `$FORMAT`

MEANING: Specifies significant digits for the NONMEM report file

CONTEXT: NM-TRAN Control Record

USAGE:

$FORMAT FMTN = n (NM75)
$FORMAT FMTN = 3 (default) (NM75)

You may now display any significant digits for thetas, omegas, and sigmas results, and variance-covariance of estimates, listed in the NONMEM report file. The FMTN is the number of significant digits (which is by legacy and default 3), between 3 and 23. This also applies to $TABLE outputs to the NONMEM report file. The FORTRAN format will be formed as 1PE{FMTN+6}.{FMTN-1}. For example FMTN=6 will be 1PE12.5. If you wish G field format, set the FMTN to a negative value. For example FMTN=-4 will be 1PG10.3. It is recommended that you place the $FORMAT record immediately after the $PROB record:

$PROB My problem
$FORMAT FMTN = 5

This FMTN precision format will be in effect for outputs of all problems, until another $FORMAT record is given for a new $PROB in the control stream.

REFERENCES: Guide Introduction_7

18 `$INDEX`, `$INDXS`

MEANING: Defines values for the PRED/PREDPP INDXS array

CONTEXT: NM-TRAN Control Record

USAGE:

$INDEX [label1|value1] [label2|value2] [label3|value3] ...

SAMPLE:

$INDEX DOSE 1

DISCUSSION:

Optional. Used only with user-supplied FORTRAN subroutines (ERROR, PK, INFN, PRED) which make explicit use of the INDXS array. May also be coded $INDXS or $INDEXES.

OPTIONS:

The labels are those of data items on the $INPUT record. The values are integers no larger than the number of data items in the NONMEM input data set. Either the index of the data items with labeli or valuei is stored in INDXS(i). (The index of a data item is its position in the NONMEM data record.)

REFERENCES: Guide I, section C.4.1; Guide IV, section III.B.3; Guide VI, section III.C, V.A

19 `$INFN`

MEANING: Marks the beginning of abbreviated code for the INFN routine

CONTEXT: NM-TRAN Control Record

USAGE:

$INFN
abbreviated code

SAMPLE:

$INFN
IF (ICALL == 1) CALL SUPP (1,1)

DISCUSSION:

The $INFN record is used to describe initialization processing for a NONMEM run, or NONMEM problem, or finalization processing for a NONMEM problem. It is used with PREDPP. General rules for abbreviated code are documented elsewhere (See Section 53.1). Specific rules for $INFN blocks are described elsewhere. (See Section 53.46, Finalization example).

RECORD ORDER: Follows $SUBROUTINES.

REFERENCES: None.

20 `$INPUT`

MEANING: Defines the data item types in the data set

CONTEXT: NM-TRAN Control Record

USAGE:

$INPUT item1 item2 item3 . . .

SAMPLE:

$INPUT ID DOSE TIME CP = DV WT

DISCUSSION:

The items define the data item types that appear in the NM-TRAN data records, and define the order of their appearance.

This record is required. It must precede any other NM-TRAN control record that refers to specific data item types.

With NONMEM VI 2.0 and later versions, the length of a single $INPUT record (and all records of the NM-TRAN input file) is at most 160 characters. (Previously, it was 80 characters.) With NONMEM 7.3, the maximum length is given by FSD in resource/SIZES.f90 (FSD=67000 with NONMEM 7.3). 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.

Multiple $INPUT records may be used. Each continues the previous record.

OPTIONS:

Each item has form B or A=B, where A and B are data item labels.

With previous versions of NONMEM labels were restricted to 4 characters in length and could not include the character _. With NONMEM 7 a label consists of 1-24 letters (A-Z), numerals (0-9), and the character _, beginning with a letter. (The length 24 is specified by constant SDF in SIZES) (See Section 50.41).

The labels may be used in subsequent NM-TRAN control records and will be used as labels for data items in NONMEM output.

Certain data item labels are reserved and refer to data items that may be needed by NONMEM or PREDPP, i.e.,

ID L1 L2 DV MDV
RAW_ MRG_ RPT_
TIME DATE DAT1 DAT2 DAT3 DROP SKIP EVID AMT RATE SS II ADDL
CMT PCMT CALL CONT

Certain data item labels are semi-reserved, in that they have reserved meanings if used in $INPUT, but can also be user-defined in abbreviated code, in which case they have no reserved meaning, i.e.,

XVID1 XVID2 XVID3 XVID4 XVID5

(See Section 51.15). REPL_

Others are labels assigned by the user, e.g., to label user (concomitant) data.

Certain labels should not appear in the $INPUT record:

ETA1 ETA2 ETA3 ETA4 ETA5 ETA6 ETA7 ETA8 ETA9
Labels for basic PK parameters (e.g., CL, V, K, KA)
Labels for additional PK parameters (e.g., S1, F0, R1, F1)
Arguments of subroutines internal to NONMEM/PREDPP
Mu variables (e.g., MU_ MU_i )

When the form A=B is used, at least one of the labels A or B must be a reserved label. If A or B is a non-reserved label, it is a synonym for the reserved label. The synonym is used as the label in NONMEM output.

If DROP (or SKIP) is used as a data item label or synonym, the data item type will not appear in the NONMEM data set. DROP (or SKIP) may be used with more than one item.

If the label DATE (or DAT1, DAT2, or DAT3) is used, DATE=DROP causes the data item to not appear in the NONMEM data set. However, NMTRAN will adjust the TIME data item to reflect the date. (See Section 51.10).

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

21 `$LDFOLD`

MEANING: Revert to pre NONMEM 7.5.1 interpretation of loss of degrees of freedom (LDF).

CONTEXT: NM-TRAN Control Record

USAGE:

$LDFOLD (NM751)
$LDFOLD

DISCUSSION:

If there is a reason that you need your problem to handle LDFs in the manner of previous NONMEM versions, insert $LDFOLD after the first $PROBLEM:

$PROB My problem
$LDFOLD

and this will revert to the old default handling of LDFs. Only the new methods (ITS/IMP/SAEM/BAYES) are affected by a change in default behavior regarding LDFs of NONMEM version 7.5.0 to 7.5.1.

REFERENCES: Guide Introduction_7

22 `$LEVEL`

MEANING: Specifies Nested Random Levels Above Subject ID

CONTEXT: NM-TRAN Control Record

USAGE:

$LEVEL item = (n1[m1], n2[m2] ...) ...

SAMPLE:

$LEVEL

DISCUSSION:

Identifies one or more Super ID data items.

item: Item is the name of a data item listed on $INPUT. It defines an additional nested random level, and is referred to as a “super ID” data item. The first super ID item defines an additional random nesting level above that of subject ID. More than one super ID item may be listed on $LEVEL. Each subsequent super ID item defines an additional nesting level above that of the previous nesting level.
nk[mk]: States that ETA(nk) is associated with this super ID item, and ETA(mk) is nested within ETA(nk).

With NONMEM 7.4, a short-hand notation may be used to describe a series of values of nk. A sequence of values for nk can be described as start TO end BY interval. TO is required. The character : may be used instead of TO. BY is optional. Default is 1. The value of BY may be negative. If the second value of BY differs, the same syntax may also be used for mk.

Nesting levels below the subject ID is modelled as with previous versions of NONMEM. (See Interoccasion_variability example).

The order that super ID’s are listed on $LEVEL defines their nesting level. The order that standard and super ID’s are listed on $INPUT is immaterial.

When $LEVEL is used with FOCE ($ESTM METHOD=1), the SLOW option is required, and MATRIX=R is required with $COV.

EXAMPLE:

$INPUT ... ID ... SID ... CID ...
...

$PK
MU_1 = THETA(1)
MU_2 = THETA(2)
CL = DEXP(MU_1 + ETA(1) + ETA(5) + ETA(9))
V1 = DEXP(MU_2 + ETA(2) + ETA(6) + ETA(10))

...
$LEVEL
SID = (5[1],6[2])
CID = (9[5],10[6])

The data item named SID is the site ID. The data item named CID is the country ID. There are several sites belonging to one country, some other sites belonging to another country, etc. For clearance, eta(9) is the country variability that has nested in it the site variability eta(5), which in turn has nested in it the subject variability (the standard ID data) eta(1).

An alternate way of coding the $LEVEL records is:

SID=(5 to 6[1])
CID=(9 to 10[5])

NONMEM performs appropriate summary statistics for eta(5), and makes the appropriate constraints on eta(5), so eta(5) changes by site, that is, by every SID value change, and not by every ID value change.

The above method, using $LEVEL, is a linearized approximation at the super ID level, and takes advantage of a dual OBJ function call.

To perform an exact analysis, separate thetas must be defined for each value pertaining to a super ID data item, so that theta is shared only by the subjects with the particular SID value. $LEVEL is not used. (See superid3_6).

If there are multiple $PROBLEM records, $LEVEL should be restated with each problem for which it is still relevant.

See also LEVWT option of the $ESTIMATION record (NM74). By default, LEVWT=0. If you wish to weight according to number of subjects for that value, set LEVWT=1 on the $EST record.

REFERENCES: Guide Introduction_7

23 `$MIX`

MEANING: Marks the beginning of abbreviated code for the MIX routine

CONTEXT: NM-TRAN Control Record

USAGE:

$MIX
abbreviated code

SAMPLE:

$MIX
NSPOP = 2
P(1) = THETA(5)
P(2) = 1 - THETA(5)

DISCUSSION:

The $MIX record is used to describe the mixture probabilities of a mixture model. It is evaluated with individual records.

ASSIGNMENT AND CONDITIONAL STATEMENTS

Left-hand quantities in assignment statements:

NSPOP: An integer variable. The number of sub-populations. Must be given a value when ICALL=1.
P(i): For each i (i=1, … , NSPOP), P(i) is the modeled fraction of the population in the ith subpopulation. The sum of the P(i) should equal 1. In principle, the P(i) can change from individual to individual. If for a given individual, the second (for example) subpopulation doesn’t apply, then set P(2)=0 for that individual. MIXP may be coded instead of P; they are synonymous in the context of the $MIX block.

Right-hand quantities in assignment statement and in conditions:

THETA(n).
MIX-defined items that appeared earlier as left-hand quantities.

ICALL: ICALL=0: Run initialization. ICALL=1: Problem initialization. ICALL=2: Normal call. ICALL=4: Simulation.

Data items listed in DATA option of $CONTR record. E.g., assume that the following records appear in the control stream prior to the $MIX block:

$INPUT ... STDY ...
$CONTR DATA = (STDY)

Then STDY may be used on the right in $MIX. STDY and STDY(1) both refer to the value of STDY on the first observation record of the individual record. STDY(i) refers to the value of STDY on the i-th observation record. TEMPLT may be used. (See Section 53.48).

Global Variables in Modules. Certain variables in FORTRAN modules can be used. (See Section 53.111)

May not include: EXIT, CALL, DO WHILE / ENDDO statements, COMRES, CALLFL pseudo-variables.

Forbidden Variable Names: NEWIND, ETA(i), EPS(i), ERR(i) COM(i).

Variables defined in $MIX are not listed in module NMPRD4 and may not be displayed in $TABLE and $SCATTER.

RECORD ORDER: Follows $SUBROUTINES.

REFERENCES: Guide IV, section III.B.4, III.B.6; Guide IV, section IV.E.1, 4.E.2; Guide VI, section III.L.2, Figure 6

24 `$MODEL`

MEANING: Specifies the MODEL subroutine of PREDPP

CONTEXT: NM-TRAN Control Record

USAGE:

$MODEL [NCOMPARTMENTS = n1] [NEQUILIBRIUM = n2] [NPARAMETERS = n3]
[COMPARTMENT = ([name] [attribute1] [attribute2] ...)] ...
[LINK compnamea [TO|AND] compnameb BY k [l]] ...
[I_SS = n]

SAMPLE:

$MODEL NPARAMETERS = 3
COMP = (DEPOT DEFDOSE INITIALOFF) COMP = (CENTRAL DEFOBS NOOFF)

DISCUSSION:

Required with a general ADVAN (ADVAN5,6,7,8,9,13,14,15,16,17,18).

OPTIONS:

NCOMPARTMENTS=n1: Total number of compartments other than the output compartment. Default: the number of COMPARTMENT options. May also be coded NCM or NCOMPS.
NEQUILIBRIUM=n2: Number of equilibrium compartments. Default: 0
NPARAMETERS=n3: Number of basic PK parameters. Default: The number of basic PK parameters defined in the $PK abbreviated code. May also be coded NPARAMS. May be 0 with the general non-linear models (ADVAN6, ADVAN8, ADVAN9, ADVAN13, ADVAN14, ADVAN15, ADVAN16, ADVAN17, ADVAN18).
COMPARTMENT=([name] [attribute1] [attribute2] ...): Each COMPARTMENT option defines a single compartment. Compartments are numbered in the order in which they are defined. The name option gives the name for the compartment. The name option may not be one of the compartment attributes below, unless it is enclosed in quotes (' or "). If the name option is not used, then the compartment is named COMPn, where n is the compartment number.

Attributes are chosen from the following list. When an attribute is not chosen, its opposite is the default.

INITIALOFF - Compartment is initially off.
NOOFF - Compartment may not be turned on or off.
NODOSE - Compartment may not receive a dose.
EQUILIBRIUM - Compartment is an equilibrium compartment (ADVAN9, ADVAN15, and ADVAN17 only; implies NODOSE).
EXCLUDE - Compartment amount is excluded from the computation of the amount (Amt) of the output compartment (ADVAN9, ADVAN15, and ADVAN17 only).

The following two attributes have no opposites.

DEFOBSERVATION - Compartment is the default observation compartment.
DEFDOSE - Compartment is the default dose compartment.

If no compartment has the DEFOBSERVATION attribute, the default is the first compartment with the name CENTRAL; otherwise, the first compartment. If no compartment has the DEFDOSE attribute, the default is the first compartment with the name DEPOT which may receive doses; otherwise, the first compartment which may receive doses.

LINK compname [TO|AND] compname BY k [l]: Link clauses are used with ADVAN5 and ADVAN7, but only in the absence of $PK abbreviated code. They are rarely used, and are described in Guide IV.
I_SS= n: I_SS may be used with the general non-linear models (ADVAN6, ADVAN8, ADVAN9, ADVAN13, ADVAN14, ADVAN15) to request the initial state feature of PREDPP. Values of n are:

0 No initial state state (the default)
1 Initial steady state
2 Initial steady state, adds to current compartment amounts.
3 Initial steady state, use current compartment amounts as initial estimates.

The attributes INITIALOFF NODOSE define an output-type compartment. As with the output compartment, it is possible to use a negative value of CMT to obtain an observation and turn off such a compartment with one observation record. Like the output compartment, it is initially off, and it remains off until it is explicitly turned on by an other type event record which has the output compartment’s number in the CMT data item. Unlike the output compartment, a differential equation (DADT) must be supplied for an output-type compartment.

(See advan68, Section 56.12, Section 53.77) (See Initial Steady State: I_SS, Section 53.45).

RECORD ORDER: Follows $SUBROUTINES. Precedes $PK (if present).

SYMBOLIC LABEL SUBSTITUTIONS OF MODEL COMPARTMENTS (NM75)

Compartment names defined in $MODEL are automatically available for substitution in abbreviated code. This is referred to as “implicit” compartment name substitution. It is an alternative to “explicit” compartment name substitution using $ABBR REPLACE records.

For example:

$MODEL
COMP = (GUT,DEFDOS)
COMP = (CENTRAL,DEFOBS)
COMP = (PERI)

allows substitutions to be made for A(GUT), DADT(GUT), A(CENTRAL), DADT(CENTRAL), etc, so you may use these symbols in your abbreviated code, as in the following:

$DES
DADT(GUT) = -KA * A(GUT)
DADT(CENTRAL) = KA * A(GUT) - (KCP + KC0) * A(CENTRAL) + KPC * A(PERI)
DADT(PERI) = KCP * A(CENTRAL) - KPC * A(PERI)

...

$ERROR
IPRED = A(CENTRAL) / S2

In the generated code, compartment names are replaced by the appropriate values 1, 2, etc.

See INTRODUCTION TO NONMEM 7, Symbolic Label Substitutions of Model Compartments.

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

25 `$MSFI`

MEANING: Gives the name of an input Model Specification File

CONTEXT: NM-TRAN Control Record

USAGE:

$MSFI filename [NORESCALE|RESCALE] [NPOPETAS[= n]]
[ONLYREAD] [NOMSFTEST|MSFTEST]
[VERSION = n]
[NEW]

SAMPLE:

$MSFI MSF13

DISCUSSION:

This record gives the name of an input Model Specification File.

OPTIONS:

filename: Name of the Model Specification File. Must be the first option. Filename may not contain embedded spaces. If it contains commas, semicolons, or parentheses, then it must be surrounded by single quotes ' or double quotes ". Filename may also contain equal signs if it is enclosed in quotes. If filename is the same as any option of the $MSFI record, it must be enclosed in quotes. Filename may contain at most 71 characters.
NORESCALE: If a search is continued, it is continued just as it would have been in the previous run. This option has no effect if the Estimation Step is not implemented or if the step is implemented, but using different options on the $ESTIMATION record from those used with the previous run. This is the default option.
RESCALE: The search is to be restarted with initial estimates taken to be the final estimates from the previous run, so that a UCP value of 0.1 now corresponds to a final estimate from the previous run. This option may be used only if the search with the previous run terminated successfully and all the options used on the $ESTIMATION record coincide with those used with the previous run (except the MAXEVAL option).
NPOPETAS[=n]: If the data are to be understood to be population data, the option NPOPETAS may be needed, and then the part “=n”, n>0, may also need to be coded. The integer n should be the number of population eta variables. The part “=n” is required when the $ERROR block describes a model that changes the value of F, and there is no $PK block. It is also required when variables A(n) are used in the $PK abbreviated code. If the data are to be understood to be single-subject data, the option NPOPETAS=0 may be needed. May also be coded POPETAS.
ONLYREAD: This option should be used if and only if the model specification file is being used to convey prior information to a succeeding problem in the control stream (See Section 59.21). No task records may appear in a problem specification containing a $MSFI record with this option.

When the $MSFI record is used in a problem specification, $THETA, $OMEGA and $SIGMA records should not appear in that specification. It is permissible for the data file to differ from the original data file, but usually this is not done.

MSFTEST: Prevents an MSF file from being utilized in a subsequent control stream file or problem if there were errors. This is the default.
NOMSFTEST: Sometimes the MSFI error check is too strict. This occurs particularly when using classical NONMEM methods. To turn of MSFI error checking, use NOMSFTEST.
VERSION[=n]: Read in MSF files from previous versions. With NONMEM 7.6.0, choices are (NONMEM 7.5 and 7.6 use present MSF version):

$MSFI myfile.msf VERSION = 7.4.4
$MSFI myfile.msf VERSION = 7.4.3
$MSFI myfile.msf VERSION = 7.4.2
$MSFI myfile.msf VERSION = 7.4.1
$MSFI myfile.msf VERSION = 7.4.0
$MSFI myfile.msf VERSION = 7.3.0
$MSFI myfile.msf VERSION = 7.2.0
$MSFI myfile.msf VERSION = 7.1.2
$MSFI myfile.msf VERSION = 7.1.0
$MSFI myfile.msf VERSION = 6.2
$MSFI myfile.msf VERSION = 6.1

NEW: When the problem that created the MSF file has successfully completed, calling for a resumed or new estimation is prevented when the method is FO/FOCE/Laplace. To allow analysis to continue, or to allow an analysis on a new data set, resuming from the final parameters of the MSF file, use the option NEW: $MSFI myfilename NEW.

With NONMEM 7.3 and later, when MSF or MSFO option is used to specify an MSFO file in the $EST record e.g., $EST ... MSFO=msfroot.msf, then in addition to the main MSF file msfroot.msf, file msfroot_ETAS.msf containing individual etas will also be produced, and provide additional information when a $MSFI record is used in a subsequent problem or control stream. This is referred to as an “extra” msf file. If the Covariance Step is also implemented, files msfroot_RMAT.msf and msfroot_SMAT.msf containing intermediate information on the R matrix and S matrix will also be produced. These files provide information when a $MSFI record along with a $COV ... RESUME record is used in a subsequent problem or control stream.

The use of an extension, e.g., .msf, is optional. If the _ETA file is not present, NONMEM issues a warning: WARNING: EXTRA MSF FILE COULD NOT BE OPENED: c5msf2x_ETAS. There is no warning if _SMAT and/or _RMAT are not present.

REFERENCES: Guide I, section B.3; Guide II, section E.3; Guide III, section 3.2; Guide IV, section III.B.12; Guide Introduction_7

26 `$NONPARAMETRIC`

MEANING: Instructions for the NONMEM Nonparametric Step

CONTEXT: NM-TRAN Control Record

USAGE:

$NONPARAMETRIC [MARGINALS|ETAS] [MSFO = filename] [RECOMPUTE]
[EXPAND] [NPSUPP = n | NPSUPPE = n]
[BOOTSTRAP [STRAT = label] [STRATF = label]]
[PARAFILE = [filename|ON|OFF]
[NPESTIM = [0|1]] [NPMAXITER = n]
[UNCONDITIONAL|CONDITIONAL] [OMITTED]

SAMPLE:

$NONPARAMETRIC ETAS

DISCUSSION:

Optional. Requests that the NONMEM Nonparametric Step be implemented. When present, the $ESTIMATION record must also be present and must specify METHOD=1 or POSTHOC.

For a given eta, the points of support are the vector of posthoc estimates of that eta for all individuals (i.e., the CPE values for that eta), which is essentially equal to the number of individuals in the data set.

OPTIONS:

MARGINALS: Requests that marginal cumulatives be obtained (the default). These values are found in NONMEM global variables (See Section 53.66, Section 53.66).
ETAS: Requests that conditional (nonparametric) estimates of eta values be obtained. (Also called the CNPE).
MSFO=filename: A Model Specification File is output to the given filename. Filename may not contain embedded spaces. Filename may contain at most 71 characters. The MSFO option may appear without a file name.
RECOMPUTE: Requests that the nonparametric density estimate occurring in an input MSF should be ignored; the nonparametric estimate should be recomputed.
EXPAND: After the parametric estimation is performed, the final eta MAP (or empirical Bayes estimates, EBE) estimates, based on the final SIGMAS, OMEGAS, and THETAS, are normally used as support points. When EXPAND is selected, an alternative set of EBEs are evaluated using the initial OMEGA values, but using the final THETAS and SIGMAS.
NPSUPP=n: Number of total support points to be used. If NPSUPP>number of subjects, then extra support points are randomly created from the final OMEGAS. Only one of NPSUPP or NPSUPPE may be specified.
NPSUPPE=n: Number of total support points to be used. If NPSUPPE>number of subjects, then extra support points are randomly created from the initial, presumably inflated, OMEGAS (even when EXPAND is not selected). Only one of NPSUPP or NPSUPPE may be specified.
BOOTSTRAP: The original data set is fitted during the parametric estimation ($EST), and the eta support points from the original data set are used for the nonparametric version. However, a bootstrap sample, with subjects uniformly randomly selected with replacement from the original data set, is used for the nonparametric distribution analysis.
STRAT: The label of a data item that serves as the stratification. This splits the data set into distinct sub-sets, guaranteeing a specific number of subjects will be selected from each category.
STRATF: The label of a data item that contains the fraction that should represent a category in the bootstrapped data set. Without STRATF, the number of subjects to be taken from a given category is proportional to the number of subjects.
CONDITIONAL: The Nonparametric Step is implemented only when the Estimation Step terminates successfully or is not implemented (i.e., the $ESTIMATION record specifies MAXEVAL=0). This is the default.
NPESTIM=[0|1]: The default non-parametric estimation method for assessing support point probabilities is an (non-Monte Carlo) expectation-maximization (EM) method. You may also choose the non-negative least squares method (NNL, [29]), with NPESTIM=1.
NPMAXITER=n: The default maximum iterations for non-parametric estimation of assessing support point probabilities is 1000, which is usually more than enough.
PARAFILE=filename: As of NONMEM 7.4, nonparametric analysis can be parallelized. PARAFILE=filename specifies a different parafile than was used for the previous step. PARAFILE=ON turns on parallelization for the Nonparametric Step. PARAFILE=OFF turns off parallelization for the Nonparametric Step.
UNCONDITIONAL: The Nonparametric Step is always implemented.
OMITTED: The Nonparametric Step is not implemented.

REFERENCES: None.

27 `$OLKJDF`

MEANING: Specifies LKJ decorrelation degrees of freedom for each OMEGA block

CONTEXT: NM-TRAN Control Record

USAGE:

$OLKJDF 0 (default)
$OLKJDF [value ...]
$OLKJDF [(value)[xn]] ...

DISCUSSION:

OLKJDF is an option of the $ESTIMATION record. $OLKJDF is a separate record that allows the user to specify LKJ decorrelation degrees of freedom for each OMEGA block.

SAMPLE:

$OLKJDF 4.5 3.5 -2.0

Where 4.5 degrees of freedom are specified for the first omega block, 3.5 for the second, and -2.0 specifies 2 degrees of freedom for the third omega block, but a user-defined definition of the standard deviations of the diagonals for the third omega block. Use the OMEGA_STD_PRIORU.f90 file in the ..\source directory as a template to modify the OMEGA_STD_PRIORU to provide the desired probability density function. Set $SUBR OTHER=OMEGA_STD_PRIORU.f90 to use the user modified template (you may rename the file for organizational purposes).

RECORD ORDER: Follows $OMEGA.

REFERENCES: Guide Introduction_7

28 `$OMEGA`

MEANING: Supplies initial estimates for the NONMEM OMEGA Matrix

CONTEXT: NM-TRAN Control Record

USAGE:

$OMEGA [DIAGONAL(n) | BLOCK(n) | BLOCK(n) SAME(m) | BLOCK SAME(m)]
[[value1] [value2] [value3] ...
[(value,value...) xn]
[BLOCK(n) VALUES(diag,odiag)]
[label = value] ...
[BLOCK(n) [NAMES (label1,...,labeln)] [VALUES (diag,odiag)]
[FIXED] [UNINT]
[VARIANCE|STANDARD] [COVARIANCE|CORRELATON] [CHOLESKY]
[SCALE(scalevalue)]

SAMPLE:

$OMEGA BLOCK(3) 6. .005 .3 .0002 .006 .4

DISCUSSION:

Gives initial estimates and constraints for elements of one or several blocks of the OMEGA matrix, i.e., the matrix of variances and covariances of the eta variables in the statistical model. This record should appear only if the statistical model contains eta variables. Multiple $OMEGA records may be used to define multiple blocks of OMEGA. The order of the appearance of all blocks over all records corresponds to the order of the blocks in OMEGA.

If the initial estimates are omitted for any element(s) of OMEGA, then NONMEM will try to obtain the initial estimates.

See also the SPECIAL CASE below for the analysis type POPULATION WITH UNCONSTRAINED ETAS.

OPTIONS:

There are seven forms:

1. $OMEGA [DIAGONAL(n)] [ v11 v22 v33 ... vnn ]: This gives the initial estimates of the diagonal elements of a diagonal block of OMEGA. E.g.,

$OMEGA .04 .12
Initial estimate of variance of eta(1) = .04
Initial estimate of variance of eta(2) = .12

Each initial estimate may optionally be coded with one of the forms: init options (init options) (options init).

With NONMEM 7.3 (value,value...)xn is permitted, so that repeated inputs of $OMEGA may be entered easily.

The following options apply only to a single initial estimate (i.e., a single 1x1 block) and must follow the initial estimate unless within parentheses.

Option FIXED indicates that the variance is to be constrained to be fixed to the given initial estimate. (When FIXED appears anywhere, then the block is described by NONMEM as consisting of separate blocks, each of dimension one.)

Option UNINT is used with NONMEM 7.5. UNINT is used during the Optimal Design Step to identify an eta as uninteresting. UNINT may be used anywhere that FIXED may be used.

Option VARIANCE indicates that the initial estimate is understood to be a variance of the eta. This is the default.

Option STANDARD indicates that the initial estimate is understood to be a standard deviation of the eta. May also be coded SD. An initial estimate may be 0 only if the variance or standard deviation is fixed to this estimate.

2. $OMEGA BLOCK(n) [ v11 v21 v22 v31 v32 v33 ... vn1 vn2 ... vnn ]: This gives the initial estimates of all the elements of a nondiagonal (“full”) block of OMEGA. E.g.,

$OMEGA BLOCK(2) .04 .002 .12
Initial estimate of variance of eta(1) = .04
Initial estimate of covariance of eta(2), eta(1) = .002
Initial estimate of variance of eta(2) = .12

The following options apply to the entire block and may appear anywhere among the list of initial estimates:

FIXED: the entire block is constrained to be fixed to its initial estimate.
UNINT (NM75): identify an eta as uninteresting during Optimal Design Step.
VARIANCE: all initial estimates given for diagonal elements are understood to be initial estimates of variances of etas (default).
STANDARD (also SD): all initial estimates given for diagonal elements are understood to be initial estimates of standard deviations of etas.
COVARIANCE: all initial estimates given for off-diagonal elements are understood to be initial estimates of covariances of etas (default).
CORRELATON: all initial estimates given for off-diagonal elements are understood to be initial estimates of correlations of etas.
CHOLESKY: the block is specified in its Cholesky form.

Options VARIANCE or STANDARD may be combined with COVARIANCE or CORRELATON.

Note that NONMEM converts all initial estimates to variance and covariances.

Examples. The following describe the same block (within rounding errors):

$OMEGA BLOCK(2) ; or $OMEGA VARIANCE COVARIANCE BLOCK(2)
0.64
-0.24 0.58

$OMEGA STANDARD BLOCK(2)
0.8
-0.24 0.762

$OMEGA STANDARD CORRELATION BLOCK(2)
0.8
-0.394 0.762

$OMEGA VARIANCE CORRELATION BLOCK(2)
0.64
-0.394 0.58

$OMEGA CHOLESKY BLOCK(2)
0.8
-0.3 0.7

The (entire) initial estimate of the block must be positive definite. The only exception is when the entire initial estimate of the block is 0, in which case it must be fixed to this estimate.

With NONMEM 7.3 if the initial estimate of a block is not positive definite because of rounding errors, a value will be added to the diagonal elements to make it positive definite. A message in the NONMEM report file will indicate that this was done.

3. $OMEGA BLOCK(n) SAME(m): This describes a block whose initial estimates, as well as final estimates, are constrained to be equal to those of the preceding block. Values may not be given. (n) may be omitted.

With NONMEM 7.3 (m) is permitted. If (m) is present, then this record is equivalent to m identical records without (m).

4. $OMEGA BLOCK(n) VALUES(diag,odiag): This supplies initial values for a block such that the initial estimates of the diagonal elements are all the same, specified by “diag”, and the initial estimates of the off-diagonal elements are all the same, specified by “odiag”. If present, VALUES must follow BLOCK.

E.g.,

$OMEGA BLOCK(6) VALUES(0.1,0.01)

is the same as:

$OMEGA BLOCK(6)
0.1
0.01 0.1
(0.01)x2 0.1
(0.01)x3 0.1
(0.01)x4 0.1
(0.01)x5 0.1

For fixed block (such as for omega priors): $OMEGA BLOCK(6) FIX VALUES(0.15,0.0)

5. $OMEGA label=value (NM75): The symbolic label substitution feature is new with NONMEM 7.5. This is a compact method of defining an ETA (an element of OMEGA) specifying its initial estimate, and specifying a label for the subscript for this element of OMEGA. The label may be used as a subscript for ETA in abbreviated code, and will also identify this element of OMEGA in the NONMEM output.

For example, suppose the first element of OMEGA that is defined happens to be:

$OMEGA ECL = .4

The NONMEM report will describe the relationship, e.g., LABELS FOR ETAS ETA(1)=ETA(ECL), and ETA(CL) rather than ETA1 will appear in the NONMEM report.

6. $OMEGA BLOCK(n) NAMES (label1,...,labeln) VALUES (odiag,diag) (NM75): With NONMEM 7.5, Symbolic label substitution may be specified for an entire block using the NAMES option.

$OMEGA BLOCK(4) NAMES(ECL,EV1,EQ,EV2) VALUES(0.03,0.01)

7. $OMEGA SCALE(scalevalue) (NM760): As of nm760, you may have your OMEGA or SIGMA values multiplied by a SCALE value. The SCALE value takes into affect on any OMEGA or SIGMA values that come after it in the record.

SPECIAL CASE (NONMEM 7.3)

If all diagonal elements of OMEGA are “1.0E+06 FIXED”, then NONMEM describes the data as ANALYSIS TYPE: POPULATION WITH UNCONSTRAINED ETAS.

Structurally NONMEM sees the analysis as population, but mathematically, the population density portion of the total likelihood is not included. This allows a population data set to be analyzed as if the data from each individual were single-subject data.

REFERENCES: Guide I, section C.3.4.6, D.5.2, D.5.3; Guide IV, section III.B.10, V.C.6; Guide V, section 9.3

29 `$OMEGAP`, `$OMEGAPD`

MEANING: Gives prior information for omegas

CONTEXT: NM-TRAN Control Record

USAGE:

$OMEGAP value1 [value2] [value3] ...
$OMEGAPD value1 [value2] [value3] ...

SAMPLE:

; Prior to OMEGA (NETPxNETP=4x4 of them)
$OMEGAP BLOCK(4)
0.2 FIX
0.0 0.2
0.0 0.0 0.2
0.0 0.0 0.0 0.2
; Set degrees of freedom of OMEGA Prior (one value per OMEGA block)
$OMEGAPD (4 FIX)

DISCUSSION:

These are called the informative forms (i.e., informative record names) of the $OMEGA record, for use with the NWPRI utility.

$OMEGAP gives prior information for elements of the OMEGA matrix. $OMEGAPD gives degrees of freedom (also called the dispersion factor) for OMEGA priors.

The name of the record describes the kind of information it gives, rather than the structure of the information. E.g., in the example above, $OMEGAPD is implemented in FCON with a $THETA record because it is always a vector of values. These records may be located anywhere in the control stream. NM-TRAN inserts the corresponding records in the control stream in the correct order. When the informative forms are used, the options of $PRIOR NWPRI need not be specified. However, if options are listed in $PRIOR NWPRI, then these values are chosen over what is surmised from the informatively labeled theta/omega/sigma records. (See Section 59.12).

OPTIONS:

The option FIXED should be used. Other appropriate options are BLOCK and VALUES.

REFERENCES: Guide Introduction_7

30 `$OMIT`

MEANING: Defines data item types to be excluded from template matching when raw data averages are computed

CONTEXT: NM-TRAN Control Record

USAGE:

$OMIT item1 item2 item3 ...

SAMPLE:

$OMIT TIME

DISCUSSION:

Optional. If a label of a data item type listed in the $INPUT record, or a synonym for such a data item type, appears in the $OMIT record, then data items of this type are excluded from template matching.

REFERENCES: None

31 `$OVARF`

MEANING: Specifies the weighting to the standard deviations of OMEGA

CONTEXT: NM-TRAN Control Record

USAGE:

$OVARF 0 (default)
$OVARF [value ...]
$OVARF [(value)[xn]] ...

SAMPLE:

$OVARF 2.0 5.0

Where 2.0 is specified for the first omega block, 5.0 for the second. If the corresponding $OLKJDF value is negative then this is argument STDSSP in user-defined OMEGA_STD_PRIORU.f90.

DISCUSSION:

The $OVARF is a separate record that allows the user to specify the weighting (inverse variance) to the standard deviations LKJ decorrelation degrees of freedom for each OMEGA block. Used with NUTS method. $EST OVARF over-rides $OVARF.

REFERENCES: Guide Introduction_7

32 `$PK`

MEANING: Marks the beginning of abbreviated code for the PK Routine

CONTEXT: NM-TRAN Control Record

USAGE:

$PK
abbreviated code

DISCUSSION:

The $PK record is used to model the values of basic and additional pharmacokinetic parameters. It is used with PREDPP.

Basic PK parameters are typically the rate constants (“micro-constants”) for use in kinetic formulas. $PK can compute instead parameters such as clearance and volume, and a translator (“TRANS”) subroutine can be used to convert these to rate constants. Additional PK parameters include compartment scale parameters, which PREDPP uses to convert compartment amounts to concentrations, and dose-related parameters such as modeled infusion rates.

ASSIGNMENT AND CONDITIONAL STATEMENTS

Left-hand quantities in assignment statements:

Basic PK parameters for the ADVAN and TRANS routines (Required, except with the General Nonlinear Kinetics Models ADVAN6, ADVAN8, ADVAN9, ADVAN13, ADVAN14, ADVAN15, ADVAN16, ADVAN17, ADVAN18). One or more of the following, depending on which ADVAN and TRANS are being used:

K CL V (ADVAN1)
KA K CL V (ADVAN2)
K K12 K21 CL V Q VSS V1 V2 ALPHA BETA AOB (ADVAN3)
KA K K23 K32 CL V Q VSS V1 V2 V3 ALPHA BETA AOB (ADVAN4)
Km0 Kmn (ADVAN5, ADVAN7)
P(n) (ADVAN6, ADVAN8, ADVAN9, ADVAN13, ADVAN14, ADVAN15, ADVAN16, ADVAN17, ADVAN18)
VM, KM (ADVAN10)
K K12 K21 K13 K31 CL Q2 Q3 V1 V2 V3 ALPHA BETA GAMMA (ADVAN11)
KA K K23 K32 K24 K42 CL Q3 Q4 V2 V3 V4 ALPHA BETA GAMMA (ADVAN12)

P(n) are referred to as “explicit” basic PK parameters. Any variable defined in $PK may be used on the right-hand side in a $DES or $AES block; these are “implicit” basic PK parameters.

Additional PK parameters (Optional). One or more of the following, depending on the compartments defined for the model. The digit following the letter is the compartment number.

Scale parameters Sn, e.g.: S1 S2 S3 S4 SC S0.
Bio-availability fractions Fn, e.g.: F1 F2 F3.
Output fractions Fn, e.g.: F2 F3 F4 F0 FO.
Infusion rates Rn, e.g.: R1 R2 R3.
Infusion durations Dn, e.g.: D1 D2 D3.
Absorption lags ALAGn, e.g.: ALAG1 ALAG2 ALAG3.
Time scale: TSCALE (may be written XSCALE).
Model event times MTIME(i), e.g.: MTIME(1) MTIME(2). (The subscript i is not a compartment number.) (See MTIME)

Initial compartment amounts (Optional), e.g.: A_0(1) A_0(2). (See Section 53.14)

Initial steady state flag I_SS (Optional). (See advan68, advan9, Section 53.55) (See Initial Steady State: I_SS, Section 53.45).

PK-defined (i.e., PRED-defined) items.

Right-hand quantities in assignment statement and in conditions:

Data item labels specified on the $INPUT statement.
THETA(n).
ETA(n) (Used if the data are population.)
PK-defined items that appeared earlier as left-hand quantities.

NEWIND: Same as the NEWIND argument passed by NONMEM to PREDPP. NEWIND=0: First record of the data set. THETA value may differ from value at last call with this record. NEWIND=1: First record of the data set, THETA value does not differ from value at last call with this record, and PRED is nonrecursive (See I_REC), or, First record of a subsequent individual record. NEWIND=2: Subsequent data record of an individual record.
ICALL: Same as the ICALL argument passed by NONMEM to PREDPP. ICALL=1: Initialization. ICALL=2: Normal call. ICALL=3: Finalization. ICALL=4: Simulation. ICALL=5: Expectation. ICALL=6: Raw data averages.

Global Variables in Modules. Certain variables in FORTRAN modules can be used. (See Section 53.111) The following are of particular interest.

DOSTIM DOSREC(n): If PK is not being called at an additional or lagged dose time, then DOSTIM = 0 and all elements of DOSREC are 0.

If PK is called at an additional or lagged dose time t, then DOSTIM=t (See Guide VI, Chapter III). DOSREC contains a copy of the dose event record which initiated the additional or lagged dose (actually, only of the final row: EVTREC(NVNT,*)). Data items may be referred to by position or by label, e.g., DOSREC(1) or DOSREC(ID). In DOSREC, TIME and all user (concomitant) data items have values from the next event record. All other NONMEM/PREDPP reserved data items have values from the initiating dose event record. (The $BIND record may be used to override this.)

A(n) TSTATE: A(n) are the latest computed compartment amounts, and TSTATE is the time at which they were computed. That is, A(n) are the amounts at the previous event time, or if at a later time, but before the time for which PK is being called, a lagged or additional dose was given, or a regular infusion was terminated, or a modeled event occurred, then A(n) are the amounts at the latest such time. If there are population etas, and A(n) are used in the $PK abbreviated code, then any $OMEGA records referring to etas explicitly used in this code should precede the $PK record, or if an $MSFI record is used, it should precede the $PK record and include the option NPOP=m.

Note: If there is no verbatim code and no explicit use of a subscripted variable A in the $PK record, then the symbol A can be used as a data item label or as a name of a PK-defined item.

A_0FLG: A_0FLG signals a record with which it is possible to initialize a compartment amount. (See Section 53.14)

Forbidden Variable Names: IDEF IREV EVTREC NVNT INDXS IRGG GG NETAS DADT(n) E(n) EPS(n)

PSEUDO ASSIGNMENT STATEMENTS:

COMRES=-1

CALLFL=-2: Call with every event record and at additional and lagged dose times.
CALLFL=-1: Call with every event record.
CALLFL=0: Call with first event record and new TIME values.
CALLFL=1: Call once per individual record.

Of the last four, CALLFL=-2 is the default when DOSREC, DOSTIM, or MTIME are used explicitly in the abbreviated code. Otherwise, CALLFL=-1 is the default.

The pseudo-assignments statements may be enclosed in parentheses. If two of them are present in the same set of parentheses, separate them with a semicolon. A calling protocol phrase may be used within parentheses instead of a pseudo-assignment statement, and either upper or lower case may be used. E.g.,

$PK (ONCE PER IR) ; same as CALLFL = 1
$PK (NEW TIME) ; same as CALLFL = 0
$PK (EVERY EVENT) ; same as CALLFL = -1
$PK (NONEVENT) ; same as CALLFL = -2

RECORD ORDER:

Follows $SUBROUTINES and $INPUT.
Follows $MODEL (with General Nonlinear Kinetics Models ADVAN6, ADVAN8, ADVAN9, ADVAN13, ADVAN14, ADVAN15, ADVAN16, ADVAN17, ADVAN18).
Precedes $ERROR (if present).

REFERENCES: Guide IV, section V.C.5; Guide V, section 7; Guide VI, section III

33 `$PRED`

MEANING: Marks the beginning of abbreviated code for the PRED routine

CONTEXT: NM-TRAN Control Record

USAGE:

$PRED
abbreviated code

DISCUSSION:

The $PRED record is used to model values for the DV data items. It is NOT used with PREDPP (but (See Section 53.36)).

ASSIGNMENT AND CONDITIONAL STATEMENTS

Left-hand quantities in assignment statements:

Y (Required. The modeled value for the dependent variable under the statistical model.)
PRED-defined items.

Right-hand quantities in assignment statement and in conditions:

Data item labels specified on the $INPUT statement.
THETA(n).
ETA(n) (Used if the data are population or single-subject data, and in the latter case can be coded ERR(n).)
EPS(n) (Used if the data are population, and can be coded ERR(n).)
PRED-defined items that appeared earlier as left-hand quantities. This includes Y.

NEWIND: Same as the NEWIND argument passed by NONMEM to PREDPP. NEWIND=0: First record of the data set. THETA value may differ from value at last call with this record. NEWIND=1: First record of the data set, THETA value does not differ from value at last call with this record, and PRED is nonrecursive (See I_REC), or, First record of a subsequent individual record. NEWIND=2: Subsequent data record of an individual record.
NEWL2: NEWL2=1: First record of an L2 record. NEWL2=2: Otherwise.
ICALL: ICALL=0: Run initialization. ICALL=1: Problem initialization. ICALL=2: Normal call. ICALL=3: Problem finalization. ICALL=4: Simulation. ICALL=5: Expectation. ICALL=6: Data Average.
Variables in Fortran modules: Certain variables in FORTRAN modules can be used. (See Section 53.111)

Forbidden Variable Names: DATREC INDXS G H DADT(n) A(n) E(n) P(n)

PSEUDO ASSIGNMENT STATEMENTS: COMRES=-1

RECORD ORDER: Follows $SUBROUTINES and $INPUT.

REFERENCES: Guide I, section C.2; Guide IV, section III.B.8, IV; Guide V, section 12.3

34 `$PRIOR`

MEANING: Provides instructions for the PRIOR subroutine

CONTEXT: NM-TRAN Control Record

USAGE:

$PRIOR subroutine [(conditional clause1), (conditional clause2) ...]
[DISPLAY[= ALL|CNT]] [ICMAX = n]
[argument1, argument2 ...]

SAMPLE:

$PRIOR TNPRI (PROBLEM 2) PLEV = .9999 ISS = 0 IVAR = 1

DISCUSSION:

Optional. Specifies the use of the PRIOR feature of NONMEM. Note that $PRIOR is a control record, not a block of abbreviated code. Therefore, only those options that are listed here may be used. E.g., verbatim code may not be used. Options and arguments may be in any order, and may be on more than one line.

OPTIONS:

subroutine: Required. Either TNPRI or NWPRI. The following options and arguments apply to calls to this subroutine. Another subroutine option (or another $PRIOR record) may follow, with a new set of options and arguments. Use only NWPRI for the new $ESTIMATION methods of NONMEM 7.
conditional clause: Optional. One or more conditions, within parentheses. The conditions are “AND”ed together, i.e., the subroutine is called when all conditions in the conditional clause are true. If there is more than one conditional clause, the clauses are “OR”ed together. Conditions may be one or more of:

ESTIMATION or SIMULATION: Specifies the NONMEM task for which the subroutine is to be called. If omitted, PRIOR is called for all tasks (i.e., for all values of ICALL). ESTIMATION and SIMULATION may not both be specified in the same conditional clause. ESTIMATION may be spelled ESTIMATE or ESTM; SIMULATION may be spelled SIMULATE or SIML. May also be specified as ICALL=n, ICALL.EQ.n, or ICALLn, where n is 2 (ESTIMATION) or 4 (SIMULATION).
PROBLEM=n: Specifies the problem for which the subroutine is to be called. May also be specified as PROBLEM=n or PROBLEM.EQ.n or PROBLEMn. PROBLEM may also be coded as IPROB. Instead of =, .EQ. may be used. Other permitted tests are .NE., .LT., .LE., .GT., and .GE..

DISPLAY[=ALL|CNT]: Optional. The PRIOR subroutine will contain code to print items of interest in the NONMEM report. This is to assist the user in checking that the $PRIOR record is working correctly.

DISPLAY=ALL is the default when only DISPLAY is present. Lines such as the following are printed with every call to PRIOR:

PRIOR ICALL,IPROB,IREP,CNT: 2 2 0 -41.898951681785.

With DISPLAY=CNT, lines such as the following are printed only when PRIOR is called for simulation or estimation.

PRIOR CNT: -41.898951681785

ICMAX=n: Optional. The PRIOR subroutine will set the given value in ICMAX prior to calling the subroutine. (See Section 53.86).
Subroutine arguments: Optional. The arguments are described in the help entries for NWPRI and TNPRI. They must be coded exactly as shown, i.e., no abbreviations. Any argument that is omitted defaults to 0.

ITYP, NSAM, ISS, PLEV, CNT: Arguments for both NWPRI and TNPRI.
NTHETA, NETA, NEPS, NTHP, NETP, NEPP, NPEXP: Arguments unique to NWPRI.
IFND, MODE, IVAR: Arguments unique to for TNPRI.

EXAMPLES:

$PRIOR TNPRI (ESTIMATION, PROB >= 3) IFND = 1

TNPRI is called with the Estimation step of problems 3 and higher. IFND is set to 1 with these calls; all other arguments are 0.

$PRIOR TNPRI IFND = 1
(EST, PROB 3) (EST,PROB 4) (EST,PROB 5)

Same as the preceding example, if the run consists of exactly five problems. TNPRI is called with the Estimation step of problems 3, 4 and 5.

$PRIOR TNPRI (EST, PROB 3) IFND = 1
TNPRI (EST, PROB 4) IFND = 1
TNPRI (EST, PROB 5) IFND = 1

Same as the preceding example. Note that IFND must be specified independently each time to be 1. With re-specification of the subroutine, all arguments are reset to 0. This permits identical or different arguments with each usage of the subroutine. NM-TRAN will warn if no argument is specified in a subsequent specification of TNPRI or NWPRI, in case the arguments have been omitted by error. One or more arguments may be set explicitly to 0 to prevent the warning. When the subroutine is specified more than once, then all specifications must be conditional, i.e., conditional clauses are required.

Within the same run, one may use TNPRI with some tasks or problems, and NWPRI with other tasks or problems. There may be at most 10 $PRIOR records per problem.

(See Section 59.21, Section 59.12, Section 57.6). (See tnpri example, nwpri example).

REFERENCES: Guide Introduction_VI

35 `$PROBLEM`

MEANING: Identifies the start of a NONMEM Problem Specification

CONTEXT: NM-TRAN Control Record

USAGE:

$PROBLEM [text]

SAMPLE:

$PROB THEOPHYLLINE POPULATION DATA

DISCUSSION:

The $PROBLEM record identifies the start of a NONMEM problem specification. The text becomes a heading for the NONMEM printout. This record is required. If the problem is part of a superproblem, $SUPER must precede the $PROBLEM record. If $SIZES is present, it must precede the first $SUPER or $PROBLEM record. Otherwise, the first NM-TRAN control record must be a $PROBLEM record. A $PROBLEM record other than the first one marks the beginning of another problem specification.

The text must be contained on a single record, and only the first 72 characters of text are used in the heading. Spaces and semicolons in text are regarded as part of the text. The text is optional.

REFERENCES: Guide IV, section III.B.1

36 `$RCOV`, `$RCOVI`

MEANING: Inputting Variance-Covariance information from another problem

CONTEXT: NM-TRAN Control Record

USAGE:

$RCOV FILE = filename [FORMAT|DELIM = s1] [TBLN = n]
$RCOVI FILE = filename [FORMAT|DELIM = s1] [TBLN = n]

SAMPLE:

$RCOV FILE = sirsample.cov TBLN = 1 DELIM =,

The $RCOV record can be used to load the variance-covariance matrix of estimates results from a previous problem, and use it for subsequent use in assessing total standard errors of table items without having to re-calculate the variance with a $COV step.

The record $RCOVI may be used to load the variance-covariance information from the inverse-covariance file:

$RCOVI FILE = sirsample.coi TBLN = 1 DELIM =,

The FILE=filename option is required. If FORMAT or DELIM is used, it should be the same as was specified on the $ESTIMATION record that created the file to be used. The default is s1PE12.5. TBLN is the table number in the file. If TBLN is not specified, it defaults to 1.

NONMEM describes the use of these records with a message in the report file and to the terminal such as the following:

LOADED VARIANCE/COVARIANCE DATA FROM FILE c5.cov

If NONMEM is unable to read the file, the message is:

COULD NOT FIND APPROPRIATE VARIANCE/COVARIANCE DATA IN FILE c5.cov

$RCOV and $RCOVI can be used with the $CHAIN record. For examples and discussion: See INTRODUCTION TO NONMEM 7, $RCOV and $RCOVI Record For Inputting Variance-Covariance information from another problem.

REFERENCES: Guide Introduction_7

37 `$SCATTERPLOT`

MEANING: Requests that NONMEM generate one or more scatterplots

CONTEXT: NM-TRAN Control Record

USAGE:

$SCATTERPLOT list1 VS list2 [BY list3]
[FROM n1] [TO n2] [UNIT]
[ORD0|NOORD0] [ABS0|NOABS0] [FIRSTONLY] [OBSONLY]
[NOSUB = [0|1]]
[UNCONDITIONAL|CONDITIONAL] [OMITTED]

SAMPLE:

$SCATTERPLOT (RES WRES) VS TIME BY ID

DISCUSSION:

Requests that families of NONMEM scatterplots be produced. Up to 20 families of scatterplots may be included in the problem. May also be coded $SCATTERS or $SCATTERGRAMS.

OPTIONS:

list1: A list of item labels to be plotted on the ordinate axis (the long axis on the printed output). The list may be enclosed in parentheses. It may include: Data item labels; Special items PRED, RES, and WRES.

The user may request the following additional diagnostic items by including their name in the list.

NPRED, NRES, NWRES: Calculated assuming non-conditional estimation and no eta-epsilon interaction. NPRED and NRES are same as PRED and RES. NWRES is same as WRES when INTERACTION is not set in $EST.
PREDI, RESI, WRESI: Calculated assuming non-conditional estimation with eta-epsilon interaction. Always same as PRED, RES, and WRES.
CPRED, CRES, CWRES: Calculated assuming conditional estimation and no eta-epsilon interaction.
CPREDI, CRESI, CWRESI: Calculated assuming conditional estimation with eta-epsilon interaction.
CIPRED, CIRES, CIWRES: Conditional individual values.
CIPREDI, CIRESI, CIWRESI: Conditional individual values with eta-epsilon interaction.
EPRED, ERES, EWRES: Monte-Carlo generated diagnostics and are not linearized approximations like the other diagnostic types. EWRES is the Monte-Carlo version of CWRESI.
ECWRES: Monte-Carlo version of CWRES.
NPDE: Monte-Carlo generated normalized probability distribution error.
NPD: The correlated (or non-decorrelated) NPDE value.
OBJI: Objective function values for each individual (same as given in the root.phi file). The sum of the individual objective function values is equal to the total objective function.

Labels ETA(1), ETA(2), ... ,ETA(10), ... , ETA(70), etc., or alternatively, labels ETA1, ETA2, ... ,ET10, ... , ET70, etc., corresponding to eta(1), eta(2), etc. The labels in the output will be ETA1, ETA2, ... , ET10, ... ET70, etc.

With NONMEM 7.3, a range of etas may be requested:

$SCAT ETAS(1:2) VS ETA3

is equivalent to $SCAT ETA1 ETA2 VS ETA3. However, unlike $TABLE, $SCAT will ignore implied endings, such as $SCAT ETAS(1:LAST) VS ETA3 (just interpret it as $SCAT ETA1 VS ETA3). With NONMEM 7.4, more flexible syntax is available, using TO and BY.

With NONMEM 7.4, a symbolic label specified in $ABBR REPLACE may be listed in $SCAT.

Reserved positions of MODULE NMPRD4 (See $ABBREV). COM(k) or :k denotes the kth reserved position. (There must be exactly 4 digits after “:”. Use leading 0’s as necessary.) E.g., COM(3) or :003. Labels of the form :k will be used in the output.

Labels of PRED-defined items in MODULE NMPRD4 if abbreviated code is present (up to PDT distinct such labels in any one problem, for all tables and scatterplots. PDT is a constant in resource/SIZES.f90; default value is 500.)

These may include labels of the NM-TRAN-defined items:

0nnn e.g., 0010 stands for A00nnn
1nnn e.g., 1010 stands for A01nnn
2nnn e.g., 2010 stands for C00nnn
3nnn e.g., 3010 stands for D00nnn
4nnn e.g., 4010 stands for E00nnn
5nnn e.g., 5010 stands for F00nnn
6nnn e.g., 6010 stands for P00nnn

These may also include labels VECTRA(1), VECTRA(2), ... ,VECTRA(9), or alternatively, labels VA_1, VA_2, ... ,VA_9. Similarly, for VECTRB and VECTRC.

Synonyms may be defined on either the $TABLE or $SCATTER record for special items PRED, RES, WRES; for PRED-defined items; for NM-TRAN-defined items; and for reserved positions of MODULE NMPRD4.

E.g., assume that IWRES is a PRED-defined label, that at least 3 positions of NMPRD4 are reserved, and that NM-TRAN has generated A00032 as the label for a derivative in the generated FSUBS routine. Either $TABLE or $SCATTER records may include:

WRES=RES1,IWRES=RES2,COM(3)=ABC,0032=DK.

Elements of G and H. E.g., $SCATTER G11 BY G21. The format is Gk1 or Hk1, where k is an integer value, e.g. 1-9 or 01-99 or 001-999. Gk1 requests the value of G(k,1), and Hk1 requests the value of H(k,1), where G and H are arguments of subroutine PRED.

list2: Like list1, but includes the labels of items to be plotted on the abscissa axis (the short axis on the printed output). The list may be enclosed in parentheses. The word “VS” is optional; it may be omitted if the lists are enclosed in parenthesis, or if each list consists of exactly one item label. VS may also be coded *. Each pair of labels, one from list1 and one from list2, defines a family of scatterplots.
list3: A list of one or two item labels or synonyms. Each pair of labels from list1 and list2 produces a family of scatterplots, one scatterplot for each unique value (or combination of values) of the data item(s) in list3. If the BY option is omitted, each pair of labels from list1 and list2 produces a family comprised of a single scatterplot.
UNIT: A line of unit slope is superimposed on the scatterplots.
ORD0: A line through the zero value on the ordinate axis is superimposed on the scatterplots. May also be coded ORDZERO.
NOORD0: Prevents a zero line from being superimposed on the ordinate axis of the scatterplots. May also be coded NOORDZERO. If neither ORD0 nor NOORD0 is present, NONMEM automatically superimposes a zero line on the ordinate axis if it is appropriate for the type of data item.
ABS0: A zero line is superimposed on the abscissa axis of the scatterplots. May also be coded ABSZERO, AB0, or ABZERO.
NOABS0: Prevents a zero line from being superimposed on the abscissa axis of the scatterplots. May also be coded NOABSZERO, NOABS0, NOABZERO, NOAB0.
FIRSTONLY: Only the first data record from each individual record may contribute a point to the scatterplot. May also be coded FIRSTRECORDONLY or FIRSTRECONLY.
OBSONLY: The scatterplot will only use data records with MDV=0. This option applies independently of FIRSTONLY. It is not necessary when either DV, RES, or WRES is plotted.
FROM n1: n1 is the number of the first data record which may “contribute” to the scatterplot. Default: n1 is 1.
TO n2: n2 is the number of the last data record which may “contribute” to the scatterplot. Default: There is no upper limit. All appropriate records will contribute. To restore the NONMEM VI behavior, use TO n1+899.

With FIRSTONLY, n1 and n2 refer to (first records of) individual records.

NOSUB=[0|1]: With NOSUB=0, label substitution will be performed scatterplots. This is the default. With NOSUB=1, label substitution will not be performed.
CONDITIONAL: The Scatterplot Step is implemented only when the Estimation Step terminates successfully or is not implemented. This is the default.
UNCONDITIONAL: The Scatterplot Step is always implemented. This is the default.
OMITTED: The Scatterplot Step is not implemented.

When DV, RES, or WRES is plotted, records having MDV=1 are not plotted. The following symbols are used in scatterplots:

*          1 point
Overstriking:  2-9 points
2-9        10-35 points (A=10, B=11, ... , Z=35)
A-Z        more than 35 points
$

REFERENCES: Guide IV, section III.B.17; Guide V, section 9.5.2, 10.7.2

38 `$SIGMA`

MEANING: Supplies initial estimates for the NONMEM SIGMA Matrix

CONTEXT: NM-TRAN Control Record

USAGE:

$SIGMA [DIAGONAL(n) | BLOCK(n) | BLOCK(n) SAME(m) | BLOCK SAME(m)]
[[value1] [value2] [value3] ...
[(value,value...) xn]
[BLOCK(n) VALUES(diag,odiag)]
[label = value] ...
[BLOCK(n) [NAMES (label1,...,labeln)] [VALUES (diag,odiag)]
[FIXED] [UNINT]
[VARIANCE|STANDARD] [COVARIANCE|CORRELATON] [CHOLESKY]
[SCALE(scalevalue)]

SAMPLE:

$SIGMA BLOCK(3) 6. .005 .3 .0002 .006 .4

DISCUSSION:

Gives initial estimates and constraints for elements of one or several blocks of the SIGMA matrix, i.e., the matrix of variances and covariances of the eps variables in the statistical model. This record should appear only if the statistical model contains eps variables. Multiple $SIGMA records may be used to define multiple blocks of SIGMA. The order of the appearance of all blocks over all records corresponds to the order of the blocks in SIGMA.

If the initial estimates are omitted for any element(s) of SIGMA, then NONMEM will try to obtain the initial estimates.

OPTIONS:

There are seven forms (paralleling $OMEGA):

1. $SIGMA [DIAGONAL(n)] [ v11 v22 v33 ... vnn ]: This gives the initial estimates of the diagonal elements of a diagonal block of SIGMA. E.g.,

$SIGMA .04 .12
Initial estimate of variance of eps(1) = .04
Initial estimate of variance of eps(2) = .12

Options FIXED, UNINT (NM75), VARIANCE (default), STANDARD (also SD) apply as with $OMEGA. An initial estimate may be 0 only if the variance or standard deviation is fixed to this estimate.

2. $SIGMA BLOCK(n) [ v11 v21 v22 v31 v32 v33 ... vn1 vn2 ... vnn ]: This gives the initial estimates of all the elements of a nondiagonal (“full”) block of SIGMA. E.g.,

$SIGMA BLOCK(2) .04 .002 .12
Initial estimate of variance of eps(1) = .04
Initial estimate of covariance of eps(2), eps(1) = .002
Initial estimate of variance of eps(2) = .12

Options FIXED, UNINT (NM75), VARIANCE (default), STANDARD (also SD), COVARIANCE (default), CORRELATON, CHOLESKY apply as with $OMEGA.

The (entire) initial estimate of the block must be positive definite. The only exception is when the entire initial estimate of the block is 0, in which case it must be fixed to this estimate.

With NONMEM 7.3 if the initial estimate of a block is not positive definite because of rounding errors, a value will be added to the diagonal elements to make it positive definite.

3. $SIGMA BLOCK(n) SAME(m): This describes a block whose initial estimates, as well as final estimates, are constrained to be equal to those of the preceding block. Values may not be given. (n) may be omitted.

With NONMEM 7.3 (m) is permitted. If (m) is present, then this record is equivalent to m identical records without (m).

4. $SIGMA BLOCK(n) VALUES(diag,odiag): This supplies initial values for a block such that the initial estimates of the diagonal elements are all the same, specified by “diag”, and the initial estimates of the off-diagonal elements are all the same, specified by “odiag”. If present, VALUES must follow BLOCK.
5. $SIGMA label=value (NM75): The symbolic label substitution feature is new with NONMEM 7.5. This is a compact method of defining an EPS specifying its initial estimate, and specifying a label for the subscript for this element of SIGMA.

For example:

$SIGMA RSW = .06

The NONMEM report will describe the relationship, e.g., LABELS FOR EPS EPS(1)=EPS(RSW), and EPS(RSW) rather than EPS1 will appear in the NONMEM report.

As with $OMEGA, $SIGMA and $THETA records (if elements of THETA are used) must be placed ahead of any records that use the symbolic label.

6. $SIGMA BLOCK(n) NAMES (label1,...,labeln) VALUES (odiag,diag) (NM75): With NONMEM 7.5, Symbolic label substitution may be specified for an entire block using the NAMES option.

$SIGMA BLOCK(2) NAMES(RSW,EX) VALUES(0.03,0.01)

7. $SIGMA SCALE(scalevalue) (NM760): As of nm760, you may have your OMEGA or SIGMA values multiplied by a SCALE value. The SCALE value takes into affect on any OMEGA or SIGMA values that come after it in the record.

The SCALE is most useful when it is desired to scale an informed prior SIGMA from a previous analysis that differs from NONMEMs normal treatment. For example, you may wish to scale the sigma prior by (df-p-1)/df, where df=degrees of freedom, and p=dimension of sigma block.

REFERENCES: Guide I, section C.3.4.6, D.5.2, D.5.3; Guide IV, section III.B.10, V.C.6; Guide V, section 9.3

39 `$SIGMAP`, `$SIGMAPD`

MEANING: Gives prior information for sigmas

CONTEXT: NM-TRAN Control Record

USAGE:

$SIGMAP value1 [value2] [value3] ...
$SIGMAPD value1 [value2] [value3] ...

SAMPLE:

; Prior to SIGMA (NEPPxNEPP=1x1 of them)
$SIGMAP 0.05 FIX
; Set degrees of freedom of SIGMA Prior (one value per SIGMA block)
$SIGMAPD (1 FIX)

DISCUSSION:

These are called the informative forms of the $SIGMA record, for use with the NWPRI utility.

$SIGMAP gives prior information for elements of the SIGMA matrix. $SIGMAPD gives degrees of freedom (also called the dispersion factor) for SIGMA priors.

The name of the record describes the kind of information it gives, rather than the structure of the information. E.g., in the example above, $SIGMAPD is implemented in FCON with a $THETA record because it is always a vector of values. These records may be located anywhere in the control stream. NM-TRAN inserts the corresponding records in the control stream in the correct order. When the informative forms are used, the options of $PRIOR NWPRI need not be specified. (See Section 59.12).

OPTIONS:

The option FIXED should be used. Other appropriate options are BLOCK and VALUES.

REFERENCES: Guide Introduction_7

40 `$SIMULATION`

MEANING: Instructions for the NONMEM Simulation Step

CONTEXT: NM-TRAN Control Record

USAGE:

$SIMULATION (seed1 [seed2] [NORMAL|UNIFORM|NONPARAMETRIC] [NEW]) ...
[CLOCKSEED = [0|1]]
[SOURCE_EPS = n]
[SUBPROBLEMS = n] [ONLYSIMULATION] [OMITTED]
[REQUESTFIRST] [REQUESTSECOND] [PREDICTION|NOPREDICTION]
[TRUE = INITIAL|FINAL|PRIOR] [TTDF = n]
[BOOTSTRAP = n [REPLACE|NOREPLACE] [STRAT = label] [STRATF = label]]
[NOREWIND|REWIND] [SUPRESET|NOSUPRESET]
[RANMETHOD = [n|S|m|P]]
[PARAFILE = [filename|ON|OFF]

SAMPLE:

$SIMULATION (889215690) (2239177789 UNIFORM)

DISCUSSION:

Optional. Requests that the NONMEM Simulation Step be implemented. May also be coded $SIMULATE or $SIML.

Usually, when the Simulation Step is implemented, the simulated observation is taken to be the quantity to which the Y variable (with NM-TRAN abbreviated code) or F variable (with a user-supplied PRED or ERROR routine) is set. This is the default behaviour. However, see option NOPREDICTION below.

If a $ESTIM record appears in the problem specification, then unless the LIKELIHOOD or -2LOGLIKELIHOOD option appears on the $ESTIM record, etas (if any) are understood to be single-subject etas, except when epsilons also appear, in which case the etas are understood to be population etas. When the NOPREDICTION option is used, the etas are understood to be population etas.

In NM-TRAN abbreviated code, there can be a special block of code that is implemented only during the simulation task (See Section 53.42, Section 53.96).

OPTIONS:

The information coded within each set of parentheses defines the attributes of a single random source. A source of random numbers is an “infinite” stream of random numbers. Each pair of parentheses on the record defines a separate source of random numbers. The numbers from a source are explicitly available to the user via the NONMEM utility routine: RANDOM. By default, the first source is earmarked for the simulation of etas and epsilons.

seed1: Seed1 is the first seed for the random source, an integer between 0 and 2147483647. If this is not the first problem specification in the control stream, then seed1 can be -1, indicating that the random source is to be continued from the previous problem.
seed2: Seed2 is the second seed for the random source, an integer between 0 and 2147483647. For use of a second seed, see NONMEM Users Guide, Part IV.
NORMAL: The random numbers of the source are to be pseudo-normal with mean 0 and variance 1 (unless the source is the first and used to generate eta and epsilon realizations, in which case the variance-covariance of these variables is that specified in the $OMEGA and $SIGMA records). This is the default.
UNIFORM: The random numbers of the source are to be pseudo-uniform on the interval [0,1].
CLOCKSEED=[0|1] (NM75): If CLOCKSEED=1 (default is 0), actual starting seed will be 10000*(seconds after midnight)+SEED (applies to both seed1 and seed2, if specified.).
SOURCE_EPS=n (NM75): May be used to specify that the simulation of epsilons should use a different source than the default, which is the first. n is the number of the source for epsilons. This source must have the NORMAL attribute.
NONPARAMETRIC: The random numbers from the first source defined with the NONPARAMETRIC attribute are used to generate realizations of random vectors from a (multivariate) nonparametric distribution on eta, obtained from the Nonparametric Step of an earlier problem. An input MSF must also be present.
NEW: If the NEW option is used, the vector of eta’s (epsilon’s) changes with each call to SIMETA (SIMEPS), rather than only at the start of the next individual record.
ONLYSIMULATION: NONMEM is being asked to simulate data but not to evaluate an objective function on these data. WRES values in tables and scatterplots will be 0. PRED-defined data items in tables and scatterplots will be computed using simulated etas and initial thetas.

$ESTIM, $COV and $NONP cannot be used with ONLYSIMULATION.

SUBPROBLEMS=n: Requests that the entire NONMEM problem is to be repeated n times in succession (including all NONMEM steps: simulation, estimation, covariance, table, scatterplot). Each subproblem includes the Simulation Step, but the random sources are simply continued from subproblem to subproblem. If n=0 or n=1, there is only one subproblem; this is the default. May also be coded SUBPROBS, NSUBPROBLEMS, NSUBPROBS. With NONMEM 7.3 and higher, the maximum number of subproblems is increased from 9999 to 2147483647.
REQUESTFIRST: NONMEM sets a variable IFIRSTEM in Module ROCM_INT (referenced as FIRSTEM in abbreviated code) informing PRED whether or not PRED needs to compute first-partial derivatives with respect to eta. Normally, during the Simulation Step, these derivatives are not needed. With the REQUESTFIRST option, the FIRSTEM variable is set so to inform PRED that the derivatives need to be computed.
REQUESTSECOND: NONMEM sets a variable ISECDER in Module ROCM_INT (referenced as MSEC in abbreviated code) informing PRED whether or not PRED needs to compute second-partial derivatives with respect to eta. With the REQUESTSECOND option, the MSEC variable is set so to inform PRED that the derivatives need to be computed. REQUESTSECOND implies REQUESTFIRST.
PREDICTION: Permitted only with ONLYSIM, and is the default. With or without ONLYSIM, unless the NOPREDICTION is used, the simulated observation is taken to be the quantity to which the Y variable (with NM-TRAN abbreviated code) or F variable (with a user-supplied PRED or ERROR routine) is set. In a simulation block, the DV variable may be directly set to the simulated observation, but the Y (or F) variable should also be set to this observation.
NOPREDICTION: Permitted only with ONLYSIM. Indicates that the simulated observation will be taken to be the value to which the DV variable is set. Also, etas (if any) are understood to be population etas, even if epsilons do not appear.
TRUE=INITIAL: The initial estimates given in the control stream are used as the parameter values (“true values”) in the simulation, except when a model specification file is input. When a model specification file is input, the initial estimates with the previous run are used as the parameter values in the simulation, and the final estimates with the previous run are used as the initial estimates in all tasks other than the simulation. This is the default. May not be used with $MSFI in conjunction with SUBPROBLEMS=n (n > 1).
TRUE=FINAL: An input model specification file must be used. The final estimates with the previous run are used as the parameter values (“true values”) in the simulation and as the initial estimates in all tasks other than the simulation.
TRUE=PRIOR: The values stored in THET_P, OMEG_P, SIGM_P by the PRIOR routine are used as the true parameter values (“true values”) in the simulation.
TTDF=n (NM75): If TTDF is set to a non-zero integer value n, thetas are simulated with n degrees of freedom t-distribution. TRUE=PRIOR must be specified as well. Priors must also be specified appropriately.
BOOTSTRAP=n: With the BOOTSTRAP option, NONMEM does not perform the usual simulation activity of randomly creating DV values for a new data set, but rather selects a random set of subjects from an existing “template” data set. The BOOTSTRAP number n refers to how many subjects are to be randomly selected from the data set. Setting -1 means to randomly select as many subjects as are in the data set.
REPLACE: Subjects are selected with replacement. This results in some subjects not being selected at all, and some subjects selected more than once. This is the default.
NOREPLACE: Subjects are selected without replacement, that is, without repeating a subject.
STRAT: The label of a data item that serves as the stratification.
STRATF: The label of a data item that contains the fraction that should represent a category in the bootstrapped data set.
NOREWIND|REWIND: The NOREWIND option requests that if any input data item(s) are changed (transgenerated) during a the simulation step of a sub-problem, they remain changed at the start of the next sub-problem. This is the default. With NONMEM 7.4, the REWIND option requests that the original data set be used for all sub-problems.

Keep in mind that transgeneration performed on the data set using $INFN with ICALL=1 affects the original data set and these changes are unaffected by REWIND and NOREWIND options.

SUPRESET|NOSUPRESET: This option affects seeds for random sources when a $SIMULATION record is included in the scope of a $SUPER problem. The SUPRESET option requests that, with subsequent iterations of a super-problem, the seed(s) for all random sources are reset back to that listed in the $SIMULATION record of the control stream file. This is the default. With NONMEM 7.4, the NOSUPRESET option may be used to prevent resetting the random seeds.
RANMETHOD=[n|S|m|P]: As of NONMEM 7.3, the RANMETHOD option is available for the $SIM record, to use alternative random numbers generators. n is the random number generator type, S is Sobol sequence, and m is the Sobol scrambler. The default is NONMEM’s traditional one, n=4. Among the Sobol sequence methods, the S2 method appears to provide the least biased random samples. As of NONMEM 7.4, RANMETHOD will also act on the P modifier, which will retain separate seed sequences for each subject. (See Section 50.15).
PARAFILE=filename: As of NONMEM 7.4, the Simulation Step computation may be parallelized. By default, parallelization is not turned on. PARAFILE=filename specifies a different parafile. PARAFILE=ON turns on parallelization for the Simulation Step. Set RANMETHOD=P to permit assure consistent seed patterns regardless of whether or not parallelization is performed. E.g., $SIML ... PARAFILE=ON RANMETHOD=P. PARAFILE=OFF turns off parallelization for the Simulation Step. This is the default.
OMITTED: The Simulation Step is not implemented.

REFERENCES: Guide IV, section III.B.13, IV.I; Guide V, section 12.4.8; Guide VI, section III.C, III.E, IV.B, IV.G.1

41 `$SIZES`

MEANING: Array sizes for NONMEM and PREDPP

CONTEXT: NM-TRAN Control Record

USAGE:

$SIZES [constant = value] [constant = value] ...

SAMPLE:

$SIZES LIM1 = 30000 MAXFCN = 2000000 NO = 500

DISCUSSION:

$SIZES is optional. If present, it must precede the first $PROBLEM or $SUPER record.

Certain constants are used in NM-TRAN, NONMEM and PREDPP. With NONMEM 7.2 and higher, the user may override many of the constants with the $SIZES record.

See the discusion of sizes for a discussion of how these constants are determined, and how they are communicated to NONMEM and PREDPP. (See Section 53.102)

Any non-zero value specified on the $SIZES record overrides both the default and the value that NM-TRAN would have specified. (A value of 0 is ignored.) As of NONMEM 7.3, as an alternative to modifying sizes.f90 to very large maximum sizes, you can tell NMTRAN the maximum size that may be needed by specifying a $SIZES constant as a negative value. Thus, a user can give NMTRAN permission to deal with all problems that have data input files that have up to 1000 data items, and up to 150 etas and epsilons, and up to 200 thetas, by the following:

$SIZES PD = -1000 LVR = -150 LTH = -200

but the values of these constants when the NONMEM executable is constructed will be only what is needed for the particular problem. In contrast:

$SIZES PD = 1000 LVR = 150 LTH = 200

will result in sizing the NONMEM executable with these values, and won’t make a “tailor fit”. This would result in a very large executable regardless of the model size.

Thus, $SIZES PD=-1000 tells NMTRAN that you may need as many as 1000 data items in a data file, whereas $SIZES PD=1000 tells NMTRAN that you need exactly that size.

List of $SIZES Record Options and Their Default Values:

LTH=100
LVR=30
LVR2=20
NO=250
MMX=10
LNP4=4000
LSUPP=4050
LIM7=2
LWS3=9000
MAXIDS=10000
LIM1=10000
LIM2=100000
LIM3=10000
LIM4=1000
LIM5=200
LIM6=400
LIM8=200
LIM11=25
LIM13=1000
LIM15=1000
LIM16=400
MAXRECID=200
PC=30
PCT=30
PIR=700
PD=50
PDT=50
PAL=50
MAXFCN=1000000
DIMTMP=500
DIMCNS=500
DIMNEW=1000
DIMVRB=200
PL=10
NPOPMIXMAX=10
MAXOMEG=70
MAXPTHETA=90
MAXITER=210
ISAMPLEMAX=10
MAXSIDL=0
PNM_MAXNODES=100
MAXNRDS=PC
PAST_SIZE=4000

Additional constants that may be set with $SIZES: LADD_MAX (See resource/SIZES.f90).

(See Section 53.102)

REFERENCES: Guide Introduction_7

42 `$SLKJDF`

MEANING: Specifies LKJ decorrelation degrees of freedom for each SIGMA block

CONTEXT: NM-TRAN Control Record

USAGE:

$SLKJDF 0 (default)
$SLKJDF [value ...]
$SLKJDF [(value)[xn]] ...

DISCUSSION:

SLKJDF is an option of the $ESTIMATION record. $SLKJDF is a separate record that allows the user to specify LKJ decorrelation degrees of freedom for each SIGMA block.

SAMPLE:

$SLKJDF 4.5 3.5 -2.0

Where 4.5 degrees of freedom are specified for the first sigma block, 3.5 for the second, and -2.0 specifies 2 degrees of freedom for the third sigma block, but a user-defined definition of the standard deviations of the diagonals for the third sigma block. Use the SIGMA_STD_PRIORU.f90 file in the ..\source directory as a template to modify the SIGMA_STD_PRIORU to provide the desired probability density function. Set $SUBR OTHER=SIGMA_STD_PRIORU.f90 to use the user modified template (you may rename the file for organizational purposes).

RECORD ORDER: Follows $SIGMA.

REFERENCES: Guide Introduction_7

43 `$SUBROUTINES`

MEANING: Lists certain subroutine choices for the NONMEM Executable

CONTEXT: NM-TRAN Control Record

USAGE:

$SUBROUTINES [subname1 = name1] [subname2 = name2] ...
[TOL = n] [ATOL = n] [SSTOL = n] [SSATOL = n]
[SUBROUTINES = kind]

SAMPLE:

$SUBROUTINES PRED = pred

DISCUSSION:

Optional. Describes the choice of subroutines for the NONMEM executable (also called the NONMEM load module). May also be coded $SUBS.

One of the following is required:

ADVAN=name (also specifies the use of PREDPP).
PRED=name (specifies a user-supplied PRED routine).

OPTIONS:

subname=name: Subname is the entry name of a user-supplied subroutine to be included in the NONMEM executable. Name is the name of a file containing FORTRAN source code for the subroutine. Name is used by NM-TRAN as documentation (in FREPORT) and for inclusion of source code (in FSUBS). More than one such option may be specified. The names need not be unique. Name may not contain embedded spaces. Name may contain as many characters as fit a single line. It must not start with a digit. If name contains commas, semicolons, equal signs, or parentheses, it must be surrounded by single quotes ' or double quotes ".

Subname may be chosen from the following categories.

User-supplied NONMEM routines: CRIT MIX PRED CRIT MIX PRIOR CONTR CCONTR USMETA SPTWO

User-supplied PRED routine: PRED

Subroutines from the PREDPP library: ADVAN TRANS SS (See Section 56.21).

User-supplied PREDPP routines: PK ERROR MODEL DES AES TOL INFN

Other user-supplied subroutines: OTHER

OTHER specifies the name of a file that will be copied into FSUBS (e.g., OTHER=filename). A subroutine or function in file filename might be called by a user-supplied routine or by verbatim code. With NONMEM 7.4, it might be listed on a $ABBR FUNCTION record. The OTHER option may be used up to 40 times, to specify the names of up to 40 such files; each file may contain multiple subroutines and functions. These routines must be in Fortran 90 format.

SUBROUTINES=kind: Specifies the kind of subroutines to be included in the NONMEM executable (“kind” must be DP - double precision).
TOL=n: When PREDPP is specified with an ADVAN that requires a TOL routine, this option can be used to supply a NRD (“number of required digits”) value. “n” is an integer. This is a relative tolerance.

For TOL and the options that follow (ATOL, SSTOL, SSATOL), it is also possible to code TOL=name to specify the name of a user-supplied TOL routine, or to include $TOL abbreviated code, either of which allows all these values to be assigned by compartment. A user-supplied TOL routine also allows values to be assigned by compartment and for each NONMEM step. See also the TOL option of the $COVARIANCE record. Required.

ATOL=n: Specifies the absolute tolerance for ADVAN9, ADVAN13, ADVAN14, ADVAN15, ADVAN16, ADVAN17, and ADVAN18. Optional. Default is 1.0E-12. See also the ATOL option of the $ESTIMATION and $COVARIANCE records.
SSTOL=n: Specifies the relative tolerance for Steady State evaluation. Optional. Default is TOL.
SSATOL=n: Specifies the absolute tolerance for Steady State evaluation. Optional. Default is ATOL.

REFERENCES: Guide IV, section III.B.6

44 `$SUPER`

MEANING: Identifies the start of a NONMEM Superproblem

CONTEXT: NM-TRAN Control Record

USAGE:

$SUPER [SCOPE = n1] [ITERATIONS = n2]
[NOPRINT|PRINT]

SAMPLE:

$SUPER SCOPE = 2 ITERATIONS = 10

DISCUSSION:

Optional.

OPTIONS:

SCOPE=n1: Number of problems in the superproblem. Required. Must be at least 1.
ITERATIONS=n2: Number of iterations of the superproblem. Required. Must be at least 2. ITERATIONS may also be coded NITERATIONS.
NOPRINT: NONMEM printout displaying the input information for each of the problems of the superproblem will be generated only during the first iteration. This is the default.
PRINT: NONMEM printout displaying the input information for each of the problems of the superproblem will be generated during all iterations.

To define a sequence of problems as a superproblem, precede the $PROBLEM record of the first problem of the sequence with a $SUPER record. More than one $SUPER problem can be present in the control stream, but the level of nesting can be at most 2.

The pattern for nested super problems is:

$SUPER SCOPE = s1
$PROBLEM 1

...
$PROBLEM n
$SUPER SCOPE = s2
$PROBLEM n + 1

...
$PROBLEM n + m

The second super problem must be totally contained with in the first.

n >= 1 and m >= 1 is required (each $SUPER problem must contain at least one $PROBLEM).

If s1 > n, then the scope of the first $SUPER includes the second $SUPER, and the scope of the second must be entirely contained within the scope of the first: s1 >= n+s2.

(See Section 53.89).

REFERENCES: None.

45 `$SVARF`

MEANING: Specifies the weighting to the standard deviations of SIGMA

CONTEXT: NM-TRAN Control Record

USAGE:

$SVARF 0 (default)
$SVARF [value ...]
$SVARF [(value)[xn]] ...

SAMPLE:

$SVARF 2.0 5.0

Where 2.0 is specified for the first sigma block, 5.0 for the second. If the corresponding $SLKJDF value is negative then this is argument STDSSP in user-defined SIGMA_STD_PRIORU.f90.

DISCUSSION:

The $SVARF is a separate record that allows the user to specify the weighting (inverse variance) to the standard deviations LKJ decorrelation degrees of freedom for each SIGMA block. Used with NUTS method. $EST SVARF over-rides $SVARF.

REFERENCES: Guide Introduction_7

46 `$TABLE`

MEANING: Requests that NONMEM generate a table

CONTEXT: NM-TRAN Control Record

USAGE:

$TABLE [list1] [BY list2]
[PRINT|NOPRINT] [FILE = filename]
[NOHEADER|ONEHEADER] [ONEHEADERALL]
[NOTITLE|NOLABEL]
[FIRSTONLY|LASTONLY|FIRSTLASTONLY] [NOFORWARD|FORWARD]
[APPEND|NOAPPEND]
[FORMAT = s] [LFORMAT = s] [RFORMAT = s]
[IDFORMAT = s]
[NOSUB = [0|1]]
[EXCLUDE_BY list3]
[PARAFILE = [filename|ON|OFF]
[ESAMPLE = n1][WRESCHOL]
[SEED = n2] [CLOCKSEED = [0|1]]
[RANMETHOD = [n|S|m]]
[VARCALC = [0|1|2|3]]
[FIXEDETAS = (list)]
[NPDTYPE = [0|1]]
[INTERPTYPE = [0|1]]
[UNCONDITIONAL|CONDITIONAL] [OMITTED]

SAMPLE:

$TABLE ID DOSE WT TIME

DISCUSSION:

Requests that a NONMEM table be produced. Up to 10 $TABLE records may be included in a given problem.

OPTIONS:

list1: A list of item labels (i.e., user-chosen item types) to be tabled along with DV and the special items PRED, RES, and WRES.

The user may request the following additional special diagnostic items by including their name in the list:

NPRED, NRES, NWRES: Calculated assuming non-conditional estimation and no eta-epsilon interaction. NPRED and NRES are same as PRED and RES. NWRES is same as WRES when INTERACTION is not set in $EST.
PREDI, RESI, WRESI: Calculated assuming non-conditional estimation with eta-epsilon interaction. Always same as PRED, RES, and WRES.
CPRED, CRES, CWRES: Calculated assuming conditional estimation and no eta-epsilon interaction.
CPREDI, CRESI, CWRESI: Calculated assuming conditional estimation with eta-epsilon interaction.
CIPRED, CIRES, CIWRES: Conditional individual values.
CIPREDI, CIRESI, CIWRESI: Conditional individual values with eta-epsilon interaction.
EPRED, ERES, EWRES: Monte-Carlo generated diagnostics. EWRES is the Monte-Carlo version of CWRESI.
ECWRES: Monte-Carlo version of CWRES.
NPDE: Monte-Carlo generated normalized probability distribution error.
NPD: The correlated (or non-decorrelated) NPDE value.
OBJI: Objective function values for each individual.

In addition the list may include: Data item labels; Labels ETA(1), ETA(2), ... or ETA1, ETA2, ... etc.

With NONMEM 7.3, a range of etas may be requested: ETAS(k:n) is equivalent to ETAk, ..., ETAn where n > k. LAST can be used in place of n, and requests the last (highest numbered) eta in the problem. E.g. ETAS(1:LAST).

With NONMEM 7.4, more flexible syntax is available:

The word TO may be used in place of :.
The BY expression may be used: ETAS(1 TO 10 by 3) prints out etas 1,4,7,10.
ETAS(LAST TO 1 by -3) prints out etas 10,7,4,1 (assuming LAST=10).
A number list may be given: ETAS(1,5,12,4) prints out etas 1, 5, 12, 4.
ETAS(4:1) prints etas 4, 3, 2, 1.
ETAS(4:1 by -2) prints etas 4, 2.
ETAS(1:4 by -1) prints etas 4, 3, 2, 1 (the by value sets the direction).

With NONMEM 7.4, a symbolic label specified in $ABBR REPLACE may be listed in $TABLE. For example:

$ABBR REPLACE ETA(CL) = ETA(1)
...
$TABLE ETA(CL)

Reserved positions of MODULE NMPRD4 (See Section 50.1). COM(k) or :k denotes the kth reserved position. (There must be exactly 4 digits after :. Use leading 0’s as necessary.) E.g., COM(3) or :003. Labels of the form :k will be used in the output.

Labels of PRED-defined items in MODULE NMPRD4 if abbreviated code is present. These may include labels of the NM-TRAN-defined items (0nnn, 1nnn, 2nnn, 3nnn, 4nnn, 5nnn, 6nnn) and VECTRA(1), ..., VECTRA(9) (or VA_1, ..., VA_9). Similarly for VECTRB and VECTRC.

Elements of G and H. E.g., $TABLE G11 G21 G31 H11 H21. The format is Gk1 or Hk1, where k is an integer value. Gk1 requests the value of G(k,1), and Hk1 requests the value of H(k,1), where G and H are arguments of subroutine PRED.

When tables are printed, the maximum number of labels permitted in list1 is 8; otherwise, it is PDT. (But see the NOAPPEND option.)

list2: A list comprised of one or more labels from list1. The rows of the table are sorted on the data items in list2. list2 may not appear when the number of labels in list1 is greater than 8.
NOSUB=[0|1]: With NOSUB=0, label substitution will be performed for final estimates in table files. This is the default.
list3: A list comprised of one or more items that are permitted in list1. They follow option EXCLUDE_BY. Labels in list3 are called exclusion variables. If one or more of them have a non-zero value for a given data record, the row of the table corresponding to the data record will be excluded from the table file.
PARAFILE=filename: Weighted residuals are evaluated before the first $TABLE record. As of NONMEM 7.4, this computation is parallelized if parallelization is on when the first Table Step is implemented. PARAFILE=ON turns on parallelization for the weighted residuals. PARAFILE=OFF turns off parallelization. The PARAFILE option may be specified on any $TABLE record, but applies to all $TABLE records.
ESAMPLE=n1: n1 specifies the number of random samples used to calculate the Monte-Carlo diagnostics. Should be specified only on the first $TABLE record. Default is 300.
WRESCHOL (NM73): Use the Cholesky square root of the variance, rather than the eigenvalue square root, when computing weighted residuals. Should be specified only on the first $TABLE record.
SEED=n2: n2 specifies the starting seed for generating the Monte-Carlo diagnostics. Should be specified only on the first $TABLE record. Default is 11456.
CLOCKSEED=[0|1] (NM75): If CLOCKSEED=1 (default is 0), actual starting seed will be 10000*(seconds after midnight)+SEED.
RANMETHOD=[n|S|m]: n: the random number generator used for the Monte-Carlo simuations of weighted residual items. S: sobol sequence. m: the type of scrambling desired. See the description of RANMETHOD for $ESTIM. RANMETHOD should be specified only on the first $TABLE command. The RANMETHOD set in the $TABLE command does not propagate to $EST or $CHAIN.

Options PRINT, NOPRINT, HEADER, NOHEADER, NOLABEL, NOTITLE, FILE, FIRSTONLY, LASTONLY, FIRSTLASTONLY, FORWARD, NOFORWARD, APPEND, NOAPPEND, FORMAT, VARCALC apply to the individual $TABLE record. They must be specified for each table to which they apply.

PRINT: A printed table appears in the NONMEM output. This is the default.
NOPRINT: No printed table appears in the NONMEM output.
FILE=filename: The table is written to the given file in character form, e.g., ASCII or EBCDIC, according to the hardware platform. Filename may not contain embedded spaces. Filename may contain at most 71 characters. Default: No table file is output. Required with NOPRINT.
NOHEADER: Used only with the FILE option. No header lines are included in the table file.
ONEHEADER: Used only with the FILE option. Only the first line of the table is a header line.
ONEHEADERALL (NM74): Used only with the FILE option and FORWARD. Only the first line of the table file is a header line. May also be coded ONEHEADERPERFILE.
NOLABEL: Used only with the FILE option. Do not print column labels. It may be combined with ONEHEADER to print only the title at the beginning of each table.
NOTITLE: Used only with the FILE option. Do not print table titles. It may be combined with ONEHEADER to print only the column labels at the beginning of each table. NOLABEL NOTITLE is equivalent to NOHEADER.
FIRSTONLY: Only information corresponding to the first data record from each individual record appears in the table. May also be coded FIRSTRECORDONLY or FIRSTRECONLY.
LASTONLY: Only information corresponding to the last data record from each individual record appears in the table. May also be coded LASTRECORDONLY or LASTRECONLY.
FIRSTLASTONLY: Only information corresponding to the first and last data record from each individual record appears in the table.
NOFORWARD: Used only with the FILE option. When the table file is opened during a given (sub)problem, it is positioned at the start of the file. This is the default.
FORWARD: Used only with the FILE option. When a table file is opened during a given (sub)problem, it is forwarded to the end of the file. This allows a table file to accumulate tables from multiple subproblems and superproblems. Moreover, if in the same (sub)problem the $TABLE record is followed by a contiguous succession of additional $TABLE records having the same filename as the given record, then even though some of these additional records may have the NOFORWARD option, or have neither the NOFORWARD nor the FORWARD options, the FORWARD option will apply to each of the records in the succession.
APPEND: Items DV, PRED, RES, WRES appear automatically as the last 4 columns of the table. This is the default.
NOAPPEND: Requests that items DV, PRED, RES, WRES not appear automatically. When this is specified, the number of labels that may appear in the table can be as large as 12 (rather than 8) for a printed table, and as large as PDT=4 (rather than PDT) for a table file.
FORMAT=s: This option defines the delimiter and number format for table files. It affects table files until a different FORMAT is specified. s defines the delimiter [,|s(pace)|t(ab)] followed by a Fortran format specification. The default is s1PE11.4. There are many more options for FORMAT.

Alternately, use LFORMAT and/or RFORMAT.

LFORMAT=s: Specifies the format of the full label record of a table. Allows different formats for different columns. Sample: LFORMAT="(4X,A4,4(',',4X,A8))"
RFORMAT=s: Specifies the format of the full numeric record of a table. Allows different formats for different columns. Sample: RFORMAT="(F8.0,,4(',',1PE12.5))"

Multiple LFORMAT options and RFORMAT options may be present and will be concatenated. The format specifications are not checked by NMTRAN. If either is invalid, the run will fail in NONMEM. Use LFORMAT="NONE" or RFORMAT="NONE" to resume use of the default format in a subsequent problem.

IDFORMAT=s (NM75): By default the ID column has the same format as specified by FORMAT. IDFORMAT specifies the format for the ID column in table files. If an improper format is given, it defaults to that of FORMAT. Some examples:

IDFORMAT=I: Integer value, left adjusted in the field.
IDFORMAT=I6: Integer value, right adjusted in the first 6 characters of the field.
IDFORMAT=F6.1: Floating value, with single digit to the right of the decimal.

VARCALC=[0|1|2|3] (NM74,NM75): To report standard errors associated with etas (individual parameters) in the tables for user-defined variables, set $TABLE ...VARCALC=1. See setest.ctl in the examples directory. This appends an item named item_SE following each user-defined item in list1. In addition, full variances-covariances among all user-defined variables and PREDPP parameters will be outputted to file root.vpd. With NONMEM 7.5, file root.vpt is also created. This contains variance-covariances associated with thetas (or omegas and sigmas) as well as those associated with etas/individual parameters. To append the comparable total standard errors item_SE to tables, set $TABLE ...VARCALC=3. To only create the vpd and vpt files, and not report SE’s to the table, set VARCALC=2. VARCALC=0 requests neither SE’s nor vpd nor vpt, and is the default.
FIXEDETAS=(list) (NM74): Specified etas may be treated as if they are fixed effects when evaluating population diagnostics during the $TABLE step. This is particularly suitable for super-ID $LEVEL etas that span groups of subjects, as if they were a fixed effect when evaluating populations characteristics during the $TABLE step, such as PRED, CWRES, NPDE, etc. List is a number-list of etas. For example, FIXEDETAS=(3-6).
NPDTYPE=1: The strict stochastic (Monte Carlo) method over the data y domain as well as etas is implemented for NPD diagnostics.
NPDTYPE=0: An asymptotic assessment of the residual variability is used. This is the default.
INTERPTYPE=[0|1] (NM751): By default the interpolation for NPD/NPDE evaluations type is 0, that is, the nearest value in the quantile area is chosen, without interpolation. If INTERPTYPE=1, then an interpolation is performed using an inverseNORM linearized interpolator. In addition, for NPDE it will extrapolate quantile positions that are outside the Monte Carlo sampled range, allowing severe outliers to be less truncated.
UNCONDITIONAL: The Table Step is always implemented. This is the default.
CONDITIONAL: The Table Step is implemented only when the Estimation Step terminates successfully or is not implemented.
OMITTED: The Table Step is not implemented.

REFERENCES: Guide IV, section III.B.16; Guide V, section 9.5.1, 10.7.1

47 `$THETA`

MEANING: Gives initial estimates and bounds for thetas

CONTEXT: NM-TRAN Control Record

USAGE:

$THETA value1 [value2] [value3] ...
[(value)xn] ...
[label = value] ...
[NAMES (label ...)value ...]
[NUMBERPOINTS = n]
[ABORT|NOABORT|NOABORTFIRST]

SAMPLE:

$THETA (0,3) 2 FIXED (0,.6,1) 10 (-INF,-2.7,0) (37 FIXED)

DISCUSSION:

Gives initial estimates and bounds for elements of the THETA matrix. Thetas are numbered in the order in which they are defined.

OPTIONS:

Each value defines a theta and gives its initial estimate and bounds. A value has one of 4 forms:

init [FIXED]: Init is the initial estimate. If FIXED is used, the final parameter estimate is to be constrained to equal the initial parameter estimate.
([low,] init [,up] [FIXED]): Low and up are lower and upper bounds respectively. They are the boundaries for the minimization search. Commas are optional. If an upper bound is used, a lower bound must also be used (e.g., -INF; see below). The lower and upper bounds (or if just the lower bound is used, then just this bound) may be omitted. When FIXED is used, and a bound appears the bound must equal the initial estimate. FIXED is implied when all three values are equal. The lower bound can be -INF (i.e., -infinity), and the upper bound can be INF (i.e., +infinity). These are the defaults for lower and upper bounds. They are communicated to NONMEM as numeric values -1000000 and 1000000.
([low,] init [,up]) [FIXED]: This is just like the form described above except that if the FIXED attribute is used, the attribute occurs outside the parentheses, and then if moreover, a bound appears, the bound need not equal the initial estimate.
(low,,up): The commas are required. Because no initial estimate is given, a search for an initial estimate (the Initial Estimates Step) is undertaken by NONMEM. With NONMEM 7.4, when initial thetas are to be estimated, evaluations can now be done for FOCE and Laplace, not just for FO.
(value)xn: Any initial value or group of initial values may be enclosed in parentheses and followed by xn, which means to replicate the values within parentheses n times (“repeated value”). For example, the following two are equivalent:

$THETA 2 2 2 2 (0.001,0.1,1000) (0.001,0.1,1000) (0.001,0.1,1000)
(0.5 FIXED) (0.5 FIXED)

$THETA (2)x4 (0.001,0.1,1000)x3 (0.5 FIXED)x2

UNINT (NM75): UNINT is used during the Optimal Design Step to identify a theta as uninteresting. UNINT may be used anywhere that FIXED may be used.
label=value [FIXED] (NM75): This is a compact method of defining an element of theta, specifying its initial estimate, and specifying a symbolic subscript for this element of THETA. The symbolic subscript may be used for THETA in abbreviated code, and will also identify this element of THETA in the NONMEM output. (Only the first 9 characters of the label will appear). If new $THETA records change the ordering, the abbreviated code does not have to be changed.

For example, suppose the third element of THETA that is defined happens to be:

$THETA CL = (0.0,7.0)

The abbreviated code can use this symbolic subscript instead of the numeric subscript, e.g., TVCL=THETA(CL). The NONMEM report will describe the relationship, e.g., LABELS FOR THETAS THETA(3)=THETA(CL), and THETA(CL) rather than TH 3 will appear in the NONMEM report.

It is also possible to specify the label using the $ABBR REPLACE THETA(CL)=THETA(3) control record but the NONMEM report will not identify the relationship and will not generate the symbolic label THETA(CL) in the report. For dynamic, or implicit mapping of labels, such as for various occasions, these still need to be done via the $ABBR REPLACE record.

$THETA records must be placed ahead of any records that use the symbolic label. Therefore these records must be placed before $THETAI, $THETAR, and abbreviated code.

NAMES (label ...)value ... (NM75): A compact way of defining one or more thetas with labels and initial values. For example: $THETA NAMES(V1,CL,Q,V2) (0.0,7.0) (0.0,7.0) (0.0,7.0) 7.
NUMBERPOINTS=n: During NONMEM’s search for an initial estimate, a number of points will be examined. This number will be automatically determined by NONMEM, or it can be specified with this option. May also be coded NUMBERPTS, NUMPOINTS, NUMPTS.
ABORT: During the Initial Estimates step, NONMEM is to abort when PRED sets the error return code to 1. (The PRED error return code n is set by the statement EXIT n [k] in abbreviated code, or by the statement IERPRD=n in user-supplied code, or by PREDPP when it detects an error.) This is the default.
NOABORT: During the Initial Estimates step, NONMEM is simply to ignore values of the theta vector that result in PRED error return code 1. (Ordinarily the first value of the theta vector is never ignored.) These will not be feasible values for an initial estimate.
NOABORTFIRST: Same as NOABORT option, but also applies to the first value of the theta vector that is tried. It cannot be shortened; all characters must be coded. May be used with the NOABORT option, in which case the stronger condition (NOABORTFIRST) takes precedence.

REFERENCES: Guide IV, section III.B.9

48 `$THETAI`

MEANING: Gives Instructions for Transforming Initial Thetas

CONTEXT: NM-TRAN Control Record

USAGE:

$THETAI Fortran statements

SAMPLE:

$THI
THETA(1:NTHETA) = LOG(THETAI(1:NTHETA))
THETAP(1:NTHP) = LOG(THETAPI(1:NTHP))

THETA = LOG(THETA)

DISCUSSION:

The purpose of $THETAI is to transform the initial values in the $THETA and $THETAP records. The record name may also be coded as $THI.

In the above sample code, it is desired that the thetas by estimated within NONMEM in the log domain, but the user wants the convenience of inputting and outputting them in the natural domain, such as when performing linear MU referencing.

The $THETAI record will convert any initial thetas in a $THETA record, or thetas obtained from a chain file, but will not convert thetas from an MSF file. The variance to the theta priors will be appropriately converted when using $PRIOR NWPRI.

The assignment statements may be any Fortran 95 statements. They are copied unchanged to subroutine SUBROUTINE THETAISUB in FSUBS (also found in thetair.f90). They may include array assignment statements specifying the whole arrays or sections of arrays.

If the initial estimate for an element of theta is transformed, so is the upper and lower bounds for that theta, if any.

Arguments of the subroutine are as follows.

THETAI: Values of THETA specified on $THETA records. Input.
THETAPI: Values of THETA specified on $THETAP records (or, if the informative names are not used, thetas corresponding to priors, if any). Input.
THETA: New values of THETA. Output.
THETAP: New values of THETA’s for priors. Output.

Other reserved variables that may be used are as follows:

NTHETA: Number of thetas to be estimated.
NTHP: Number of theta priors.
NPROB IPROB: These can be tested in IF statements so that values may be assigned differently for different problems.

If the range is not specified, NONMEM to supply the range (which is by default NTHETA+NTHP).

When appropriate, for reporting thetas, the inverse function should be supplied, e.g., with the samples above:

$THR
THETAR(1:NTHETA) = EXP(THETA(1:NTHETA))
THETAPR(1:NTHP) = EXP(THETAP(1:NTHP))

or:

THETAR=EXP(THETA)

Note that the assignment occurs after the NONMEM control stream has been processed, so that errors in assignment of THETA’s are not found. E.g.

$THI
THETA = 0.

This will set all theta’s to 0, and there will be no specific error message from NONMEM, though most likely the run will fail.

If initial estimates of all or part of THETA are omitted, NONMEM performs a search for missing initial estimates as its first task. (These are printed on a separate page under the heading “INITIAL PARAMETER ESTIMATE”). This search occurs before the transformation by $THETAI.

Values of INITIAL ESTIMATE OF THETA in NONMEM output are those from the $THETA/$THETAP records. Values of THETA in the root.ext files are as set in $THI.

$THI may be used with $THR, but not necessarily.

Another example is rescaling thetas. E.g., suppose in CONTROL5:

$THETA (.1,3,5) (.008,.08,.5) (.004,.04,.9)

is replaced with:

$THETAI
THETA = THETAI / 10.
$THETA (1,30,50) (.08,.8,5) (.04,.4,9)

The results will be identical, except for the values of INITIAL ESTIMATE OF THETA in the NONMEM report. The values in .ext will not be affected.

REFERENCES: Guide Introduction_7

49 `$THETAP`, `$THETAPV`

MEANING: Gives prior information for thetas

CONTEXT: NM-TRAN Control Record

USAGE:

$THETAP value1 [value2] [value3] ...
$THETAPV value1 [value2] [value3] ...

SAMPLE:

; Prior information of THETAS (NTHP=4 of them)
$THETAP (2.0 FIX) (2.0 FIX) (2.0 FIX) (2.0 FIX)
; Variance to prior information of THETAS (NTHPxNTHP=4x4 of them).
$THETAPV BLOCK(4)
10000 FIX
0.00 10000
0.00 0.00 10000
0.00 0.00 0.0 10000

DISCUSSION:

These are called the informative forms of the $THETA record, for use with the NWPRI utility.

$THETAP gives prior information for elements of the THETA matrix. $THETAPV gives variance information for THETA priors.

The name of the record describes the kind of information it gives, rather than the structure of the information. E.g., in the example above, $THETAPV is implemented in FCON with an $OMEGA record because it is in general an array of values. These records may be located anywhere in the control stream. NM-TRAN inserts the corresponding records in the control stream in the correct order. When the informative forms are used, the options of $PRIOR NWPRI need not be specified. (See Section 59.12).

OPTIONS:

The option FIXED should be used. Other appropriate options are BLOCK and VALUES.

REFERENCES: Guide Introduction_7

50 `$THETAR`

MEANING: Gives Instructions for Transforming Final Thetas

CONTEXT: NM-TRAN Control Record

USAGE:

$THETAR Fortran statements

SAMPLE:

$THETAR
THETAR = EXP(THETA)

Or:

$THETAR

THETAR(1:NTHETA) = EXP(THETA(1:NTHETA))
THETAPR(1:NTHP) = EXP(THETAP(1:NTHP))

DISCUSSION:

The purpose of $THETAR is to transform the final theta values for the NONMEM report and additional output files. The record name may also be coded as $THR.

In the above sample code, it is assumed that $THETAI was used to transform thetas from the natural domain to the log domain for estimation within NONMEM, such as when performing linear MU referencing. $THETAR causes them to be output in the natural domain as well.

This affects the following data in the output report:

NPARAMETR
FINAL PARAMETER ESTIMATE for THETA.
FIRST ORDER STANDARD ERROR OF ESTIMATE
THETA - VECTOR OF FIXED EFFECTS PARAMETERS
FIRST ORDER COVARIANCE MATRIX OF ESTIMATE
THETA - VECTOR OF FIXED EFFECTS PARAMETERS

Contents of additional output files such as .coi and .cov and .cor are also affected.

The assignment statements may be any Fortran 95 statements. They are copied unchanged to subroutine SUBROUTINE THETARSUB in FSUBS (also found in thetair.f90).

They may include array assignment statements specifying the whole arrays or sections of arrays.

Arguments of the subroutine are as follows.

THETA: Final estimates of theta. Input.
THETAP: Final estimates of thetas specified on $THETAP records (or, if the informative names are not used, thetas corresponding to priors, if any). Input.
THETAR: New values of THETA. Output.
THETAPR: New values of THETA’s for priors. Output.

Other reserved variables that may be used are as follows:

NTHETA: Number of thetas to be estimated.
NTHP: Number of theta priors.
NPROB IPROB: These can be tested in IF statements so that values may be assigned differently for different problems.

If the range is not specified, NONMEM to supply the range (which is by default NTHETA+NTHP).

$THR may be used with $THI, but not necessarily.

Another example is rescaling thetas. E.g., suppose that:

$THETAI
THETA = THETAI / 10.

was used to rescale thetas on input.

Then:

$THETAR
THETAR = THETA * 10.

can be used to report them in the original domain.

REFERENCES: Guide Introduction_7

51 `$TOL`

MEANING: Marks the beginning of abbreviated code for the TOL routine

CONTEXT: NM-TRAN Control Record

USAGE:

$TOL
abbreviated code

DISCUSSION:

The $TOL record is used to specify compartment-specific NRD values. It is used with PREDPP’s general non-linear models (ADVAN6, ADVAN8, ADVAN9, ADVAN13, ADVAN14, ADVAN15, ADVAN16, ADVAN17, ADVAN18, and SS6 and SS9). NRD stands for “Number of Required Digits,” although the precise meaning depends on the particular ADVAN or SS routine that uses it.

$TOL cannot be present if the $SUBROUTINES record includes any of the corresponding options.

The following are equivalent:

$SUBROUTINES ... TOL = n

and:

$SUBROUTINES ...
$TOL NRD = n

Left-hand quantities:

These are identical to the left-hand variables that may be set in subroutine TOL. If subscript (I) is omitted, it defaults to 1.

NRD(I): The number of digits that are required to be accurate in the computation of the drug amount in compartment I, i.e., the relative tolerance. ADVAN 9, 13, 16, 17, and 18 have the capability of using different values of NRD for different compartments. For compartments not specified, the tolerance of the last compartment specified will be used.

However, all the other ADVAN routines requiring TOL take the relative tolerance to be the same for all compartments; NRD(I), I > 1, is ignored, and only NRD(1) is used. With NONMEM 7.4, NRD(0) is the relative tolerance for the Steady State computations. If NRD(0) is not specified, NRD(1) is used.

The value of NRD(1) can also be specified using $SUBROUTINES option TOL. The value of NRD(0) can also be specified using $SUBROUTINES option SSTOL.

ANRD(I) (NM74): The absolute tolerance in the computation of the drug amount in compartment I. The default is 12 (that is, accuracy is 10**(-12)). Used by ADVAN 9, 13, 14, and 15, 16, 17, and 18 which have the capability of using different values of ANRD for different compartments. For compartments not specified, the tolerance of the last compartment specified will be used.

ANRD(0) is the absolute tolerance for the Steady State computations. If ANRD(0) is not specified, ANRD(1) is used.

The value of ANRD(1) can also be specified using $SUBROUTINES option ATOL. The value of ANRD(0) can also be specified using $SUBROUTINES option SSATOL.

NRDC(I) (NM74): Same as NRD(I), but used for the FOCE/LAPLACE covariance step. Used with ADVAN 9, 13, 14, 15, 16, 17, and 18. If not set, NRDC defaults to the value of NRD. NRDC(0) is used for Steady State computations during the FOCE/LAPLACE covariance step.

The value of NRDC(1) can also be specified using $SUBROUTINES option TOLC. The value of NRDC(0) can also be specified using $SUBROUTINES option SSTOLC.

ANRDC(I) (NM74): Same as ANRD(I), but used for the FOCE/LAPLACE covariance step. Used with ADVAN 9, 13, 14, 15, 16, 17, 18. If not set, ANRDC defaults to the value of ANRD. ANRDC(0) is used for Steady State computations during the FOCE/LAPLACE covariance step.

The value of ANRDC(1) can also be specified using $SUBROUTINES option ATOLC. The value of ANRDC(0) can also be specified using $SUBROUTINES option SSATOLC.

Right-hand quantities: Integers, e.g., NRD(1)=4.

Forbidden Variable Names: All other variables.

RECORD ORDER: Follows $SUBROUTINES and $MODEL.

REFERENCES: Guide IV, section V.C.3, V.C.10; Guide VI, section VI.D, Figure 41

52 `$TTDF` (NM75)

MEANING: Specifies t-distribution degrees of freedom for theta

CONTEXT: NM-TRAN Control Record

USAGE:

$TTDF 0 (default)
$TTDF [value ...]
$TTDF [(value)[xn]] ...

SAMPLE:

$TTDF (2.0)x2 (3.0)x2

sets t-distribution degrees of freedom for thetas 1 and 2 to value of 2, and degrees of freedom for thetas 3 and 4 to value of 3.0.

DISCUSSION:

The ttdf is a separate record that allows the user to specify the t-distribution degrees of freedom for each theta. It can be used with $ESTIMATION METHOD=NUTS, and with $SIMULATION. By default $TTDF value is 0. These values will be used in estimation and simulation unless $EST TTDF or $SIM TTDF is set, respectively, which set the t degrees of freedom to a single TTDF value for all thetas for that step.

REFERENCES: Guide IV, section V.C.3, V.C.10; Guide VI, section VI.D, Figure 41

53 `$WARNINGS`

MEANING: Control Display of NM-TRAN Warning, Data Warning and Data Error messages

CONTEXT: NM-TRAN Control Record

USAGE:

$WARNINGS [NONE] [n] [RESET | NORESET]
[WARNINGMAXIMUM = [NONE | n | (list)]]
[DATAMAXIMUM = [NONE | n | (list)]]
[ERRORMAXIMUM = n]

SAMPLE:

$WARNING WMAX = 1,EMAX = 9999

DISCUSSION:

Optional. Controls the display of NM-TRAN warning messages and data error messages in the current and all subsequent problems until another $WARNING record appears. May appear anywhere in the control stream following $SIZES, $SUPER (if present) and $PROBLEM records, but cannot affect the display of warning messages associated with the records that precede it.

OPTIONS:

NONE: Suppress all warning messages.
n: Sets WARNINGMAXIMUM=n, ERRORMAXIMUM=n, DATAMAXIMUM=n. May be 0, in which case it is the same as NONE.
LIST: Print a list of all possible warning messages. When this option is present, the control stream must consist only of the single record:

$WARNING LIST

WARNINGMAXIMUM: Refers to general (non-data) warning messages. May also be coded WARNMAXIMUM and shorter substrings, e.g., WMAX, WARN. May appear more than once, with cumulative effect.
WARNINGMAXIMUM=NONE: Suppress warning messages.
WARNINGMAXIMUM=n: Each type of warning message will be displayed no more than n times (n >= 0). The default is 20.
WARNINGMAXIMUM=(list): The list is a series of integers n1, n2, n3 … (ni >= 0). ni gives the the maximum number for the ith type of warning message.

NONE may coded for any ni if it is the last in the list. Sets the maximum number of messages for the ith and all higher-numbered messages to zero.

Example:

$WARNING WMAX = 1

Sets the maximum for all non-data messages to 1.

DATAMAXIMUM: Refers to data warning messages. May also be coded DMAXIMUM and shorter substrings, e.g. DMAX, DATA. May appear more than once, with cumulative effect. Forms and default are identical to those for the WARNINGMAXIMUM option.
ERRORMAXIMUM=n: Refers to data error messages. It can also be coded ERRMAXIMUM or EMAXIMUM, and shorter strings, e.g., EMAX. Each type of data error message will be displayed no more than n times (n >= 0). The default is 20. Data error messages can never be totally suppressed. With n = 0 and n = 1, NM-TRAN displays the first data error message and then terminates.

Example:

$WARNING EMAX = 99999

Sets the maximum number of data error messages displayed from 20 to a much higher value, so that NM-TRAN will not terminate until all data error conditions have been identified.

RESET: All counts reset to 0 with each new problem. This is the default.
NORESET: Counts of how many times a given message has been displayed are accumulated over problems. (A new $WARNING record always resets all counters, but they will not be automatically reset again with subsequent problems.)

A $WARNING record with no options re-establishes all default conditions as if no $WARNING records had been present.

REFERENCES: None.

54 FORMAT

MEANING: Specifies the format for table files and other files

CONTEXT: Options of NM-TRAN control file records

USAGE:

FORMAT and related options may be used with the following control records:

$TABLE [FORMAT = s1PE11.4(default)][LFORMAT = s][RFORMAT = s][IDFORMAT = s]

Specifies the format for writing to the output table file.

$ESTIMATION [FORMAT = s1PE12.5 (default)] [DELIM = s]

Specifies the format for writing to the raw output files.

$COVAR [FORMAT = s1PE12.5(default)] [DELIM = s]

Specifies the format for writing to the raw output files

$CHAIN [FORMAT = s1PE12.5 (default)] [DELIM = s]

Specifies the format for writing to the raw output files

$RCOV [FORMAT = s] [DELIM = s]

Specifies the format for reading from the input file root.cov

$RCOVI [FORMAT = s] [DELIM = s]

Specifies the format for reading from the input file root.coi

$ETAS [FORMAT = s] [DELIM = s]

Specifies the format for reading from the input file root.eta

$PHIS [FORMAT = s] [DELIM = s]

Specifies the format for reading from the input file root.phi

DISCUSSION:

FORMAT=s1PE12.5

s defines the delimiter [,|s(pace)|t(ab)] followed by a Fortran format specification. The FORMAT option is case-insensitive.

Default for $TABLE: FORMAT=s1PE11.4
Default for $ESTIMATION, $COVAR, $CHAIN:
- With versions of NONMEM 7.5 and higher: FORMAT=s1PE12.5
- With versions of NONMEM before 7.5: FORMAT=s1PE11.4

As with previous versions: The first character defines the delimiter. Delimiters are not a part of the Fortran language. The delimiter is stripped from the Fortran format specification, and then used by NONMEM to modify the file being generated. The delimiter may be s for space, t for tab, or the comma. A comma produces a comma delimited file with aligned fields (so, padded with spaces). The delimiters may be upper or lower case.

New to NONMEM 7.5: There are two new delimiters. c for comma delimited file with no spaces, or q for comma delimited file with no spaces and double quotes around column names that have commas (such as "OMEGA(2,1)").

The list of delimiters is now as follows.

s means space
t means tab
, means comma
c means comma, and spaces removed
q means comma. Spaces removed, and quotes around entries that need them.

Two new formats are permitted, which provide both delimiter and number format:

FORMAT=QCSV is equivalent to FORMAT=q1PG23.16
FORMAT=CSV is equivalent to FORMAT=c1PG23.16

May be terminated with line length (e.g., FORMAT=s1PE15.8:160), line length with continuation marker for the end of each line (e.g., FORMAT=s1PE15.8:160c), and continuation marker for start of each continued line (e.g. FORMAT=s1PE15.8:160cx). If “c” is the letter s, it stands for “space”. If “c” is the character &, (e.g., FORMAT=s1PE15.8:160&) and & is the last character on the line, it must be followed by “;” (e.g., FORMAT=s1PE15.8:160&;).

If the user-defined format is inappropriate for a particular number, then NONMEM uses the default format for that number.

Most of the numeric formats are similar to those of Fortran, but there are exceptions.

The syntax for the number format is Fortran based, as follows:

For E field: xPEw.d indicates

w total characters to be occupied by the number (including decimal point, sign, digits, E specifier, and 2 digit magnitude),
d digits to the right of the decimal point, and
x digits to the left of the decimal point.

Examples:

E12.5: -0.12345E+02
2PE13.6: -12.12345E+02

If you are outputting numbers that are less than 1.0E-99, such as 1.2236E-102, NONMEM changes how the number is displayed. With format 1PE12.4, Fortran would delete the “E” and display the number as 1.2236-102. NONMEM retains the “E” and displays one fewer significant digit to make room for the extra digit in the exponent. The final digit is truncated (no rounding), as follows:

1PE12.4: 1.223E-102

To make room for a three digit exponent, you may set the format as follows:

xPEw.dEe

where e is the number of digits to be provided for the exponent. For example

1PE12.4E3: 1.2236E-102

Another example of this format:

1PE12.4E3: -2.3456E+002

For F field: Fw.d indicates

w total characters to be occupied by the number (including decimal point, sign and digits),
d digits to the right of the decimal point.

Examples:

F10.3: -0.012
F10.3: 234567.123

For G field: xPGw.d

For numbers >=0.1, will print an F field number if the value fits into w places showing d digits, otherwise will resort to xPEw.d format.
For numbers <0.1, will always use xPEw.d format.

OPTIONS:

IDFORMAT=s1PE11.4 (NM75): This specifies the format for the ID column. By default the ID column has the same format as specified by FORMAT. However, sometimes you wish the ID to appear as an integer, in which case, you may set IDFORMAT as I. Do not include the delimiter.

Some examples:

IDFORMAT=I Integer value, left adjusted in the field.
IDFORMAT=I6 Integer value, right adjusted in the first 6 characters of the field
IDFORMAT=F6.1 Floating value, with single digit to the right of the decimal.

If an improper format is given, it defaults to that of FORMAT.

LFORMAT=s RFORMAT=s: An alternative format description to FORMAT is RFORMAT and LFORMAT.

(where R=real numbers) describes the full numeric record of a table, so that formats for specific columns may be specified.

LFORMAT (where L=label) specifies the format of the full label record of a table.

The formats must be enclosed in double quotes, and (), and have valid Fortran format specifiers. The RFORMAT and LFORMAT options can be repeated if the format specification is longer than 80 characters. Multiple RFORMAT and LFORMAT entries will be concatenated to form a single format record specification. For example,

LFORMAT="(4X,A4,4(',',4X,A8))"
RFORMAT="(F8.0,"
RFORMAT="4(',',1PE12.5))"

Will result in the following formats submitted to a Fortran write statement:

LFORMAT=(4X,A4,4(',',4X,A8))

for the table’s label record, and

RFORMAT=(F8.0,4(',',1PE12.5))

For the table’s numeric records.

If RFORMAT and LFORMAT are given, then the FORMAT option will be ignored. By default, FORMAT, RFORMAT, LFORMAT specifications will be passed on to the next $TABLE record in a given problem unless new ones are given. To turn off an RFORMAT/LFORMAT specification in a subsequent table (and therefore use FORMAT instead), set

LFORMAT="NONE"
RFORMAT="NONE"

Here is an example of $TABLE statements designated in a control stream file:

$TABLE ID TIME PRED RES WRES CPRED CWRES EPRED ERES EWRES NOAPPEND ONEHEAD
FILE = tabstuff.TAB NOPRINT,FORMAT=,1PE15.8

$TABLE ID CL V1 Q V2 FIRSTONLY NOAPPEND NOPRINT FILE = tabstuff.PAR
LFORMAT = "(4X,A4,4(',',4X,A8))"
RFORMAT = "(F8.0,"
RFORMAT = "4(',',1PE12.5))"

$TABLE ID ETA1 ETA2 ETA3 ETA4 FIRSTONLY NOAPPEND NOPRINT
FILE = tabstuff.ETA,FORMAT=";F12.4"
LFORMAT = "NONE"
RFORMAT = "NONE"

There is no NMTRAN error checking on the RFORMAT and LFORMAT records, so the user must engage in trial and error to obtain a satisfactory table output (you should set MAXEVAL=0 or MAXEVAL=1 for the $EST step to do a quick check, so you don’t spend hours on estimation only to find the RFORMAT/LFORMAT were not appropriate). The $MSFO option of the $ESTIMATION record should be used to produce a Model Specification File. Such a file can be used via $MSFI record.

A word of caution. The FORMAT descriptor 1P, which means move the decimal point to the left by 1, will be in effect for all remaining FORMAT components. For example, in

RFORMAT="(F8.0,37(',',1PE13.6),24(',',F7.2))"

the F field format that follows an E field format, in which 1P was used, will also have the decimal placed to the left, and a 1.00 would appear as a 10.00. To prevent this from occurring, revert to no decimal shift with 0P:

RFORMAT="(F8.0,37(',',1PE13.6),24(',',0PF7.2))"

See INTRODUCTION TO NONMEM 7, $EST: Format of Raw Output File

See INTRODUCTION TO NONMEM 7, IDFORMAT= I

See INTRODUCTION TO NONMEM 7, LFORMAT, RFORMAT

REFERENCES: Guide Introduction_7

55 INCLUDE

MEANING: Causes NM-TRAN to read control stream records from a different file.

CONTEXT: NM-TRAN Control Record

USAGE:

INCLUDE filename [ n ]

SAMPLE:

INCLUDE datadef

DISCUSSION:

This record causes NM-TRAN to read control stream records from a different file. The record must start with the characters INCLUDE or include. $INCLUDE and $include are also recognized.

OPTIONS:

filename: Name of the file to be read. Required. Filename may not contain embedded spaces. If it contains commas, semicolons, or parentheses, then it must be surrounded by single quotes ' or double quotes ". Filename may also contain equal signs if it is enclosed in quotes.
n: Optional. The number of copies of the file. Default is 1.

NMTRAN opens the named file and reads it to end-of-file. The contents of the file may be any portion of an NM-TRAN control stream, e.g., control records and/or abbreviated code. After reaching end-of-file, if the number of copies is greater than 1, NM-TRAN rewinds the file and re-reads it the specified number of times. After reaching end-of-file on the final (or only) copy, NMTRAN resumes reading the original control stream after the include record.

There may be more than one include record anywhere in the control stream, but they may not be nested. That is, an included file may not contain include records.

If an error is detected in the NMTRAN input, the line number displayed is cumulative. The number of the line in the included file is added to the number of lines already read from the control stream and any previous include files, as if the included file(s) are physically part of the control stream.

EXAMPLE:

   $PROBLEM model A with data set 3
   include data3def
   include modela
   $THETA 1.3 4
   $OMEGA .04
   $SIGMA 1
   $ESTIMATION

The file data3def contains the $INPUT and $DATA statements. The file modela contains the $SUBROUTINE statement, $PK block, and $ERROR block.

Verbatim comment lines may be present in an included file. If the character that immediately follows the initial " is !, this conforms to the FORTRAN 90 syntax for comment lines. The line is copied unchanged. If the character that immediately follows the initial " is C or c or " or *, this conforms to the FORTRAN 77 syntax for comment lines. The line is copied unchanged, but C or c or " or * is replaced by !.

REFERENCES: None.

56 ORDER_OPTION

MEANING: Instructions for the NONMEM Estimation Step

CONTEXT: NM-TRAN Control Record

ORDER is an option of the $ESTIMATION record:

ORDER=xxxf: The values of x may be T (Theta), S (Sigma), and O (Order). The value of f may be U (Upper) or L (Lower). Affects the way theta, omega, and sigma are displayed in the raw and additional output files. xxx gives the overall order, and f gives the order within OMEGA and SIGMA. Affects the raw output file and all additional output files. The default is TSOL: THETA, SIGMA, OMEGA in Lower triangular form. Does not affect the NONMEM report file.

DISCUSSION:

On the $OMEGA record, elements of Omega are given in lower triangular order, e.g.,

`$OMEGA` BLOCK(3) OM11 OM21 OM22 OM31 O32 OM33

This can also be coded as

`$OMEGA` BLOCK(3)
OM11
OM21 OM22
OM31 O32 OM33

The NONMEM report file is not consistent. The initial and final parameter estimates are printed in Lower triangular order, e.g.,

INITIAL ESTIMATE OF `OMEGA`:
OM11
OM21 OM22
OM31 OM32 OM33

However, in the intermediate printout of the Estimation step, OMEGA and SIGMA are in Upper triangular order. This was not evident with previous version of NONMEM, because the PARAMTER values corresponding to OMEGA and SIGMA are displayed as unconstrained parameters (UCP), and these are not in a 1-1 mapping with the elements of OMEGA and SIGMA. But with NONMEM 7.2 and higher, the intermediate output of the Estimation step includes a line NPARAMETR, in which OMEGA and SIGMA are converted to their “natural” space. E.g.,

OM11 OM12 OM13 OM22 OM23 OM33

Because OMEGA is symmetric, this is the same as

OM11 OM21 OM31 OM22 OM32 OM33

In the NONMEM report, upper triangular form is used for all of the “COVARIANCE MATRIX OF THE ESTIMATE”, “CORRELATION MATRIX OF ESTIMATE” and the “INVERSE COVARIANCE MATRIX OF ESTIMATE”. E.g.,

OM11 OM12 OM13 OM22 OM23 OM33

This is TOSU order.

Case 1. ORDER is not used (Default). The raw output file .ext and additional output files .cov, etc, are in a different order: TSOL. SIGMA precedes OMEGA. The order within OMEGA is lower triangular, consistent with the Initial and final estimates of OMEGA, but different than the intermediate output in the NONMEM report. The order of the last line of the “COVARIANCE MATRIX OF ESTIMATE” in the NONMEM report differs from the order of the lines of the .cov file, and similarly for .cor and .coi.

Case 2. ORDER=TOSU. Each line of the raw output file .ext is in the same order as in the intermediate output portion of the NONMEM report. Also, each line of the .cov file is in the same order as the last line of the “COVARIANCE MATRIX OF ESTIMATE” in the NONMEM report, and similarly for .cor and .coi.

Note that the ORDER option does not affect the NONMEM report file, only the raw and additional output files. The SIGMA matrix always printed in the same order as OMEGA, and the ORDER option applies to it as well.

REFERENCES: Guide Introduction_7

1 $ABBREVIATED

2 $AES

3 $AESINITIAL

4 $ANNEAL

5 $BIND

6 $CHAIN

7 $CONTR

8 $COVARIANCE, $COVR

8.1 SIRMAXWT=x (NM75)

9 $DATA

10 $DEFAULT

11 $DES

12 $DESIGN (NM75)

13 $ERROR

14 $ESTIMATION RECORD OPTIONS

15 $ESTIMATION, $ESTM

16 $ETAS, $PHIS

17 $FORMAT

18 $INDEX, $INDXS

19 $INFN

20 $INPUT

21 $LDFOLD

22 $LEVEL

23 $MIX

24 $MODEL

25 $MSFI

26 $NONPARAMETRIC

27 $OLKJDF

28 $OMEGA

29 $OMEGAP, $OMEGAPD

30 $OMIT

31 $OVARF

32 $PK

33 $PRED

34 $PRIOR

35 $PROBLEM

36 $RCOV, $RCOVI

37 $SCATTERPLOT

38 $SIGMA

39 $SIGMAP, $SIGMAPD

40 $SIMULATION

41 $SIZES

42 $SLKJDF

43 $SUBROUTINES

44 $SUPER

45 $SVARF

46 $TABLE

47 $THETA

48 $THETAI

49 $THETAP, $THETAPV

50 $THETAR

51 $TOL

52 $TTDF (NM75)

53 $WARNINGS

54 FORMAT

55 INCLUDE

56 ORDER_OPTION

1 `$ABBREVIATED`

2 `$AES`

3 `$AESINITIAL`

4 `$ANNEAL`

5 `$BIND`

6 `$CHAIN`

7 `$CONTR`

8 `$COVARIANCE`, `$COVR`

9 `$DATA`

10 `$DEFAULT`

11 `$DES`

12 `$DESIGN` (NM75)

13 `$ERROR`

14 `$ESTIMATION` RECORD OPTIONS

15 `$ESTIMATION`, `$ESTM`

16 `$ETAS`, `$PHIS`

17 `$FORMAT`

18 `$INDEX`, `$INDXS`

19 `$INFN`

20 `$INPUT`

21 `$LDFOLD`

22 `$LEVEL`

23 `$MIX`

24 `$MODEL`

25 `$MSFI`

26 `$NONPARAMETRIC`

27 `$OLKJDF`

28 `$OMEGA`

29 `$OMEGAP`, `$OMEGAPD`

30 `$OMIT`

31 `$OVARF`

32 `$PK`

33 `$PRED`

34 `$PRIOR`

35 `$PROBLEM`

36 `$RCOV`, `$RCOVI`

37 `$SCATTERPLOT`

38 `$SIGMA`

39 `$SIGMAP`, `$SIGMAPD`

40 `$SIMULATION`

41 `$SIZES`

42 `$SLKJDF`

43 `$SUBROUTINES`

44 `$SUPER`

45 `$SVARF`

46 `$TABLE`

47 `$THETA`

48 `$THETAI`

49 `$THETAP`, `$THETAPV`

50 `$THETAR`

51 `$TOL`

52 `$TTDF` (NM75)

53 `$WARNINGS`