127 NM-TRAN Control Records

Generated from nmhelp plain-text source files (*.ctl) of the NONMEM 7.6.0 distribution. These mirror the content presented by nmhelp and complement the formatted Part VIII Help Guide.

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:

$ABBREVIATED    COMRES=2

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 copying block). 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 Partial Derivative Indicators).

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.EQ.1) F1=1 IF(DOSN.EQ.2) F1=1EXP(ETA(2)) IF(DOSN.EQ.3) F1=1EXP(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 rightside 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 dowhile block).

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

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

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 bivariate function). 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 $AESINITIAL). General rules for abbreviated code are documented elsewhere (See abbreviated code). 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 Variables_in_Modules) 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 aes, advan9_15, 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 $AES). General rules for abbreviated code are documented elsewhere (See abbreviated code). 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 Variables_in_modules)

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

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

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.EQ.0) THEN
XB=X
ELSE
XB=DOSREC(X)
ENDIF

NEXT:

XB=X

LAST:

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

In this case, when DOSTIM>0, XB retains its value from the previous
call to PK.

(See bind example).

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 $ESTIMATION_record_options). (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 sizes).

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 sup -1 S R sup -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 .5R. S: print the matrix .25S. 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. 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 $ESTIMATION). 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 variancecovariance 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 VarianceCovariance 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)

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 format). 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 Vsquare_root(eigenvalue). If you set PRETYPE=1, then the corrector is Vsquare_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 Rmatrix 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 (see IGNORE list and ACCEPT list), 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. The same total applies to these dropped record. See PRED_IGNORE_DATA, below. 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 (at the place where the file is positioned before data records are read; see the NOREWIND option), and to include as well, those and only those subsequent contiguous data records having the same value of the data item as does the first record. It counts the total number of these data records, minus any comment or dropped records, and puts this number in the NONMEM control file. 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. If the data are single-subject data, the ID data items used to determine the data records for the problem are those labeled ID (not .ID.). If there is more than one problem specification with a $DATA record that includes an option of the form RECORDS=label, then either none of these $DATA records may also include a format specification, or all of them must include the same format specification. (See records=id).

LRECL=n2

The number of characters in a logical record. Needed for certain operating systems (e.g., IBM/CMS).

IGNORE=c1

[Note: The following two options, IGNORE and ACCEPT allow the user to drop records from the NM-TRAN data set prior to the run. With NONMEM 7.5, it is also possible to drop records from the NONMEM data set using abbreviated code, which is more flexible than the criteria that can be specified in the $DATA record. See PRED_IGNORE_DATA, below.] Specifies that any data record having the character c1 in column 1 should be ignored, i.e., these records are not included in the NONMEM data set. This allows comment records to be included in the NM-TRAN data set. In general, records having the character c1 in column 1 will be called “comment records”. Also permitted: IGNORE=‘c’ or IGNORE="c", where c may be any character except space. IGNORE=# is the default. That is, in the absence of IGNORE option, any record whose first character is # is treated as a comment record. IGNORE=@ signifies that any data record having an alphabetic character or @ as its first non-blank character (not just in column 1) should be ignored. Alphabetic characters are the letters A-Z and a-z. 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.) Thus, the following are identical: “label=value”,“label==value”,“label.EQ.value”. With NONMEM 7.3, “label.NEN.value” and “label.EQN.value” are permitted. (There is no Fortran 90 operator for this comparison.) If the logical operator is omitted, the default is “=”. With each data record, the value of the data item with the given label and the value in the list are compared according to the logical operator, and if result is “true”, the record is ignored, i.e. it is not included in the NONMEM data set (see example below). Such records are called “dropped records”. With “=”, “==”, “/=’,”.EQ.” and “.NE.”, the value in the data record and the value in the list are compared as character strings. Otherwise, they are converted to numeric and compared numerically. (This is the case with .NEN. and .EQN.) This comparison is made prior to time translation. Hence, the TIME item cannot be compared numerically if it contains non-numeric characters such as “:”. Note: if the data file is a table file from a previous NONMEM run, values that had been integers (0,1,..) in the original data file will be real values (0.0000E+00, 1.0000E+00, …) in the table file. A comparison for equality or inequality should now be for the real value. E.g. IGNORE=(OCC==1.0000E+00). With NONMEM 7 the default format for the table file is PE11.4, as in the examples above. The FORMAT option of $TABLE may be used to change this and the values used in a subsequent IGNORE will have to be changed accordingly. The .NEN. and .EQN. operators that are described above will always work. A data item label along with a logical operator and value is called a condition. A list may contain several conditions; these should be separated by commas, and the list should be enclosed in parentheses. Up to 100 different conditions altogether can be specified. IGNORE=(list) may be used with IGNORE=c, where c is a character. Multiple IGNORE options with different lists may be used. A list may span one or more NM-TRAN records. The use of “=” after IGNORE is optional, but parentheses are required with this form of IGNORE. Values may be alphabetic or numeric, and may optionally be surrounded by single quotes ’ or double quotes “. Quotes are required if a value contains special characters such as =. However, a value may not contain spaces or commas. No format specification is permitted with this form of IGNORE. A data item type may be dropped from the NONMEM data set by means of the DROP or SKIP synonym on the $INPUT record, after records are dropped due to a condition based on the data item type. E.g., $INPUT … GEN=SKIP … $DATA file IGNORE=(GEN=‘M’) Records having GEN equal to ‘M’ will be dropped, and the GEN data item type will then be omitted from the NONMEM data set. A dropped data item may be any alphanumeric string (without a data item delimiter - a blank or a comma). If there is more than one condition, then records satisfying at least one of these conditions will be dropped. In effect, the conditions for dropping a record are connected by the implied conjunction “.OR.”. E.g. IGNORE=(GEN.EQ.1,AGE.GT.60). Records having GEN equal to 1 or AGE greater than 60 are dropped. All others are accepted.

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. However, it may be used with IGNORE=c, where c is a character. 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. Suppose it is desired that records be dropped that satisfy the logical “.AND.” of several conditions. This can be implemented by using an ACCEPT list with the negations of the conditions. For example, suppose that records to be ignored are those having GEN=1 .AND. AGE > 60. This may be done as follows: ACCEPT=(GEN.NE.1,AGE.LE.60)

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. The explicit option is needed if the use of the PRED_IGNORE_DATA variables occurs in user-written or verbatim code, so that NMTRAN is unaware of it. (See Guide Introduction_7 “Extension to $DATA IGNORE=st filtering”)

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=.. Null data items consist of a single dot (.) or consecutive commas or consecutive tab characters. c2 may be any character except space (” “) or semicolon (”;“). Also permitted: NULL=‘c’ or NULL="c", where c may be any character. 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. Space between adjacent columns may be suppressed and multi-line records may be generated. This is the default.

WIDE Requests that FDATA contain single-line records, and that at

least one space separate columns. (Records in FDATA will never be wider than 300 characters.) With this option, there will be no FINISH (FIN) record in the NONMEM data set.

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. The options REWIND and NOREWIND apply only with a $DATA record in a subsequent problem specification, and only when the file named on the record is the same as that specified for the previous problem. When the file named on the record is different from that specified for the previous problem, the file is (re)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. (Whether the file input to NONMEM itself will be repositioned depends on whether this file is FDATA or is one named in the $DATA record; see NONMEM Users Guide, Part IV for a complete explanation.) NOREWIND: Leave the file at its current position so that the next NM-TRAN data set in the file is used. The $DATA record with the previous problem specification must have included the RECORDS option (or a FINISH record must have terminated the data set used in the previous problem), so that NM-TRAN did not read to a physical end-of-file. This is the default.

CHECKOUT

Requests that NONMEM implement the data checkout mode, in which the PRED routine is not called and predictions, residuals, weighted residuals and the objective function are not computed. May also be coded CHECKDATA. No tasks other than $TABLE or $SCAT can be specified. With NONMEM 7.5, an additional file, FDATA.csv is produced that outputs the contents of its input data file (typically FDATA) in a comma delimited file format, so you can check how NONMEM inter-prets the input data. If the REPL option of $DATA or the REPL_ data item is used, the replicated form of the data will appear in FDATA.csv.

NOOPEN

NM-TRAN will not open the named data file. This permits the data file to be created by one problem and used in a subsequent problem of the same run. May not be used with options IGNORE, DROP, or when data items ID, MDV, or EVID must be generated by NM-TRAN. With NOOPEN, a format specification is required. No day-time translation takes place.

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. E.g,. suppose LAST20=50. Then two digit years are interpreted as follows: 00-50 = 2000-2050 51-99 = 1951-1999 LAST20=-1 can be used when two digit years span the year 2051. All two digit years will be assumed to be in the same century. If year is recorded with four digits, it is always processed correctly and the value of LAST20 is of no consequence.

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. If F is a real number, the translated value in FDATA will have the same number of digits after the decimal point. If F is an integer and D is omitted, there will be 2 digits. Alternately, the number of digits may be specified explicitly by D (“digits”). If D is a real number, it is truncated to integer. If D is specified as 0, it defaults to 2. The maximum value of D is 12. The number of digits that may be requested in F is limited by the precision of the computer.

For example, either of the following can be used to request  values of TIME in FDATA that have 4 digits to the right of the decimal point:
TIME/1.0000
TIME/1/4

Another example is II/0.01/6 which divides II values by 0.01, and writes 6 digits to the right of the decimal point. If F is specified as “24” (or 24.0..), the options involving TIME (II) can be used to convert the units of time (of the steadystate interval) from hours to days. The TIME (II) data item is first processed as if the option were not present. Then the resulting value is divided by F. Note: The value of TIME is divided by F, whether or not day-time translation occurs (i.e., whether or not relative times are being computed by NM-TRAN). Similarly, the value of II is divided by F whether or not “:” appears in any II data value.

BLANKOK

Specifies that blank lines are permitted in the NM-TRAN data set. With all versions prior to NONMEM VI 2.0 a blank line was permitted, and was copied to the NONMEM data set. A warning message was issued. With later versions, NM-TRAN stops with an error message when there is a blank line in the NM-TRAN data set. Option BLANKOK restores the previous behavior. There is no abbreviation. 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. Example: $DATA mydatafile MISDAT=1.0E-99 MISDAT=1.0E-102.

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 to create an expanded NONMEM data set. (Note that the NONMEM data set is typically the file FDATA generated by NM-TRAN. If there is nothing for NM-TRAN to change and the format is supplied on the $DATA record, the file named on the $DATA record is the NONMEM data set. See NONMEM Users Guide, Part IV.) The REPL option may be used with the REPL_ data item. If both are used the REPL_ data item applies first, and the REPL option applies second. See REPL_ data item. The REPL option and REPL_ data item are meant to be used with $SIMULATION or $DESIGN. For important information, see Guide Introduction_7 Section “$DATA REPL”. (See Guide Introduction_7 “Extension to $DATA IGNORE=st filtering”)

NOFDATACSV (NM760)

An additional file, FDATA.csv is produced that outputs the contents of its input data file (typically FDATA) in a comma input data. The records in FDATA.csv may differ from those in FDATA in the following cases. If REPL/REPL_ is used, the replicated form of the data will appear in FDATA.csv. Also, records excluded by PRED_IGNORE_DATA will not be present in FDATA.csv. The creation of FDATA.csv can cause a long period of data file loading and processing at the beginning of a run, if the FDATA file is very large (such as >1 MB). As of nm760, the creation of this file can be prevented by adding the option NOFDATACSV on the $DATA record.

Another change in NONMEM VI 2.0 is that tab characters (and other characters that are smaller than blank in the computer’s collating sequence, such as carriage return ^M) are permitted in NM-TRAN input files. In the NM-TRAN data set they are treated like commas, i.e., as field delimiters. In the NM-TRAN control stream they are converted to spaces. They are left unchanged in verbatim code. With NONMEM 7, the last non-blank character on the line is replaced by a space if it is a low-value character.

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 (i.e., hours:minutes). With NONMEM 7.3, values may also have the form hh:mm:ss (i.e., hours:minutes:seconds). (See Guide IV, section II.C.2)

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 $ABBREVIATED). With NOSUB=1, label substitution will not be performed. With NOSUB=-1, revert to NONMEM default, which is to treat -1 as a 0. 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. When speficied on a $EST record, the usual rule for options apply, in which the option varies carries into the next $EST record in the problem unless otherwise re-specified.

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). General rules for abbreviated code are documented elsewhere (See abbreviated code). Specific rules follow.

ASSIGNMENT AND CONDITIONAL STATEMENTS

Left-hand quantities in assignment statements:

DADT(1), DADT(2), … (Required. Derivative of each compartment amount with respect to time.)

It is important to note that PREDPP itself adds in the rates for any infusions that may be active. It is possible to introduce endogenous drug into a compartment by explicit terms in a differential equation, rather than by PREDPP dose event records. Drug introduced in this manner is not included by PREDPP in the computation of the output compartment.

DES-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 explicit basic PK parameters; may be random variables.)

PK-defined items (Post-translation implicit basic PK parameters; may be random variables.)

T (Time; may be random variable. T takes values continuously over an integration interval.) (Note that T may take values that are larger than the ending time of the interval.)

DES-defined items that appeared earlier as left-hand quantities in $DES.

Data item labels specified on the $INPUT statement may be used explicitly in DES and $DES abbbreviated code (rather than obtained as PK parameters). This may improve run time. As with $PK, values are those of the current event record (the event record to which the system is being advanced).

THETA(n).

Fortran functions that are continuous, such as SIN and COS, may be used. The INT, MOD, and ABS functions (or other functions that introduce a discontinuity) should not be used in the $DES block. Instead, use model event times MTIME in the $PK block, and either set flag variables in $PK that can be tested in $DES, or use MPAST in the $DES block. See Appendix 3 of Guide VI PREDPP. Several examples are available for the use of MTIME with $DES. (See mtime, model time examples). (See Examples Using MTIME to Model Periodic Discontinuities in $DES). See step_circexa.ctl in the NONMEM examples directory. See idr_circexa.ctl in the NONMEM examples directory.

Global Variables in Modules Certain variables in FORTRAN Modules can be used. (See Variables_in_Modules) 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 $DES may test DOSTIM. It may use DOSTIM on the right, unless DOSTIM is a random variable. In this case, 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 $DES 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 DES at that time. Otherwise, ISFINL=0.

DES_DER, MITER, METH: See Diff Eq Solver Settings.

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

DISPLAYED VALUES

DES-defined variables may be listed for display in $TABLE or $SCATTER. The values displayed for the first event record of the data set are 0’s. The values displayed for the first event record of subsequent individuals are those from the last event record of the previous individual. This is because there is no call to DES with the first event record of the individual record, or with any other event record with the same value of TIME. NM-TRAN provides a warning message. (WARNING 48) DES-DEFINED ITEMS ARE COMPUTED ONLY WHEN EVENT TIME INCREASES. E.G., DISPLAYED VALUES ASSOCIATED WITH THE FIRST EVENT RECORD OF AN INDIVIDUAL RECORD ARE COMPUTED WITH (THE LAST ADVANCE TO) AN EVENT TIME OF THE PRIOR INDIVIDUAL RECORD.

The values displayed for event records other than the first are evaluated at the event time (as are all other displayed items such as PK-defined values and data record items).

Note that multiple calls to DES are associated with each event record. Some (including the final call during integration) may have a value of T that is larger than the end time of the integration interval. When NONMEM is performing simulation or a copying pass (COMACT>0), DES is called immediately after the advance to an event time or non-event time, with a value of T equal to this time, so that displayed values are the final value of T. Global variable ISFINL is set by PREDPP to 1 on this final call to DES. ISFINL can be tested on a WRITE statement if such statements are used in DES.

(See des, advan6, advan8, advan9).

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 following is a brief summary of the options. See Introduction to NONMEM 7 “Clinical Trial Design Evaluation and Optimization” for more detail and more examples. The options are described in the following sections:

$DESIGN Record Options (2) Additional Control Options for $DESIGN (3) Options for Setting up Types of Optimal Design
$DESIGN Record Options

APPROX=FO (default)

The nlme approximation method is specified here. First order (no interaction) is the default, and the appropriate type of covariance matrix is evaluated or used in optimization of the design. 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)), where FIM=Fisher Information Matrix (inverse of variance-covariance). 2: design type: a-optimality, -1/tr(1/FIM) 6: design type: ds-optimality, -log(det(FIM))+log(det(FIMunintersting)) To identify parameters as uninteresting, place UNINT at the parameter in the same manner you would place FIX. 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)), as described in the PFIM 4.0 manual [26].

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, as follows:

0,1,3,4,5: design type: D-optimality, -log(det(FIM))/D, where D is the dimension of the FIM.| 2: design type: a-optimality, -1/tr(1/FIM) 6: design type: DS-optimality, (-log(det(FIM))+log(det(FIMuninteresting)))/(D-U)| where U=number of uninteresting parameters. 7: design type: R-optimality (relative standard error), -1/(tr(sqrt(1/FIM)/Parameter))/D)| 8: -log(det(Bayes FIM))/D 9: design type: A-optimality, -1/(tr(1/FIM)/(D-U)) 10: -1/(tr(sqrt(1/FIM)/Parameter))/(D-U))

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. For a template of one subject, GROUPSIZE would then offer the variance-covariance expected from GROUPSIZE number of subjects.

FIMTYPE or FIMDIAG=0

FIMTYPE or FIMDIAG may be set to the following, and corresponds to fimcalc.type in POPED:

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, as described in the manual.

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. See example optdesign16.

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 (see below).

CLOCKSEED=0 (default)

As of nm75, the actual starting seed will be 10000*(seconds after midnight)+SEED (SEED may be set to 0 for this purpose), if CLOCKSEED=1. 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.

MODE=0 (default), 1, 2, or 3

Used for specifying data and prediction value type when specifying APPROX=FOCEI. In NONMEM report: 0 EVALUATE AT F(ETAsim) DURING CONDITIONAL DESIGN ASSESSMENT 1 EVALUATE AT THE MODE F(ETAhat) DURING CONDITIONAL DESIGN ASSESSMENT 2 EVALUATE AT F(ETAsim)-GETAsim DURING CONDITIONAL DESIGN ASSESSMENT 3 EVALUATE AT F(0) DURING CONDITIONAL DESIGN ASSESSMENT In other words, MODE=0 means FOCEI with data at F(ETAsim), and predicted function evalauted at f(ETAsim), is to be used. This method works well. MODE=1 means FOCEI with data at F(ETAsim), and predicted function evaluated at the mode, f(ETAhat), is to be used. The results are not satisfactory. MODE=2 means linearized FOCEI, with data at F(ETAsim)-GETAsim, and predicted function at F(ETAsim). Works well.

DATASIM=0 (default)

Normally, y-expectation evaluation of the FIM is performed. To actually simulate data, set DATASIM=1, and along with APPROX=FOCEI, this will produce simulated etas as well.

Additional Control Options for $DESIGN

The following options may be set within the $DESIGN record, and they operate exactly as their equivalents in the $EST record. Thus, the following are equivalent:

$DESIGN FIMDIAG=1 OFVTYPE=6 APPROX=FO
        MAXEVAL=9999 NOHABORT PRINT=20 SIGL=10 POSTHOC
$DESIGN FIMDIAG=1 OFVTYPE=6 APPROX=FO
$EST    MAXEVAL=9999 NOHABORT PRINT=20 SIGL=10 POSTHOC

The options are as follows.

SIGL
SIGLO
SIGL
SIGLO
ABORT/NOABORT/NOHABORT
MAXEVAL
MAXEVAL=0 indicates design evaluation (the default)

MAXEVAL>0 indicates design optimization PRINT control iteration printing during optimal design NUMERICAL/NONUMERICAL -2LL/LIKELIHOOD/LLIKELIHOOD SLOW/NOSLOW/FAST POSTHOC NOPRIOR FORMAT FILE FNLETA

Options for Setting up Types of Optimal Design

The additional options for $DESIGN listed below are for optimizing parts of the design components. For example, the DESEL, DESELSTRAT, DESELMIN, DESELMAX can be specified for all the various design elements that you want optimized. It might be TIME for time samples, AMT for dose, or some type of covariate specific for the problem. Certainly, any combination of covariates can be requested to be optimized.

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 (subject template), and use RS method to find optimal continuous parameters.

DISCRETE_SG

Find optimal number of time points for each sub-design (subject template), and use STGR method to find optimal continuous parameters.

Specific parameters must be specified to be optimized.

This is done using the following options:

DESEL=label

The data item (column) that contains the design element (DESEL) values that are to be modified and optimized. For example, TIME column would indicate that you want times to be estimated.

DESELSTRAT=label

The data item (column) indicating stratification. The DESELSTRAT data item should contain integer indices to indicate what values are to be shared, and estimated together. If a record contains a value of 0 in the DESELSTRAT column, then this record is not included in the estimation process, and its value (say its time value in DESEL=TIME column) will not be changed. If the record contains a value >0 in DESELSTRAT, let us suppose a 1, then all records with the value of 1 in DESELSTRAT will share the same time value (or whatever DESEL selected), extimated together. Those records with value 2 will be another set of records which will share a time value, etc. Thus, within a subject, there may be a PK record and a PD record which should share the same time value. Also, a group of subjects may share the same time values. Within a subject, times will be automatically sorted as they are changed, so that NONMEM’s time ordering policy is not violated.

DESELMIN=label

The data item (column) containing the minimal value

DESELMAX=label

The data item (column) containing the maximal value

You must impose boundaries on the values that are being optimized. That is done with these two data items. Only those records with a stratification value >0 in DESELSTRAT column will require a min and max value, and only those records that define that stratification value for the first time.

All four DESEL items must be specified: DESEL,DESELSTRAT,DESELMIN,DESELMAX. They may be repeated for as many design elements are to be optimized. For example for times and amounts: DESEL=TIME DESELMMIN=TMIN DESELMAX=TMAX DESELSTRAT=TSTRAT DESEL=AMT DESELMIN=AMTMIN DESELMAX=AMTMAX DESELSTRAT=AMTSTRAT

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. If NMIN<0 or NMAX<0, then most previous non-negative value is used. The NMIN and NMAX column are only used for the DISCRETE* analyses, to bound the number of time points that may be permitted for a given subject. With DISCRETE*, the total N of time points among all subjects is determined by the total number of time points whose MDV=0 in the starting data set.

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. If STRAT and STRATF are specified, and there is at least one STRAT value >0, then the SRATF values are optimized, and represent the weight to the contribution of that subject to the Information matrix. For STRAT<=0, then their STRATF values are not optimized, and remain fixed at their initial values, but are still used as weights to the information matrix. It is up to the user to ensure that the sum of STRATF values among unique STRAT values sum to 1. If value of STRATF<0.0, then that subject is not included in the assessment.

Additional $COVARIANCE Control Options for $DESIGN

In addition, $DESIGN sets up the covariance step as $COV MATRIX=R UNCONDITIONAL without the user requiring this record entered in the control stream. If you wish to specify additional control for the covariance, you can add these in a $COV record, such as: $DESIGN FIMDIAG=1 OFVTYPE=6 APPROX=FO MAXEVAL=9999 NOHABORT PRINT=20 SIGL=10 POSTHOC $COV PRINT=E

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 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). General rules for abbreviated code are documented elsewhere (See abbreviated code). Specific rules follow.

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 pseudoassignment statement.

Right-hand quantities in assignment statement and in conditions:

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. This includes Y.

Left-hand quantities from the $PK block, if neither $PK nor $ERROR include the COMRES=-1 pseudo-assignment statement.

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. Special rules apply to blocks of abbreviated code that are executed when ICALL is not 2. (See Initialization-Finalization block, Simulation block). (See Expectation block, Data_Average block).

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

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.

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. CALLFL=2: Call once per problem. In effect, this is supplied by NM-TRAN for the simple error models, but it cannot be specified explicitly in the $ERROR record. (See callfl).

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 then either upper or lower case may be used . E.g., $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`, `$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 $ESTIMATION_record_options).

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 thetarecovery 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 (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.
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. User may still over-ride those options set by auto, by specifying them on the same $EST record. 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=2 (NM74): AUTO=3 may be user with NUTS estimation to setup the alternative sampling strategy of eta sampling. See INTRODUCTION TO NONMEM 7 for more information.
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. May be used with BAYES_PHI_STORE=1 or write statements capturing the individual parameters samples. See INTRODUCTION TO NONMEM 7 for more information.
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. See INTRODUCTION TO NONMEM 7 for more information.
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 (where independent variable is iteration number, dependent variable is parameter value). If CITER=10, then 10 of the most recent PRINTed or CINTERVAL iterations are used for the linear regression test. Default is 10. May also be coded CNSAMP. If CINTERVAL is not specified, then the PRINT option is used.
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, allowing for a more global search of parameters that minimize the objective function. 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 to facilitate any associated thetas. Simulated annealing is performed by subroutine CONSTRAINT. The $ANNEAL record facilitates EM search methods for this additional annealing technique. The subroutine CONSTRAINT may also be used to provide any kind of constraint pattern on any parameters. (See $ANNEAL). The user may modify the subroutine CONSTRAINT that performs the simulated annealing algorithm. (See additional_output_files, raw_output_file).
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 that the test should be applied to the objective function value, THETA’s and SIGMA’s but not to the OMEGA’s. CTYPE=2 indicates that the test should be applied to the objective function value, THETA’s, SIGMA’s and diagonal elements of OMEGA. CTYPE=3 indicates that the test should be applied to the objective function value, 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 beyond the decimal point over 10 iterations, even though a parameter may oscillate at some digit. If this condition is satisfied, the estimation will terminate successfully. Applies to FO/FOCE/Laplacean methods.
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 forward difference assessment can differ greatly from the backward difference assessment in cases of extreme discontinuity when varying certain thetas by even just a small amount in the model results in a large change in objective function, (such as a viral model in which a very small change in the potency of an anti-viral agent results in widely varying time of return of viral load). This results in standard errors being poorly assessed for thetas that do not have inter-subject variances associated with them. Setting DERCONT=1 slows the analysis, but can provide more accurate assessments of SE in such models. 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 This is the 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 for dispersion. 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 (See etabar) 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 (See etabar) 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. In evaluating the MAP objective function, the term log(Det(V)) must be evaluated to obtained the marginal or integrated posterior density, where V is the eta Variance matrix based on the subject’s posterior density. With ETADER>0, SLOW option may be needed. ETADER=0 Expected value V, using analytical first derivatives ETADER=1 Expected value V, using forward finite difference numerical first derivatives. Needed if not all code evaluating F and Y derivatives with respect to eta are available for processing by NM-TRAN or in user supplied code. ETADER=2 Expected value V, using central finite difference numerical first derivatives. Needed if not all code evaluating F and Y derivatives with respect to eta are available for processing by NM-TRAN or in user supplied code. ETADER=3 2nd derivative method of evaluating V, using numerical second derivatives of -log(L) with respect to etas. This is equivalent to using the “Laplace NUMERICAL” method, even though FOCE may be selected.
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, where root is the root name of the control stream file. See “Stochastic Approximation Expectation Maximization (SAEM) Method” in Guide INTRODUCTION TO NONMEM 7.
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 etasxi).
EVALSHRINK=0 (NM760): By default, when MAXEVAL=0, and population parameters are not inputted from an MSF file (using the $MSFI record), 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 in the manner described in Guide INTRODUCTION TO NONMEM 7, “MU Referencing”. For thetas that should not have inter-subject variability, or should not be MU referenced, MU reference it anyway by adding addional etas and assigning them to these thetas through MU referencing, but set their associated omega values to 0.0 FIXED.
FILE=filename: Name for the raw output file. Parameter estimates and objective function value will be printed to this file every printed iteration as indicated by the PRINT option. Default: root.ext, where root is the name of the control file (not including any extension; “nmbayes” if the name is not specified on the nmfe command line). Note that the names of additional output files are not affected by this option. 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 They always have the name of the control file or “nmbayes” for root. (See additional_output_files, raw_output_file).
FNLETA=n (NM72): For a thorough discussion: See INTRODUCTION TO NONMEM 7, General New Options for $ESTIMATION Record FNLETA=0 requests that the FNLMOD and FNLETA routines not be called after the Estimation and Covariance steps are completed. May improve run time. Post-hoc etas for METHOD=0 will not be computed. All table outputs (diagnostics and user selected items) will use EBE’s from final estimation method (conditional modes for FO/FOCE/Laplace/ITS, conditional means for IMP/SAEM, MCMC posterior means for BAYES). FNLETA=1 is the default. FNLMOD and FNLETA routines are called as usual. Diagnostics depending on EBE’s such as CWRES, CIWRES, CIPRED, etc., will use EBE’s based on the final estimation method (conditional mode for FO/FOCE/Laplace/ITS, conditional mean for IMP/SAEM, MCMC posterior means for BAYES), while user selected items will use EBE’s from the FNLETA step (eta modes). FNLETA=2 Requests that the estimation step not be done. All table outputs will use a common set of EBE’s from an imported source. This has value if you loaded the individual etas from an MSF file, or from a $PHIS/$ETAS record, and you want to calculate $TABLE items based on those etas, rather than from a new estimation. FNLETA=3 (as of nm74) Like FNLETA=1, will call FNLETA, and all table outputs (diagnostics and user selected items) will use EBE’s from the FNLETA step (eta modes).
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. For more details, see the format help item: (See format). May also be coded DELIM.
DELIM=s: Same as FORMAT option. See INTRODUCTION TO NONMEM 7, $EST: Format of Raw Output File
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). This computation is parallelized if parallelization is on for the final Estimation Step. FPARAFILE=filename specifies a different parafile than was used for the Estimation Step. FPARAFILE=ON turns on parallelization for the EBE’s. FPARAFILE=OFF turns off parallelization for the EBE’s. The FPARAFILE option may be specified on any $ESTIMATION record, but applies only after the last Estimation Step.
GRD=s: s is a string of [G|N|D|S]’s with each symbol representing a THETA or SIGMA parameter in numerical order. The first m letters of GRD refer to the m THETA’s. Then the m+1th letter refers to SIGMA(1,1), m+2 refers to SIGMA(2,2), etc (going along the diagonal of SIGMA). Omitted symbols are assumed to be D. 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. S is used with Monte Carlo EM methods. D (default) indicates the program will decide. G and N are used only with the BAYES method. Default is DDDD…
GRD=t1v1(n1):t2v2(n2):t3v3(n3)…: An alternative syntax may be used. T is parameter type (T for theta, S for sigma-like theta). V is a letter (S,D or N), and n is a number list. For example, to specify thetas 3, and 5 through 8 to be Gibbs samples, theta 4 is sigma-like, and sigmas 1-3 are to be Metropolis-Hastings processed, GRD=TG(3,5-8):TS(4):SN(1-3) Thetas and sigmas not specified are given a default D designation.
GRDQ=0 (NM74): Optional. The gradient quick option, called GRDQ, allows thetas that must be gradient assessed (such as those that are not mureferenced) and SIGMAS to be more quickly evaluated by not evaluating the gradients for every one of the ISAMPLE random samples, but chooses a subset of the most important samples.
GRID=(nr,ns,r0,r1): Optional. May be used with STIELTJES. For nr, ns, r0, and r1, see the detailed description to option STIELTJES below. Briefly, a grid is obtained by first taking the interval [r0,r1] of the length axis and dividing this interval into nr equal subintervals. ns may be thought of as the number of points in a single quadrant of a 2-dimensional ellipse in n-space. Constraints are nr<=100, ns<=9999, 0<r0<r1<1. If r1>.9999, there is no tail region. nr and ns should be integers. 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. See ISAMPLE_M2. Default is 0.4. With Importance sampling (IMP INTERACTION), expand proposal (sampling) density variance relative to conditional density so that on average conditional density/proposal density=IACCEPT (default 0.4). For very sparse data or highly non-linear posterior densities (such as with categorical data), you may want to decrease to 0.1 to 0.3.
IACCEPT=0: For importance sampling only, you may set IACCEPT=0.0, and NONMEM will determine the most appropriate IACCEPT level for each subject, and if necessary, will use a t- distribution (by altering the DF for each subject) as well. If IACCEPT=0, the individual IACCEPT values and DF values will be listed in root.imp.
IACCEPTL=x (NM74): A scale to a second multi-variate normal density, to cover long tails in the posterior density (hence L for long tails), in combination with the normal IACCEPT value to cover the posterior density near the mode.
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 and is supplied if NOINTERACTION is not specified by the user. 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. See also STDOBJ.
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. A kernel is the Metropolis-Hastings sampling and testing mode used. The ISAMPLE_Mx options define how many times to generate and test a sample for goodness-of-fit using a given kernel. ISAMPLE does not refer to a kernel, but defines the number of chains that are maintained, each chain having their own sample generation and testing sequence using the various kernels. Each chain retains a final sample for each subject, at the end of each iteration.
ISAMPLE_M1=n: n is the number of mode 1 iterations for the Metropolis-Hasting algorithm for estimating individual parameters using the population means and variances as proposal density. Used with the SAEM and BAYES methods. Default is 2.
ISAMPLE_M1A=n (NM72): n is the number of mode 1A iterations for the Metropolis-Hasting algorithm, testing model parameters from other subjects as possible values. Used with the SAEM and BAYES methods. Default is 0.
ISAMPLE_M1B=n (NM74): n is the number of mode 1B iterations for the Metropolis-Hasting algorithm Default is 2.
ISAMPLE_M2=n: n is the number of mode 2 iterations for the Metropolis-Hasting algorithm for estimating individual parameters using the current parameter vector position as mean and a scaled variance of OMEGA as variance. Used with the SAEM and BAY
ISAMPLE_M3=n: n is the number of mode 3 iterations for the Metropolis-Hasting algorithm for estimating individual parameters in which samples are generated for each parameter separately. Used with the SAEM and BAYES methods. 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 in order to meet the IACCEPT condition 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. These options allow the scale factor boundary to be modified.
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, 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. With KNUTHSUM algorithm on by default, the SORT option is not necessary. Default is 0. May also be set with $COVARIANCE record.
LAPLACIAN: Use the Laplacian method, in which second derivatives with respect to eta are used. Laplacian may not be used with METHOD=0. It may be used with the EM/Monte Carlo methods, in which case the Laplacian option will be properly utilized, such as during MAP estimation used during IMP, IMPMAP, and ITS, or ignored, such as during SAEM or BAYES. 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. In earlier versions of NONMEM, this was the default (and only) action. To obtain similar results as earlier versions of NONMEM, set LEVCENTER=1. If LEVCENTER=0, level etas are not forced to sum to 0. See INTRODUCTION TO NONMEM 7 for more information.
LEVOBJTYPE=[0|1] (NM751): If LEVOBJTYPE=0, then for IMP/ITS/FOCE/Laplace, the reported ojective function (and what is used for estimation) is the average of two cycles of optimization. The first optimization floats all etas, and the second optimization fixes the super-ID etas to the appropriate average of etas per super-id group from the first optimization, and then floats the ID (and below) level etas. If LEVOBJTYPE=1, then the OBJ reported (and used for estimation) is only that of the second optimization cycle. The LEVOBJTYPE=0 provides the most consistent results between FOCE/Laplace and the EM and Bayes methods, particularly with super-ID levels higher than 1 (so, site ID and country ID, for example). The LEVOBJTYPE=1 provides an OBJ more consistent with theory. By default, NONMEM sets the estimation process to SLOW when a $LEVEL option is used. As of nm751, you may set NOSLOW or FAST. While there is an increase in speed, but there may not be as good optimization progress as with the SLOW option. It may be best to use SLOW for the $EST step, and use NOSLOW or FAST for the $COV step. See INTRODUCTION TO NONMEM 7 for more information.
LEVWT=n (NM74): This option applies when $LEVEL record is present. By default, LEVWT=0, and weights each level value equally, regardless of number of subjects per level value. To weight according to number of subjects for that value, set LEVWT=1.
LIKELIHOOD: This is designed mainly, but not exclusively, for use with non-continuous observed responses (“odd-type data”). Indicates that Y (with NM-TRAN abbreviated code) or F (with a user-supplied PRED or ERROR code) will be set to a (conditional) likelihood. Upon simulation it will be ignored, and the DV data item will be set directly to the simulated value in abbreviated or user code. Also etas, if any, are understood to be population etas. Epsilon variables and the $SIGMA record may not be used. The L2 data item may not be used. The CONTR and CCONTR options of the $SUBROUTINES record may not be used. NONMEM cannot obtain the initial estimate for omega. If the data are population, and MAXEVALS=0 is not coded, then NOINTERACTION is required. Compare with PREDICTION option.
-2LOGLIKELIHOOD: Indicates that Y (with NM-TRAN abbreviated code) or F (with a user-supplied PRED or ERROR code) is a -2 log (conditional) likelihood. All remarks for LIKELIHOOD apply. May also be coded -2LLIKELIHOOD. Compare with PREDICTION option.
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. Thus, if MAPITER=20 and MAPINTER=5, then for the first 20 iterations, MAP estimation is used, and thereafter, every 5th iteration the MAP estimation is used. If MAPINTER=-1, then mapinter will be turned on only if the objective function increases consistently over several iterations. Setting any of the above parameters to -100 will force NONMEM to select the default value for that parameter.
MAPITER=n (NM72): The first n iterations are to use MAP estimation to assess parameters for the sampling density. After these n iterations, the conditional means and variances of the pervious iteration are used for the sampling density parameters of the present iteration. If MAPITER=0, then the first iteration will rely on conditional means and variances that are in memory. These may have come from an MSF file, or from a previous estimation step.
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. Alternatively, you can insert the record: $EST METHOD=ITS NITER=0 Followed by $EST METHOD=SAEM or $EST METHOD=BAYES
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. Default: a generous number. (Each evaluation of the objective function requires one pass through the data set. This is also referred to as a “function evaluation.”) MAXEVALS=-1 may be specified when a $MSFI record is present. It requests that NONMEM re-use the value from the previous run, and is the default with $MSFI. MAXEVALS=0 requests that the Estimation Step be omitted. This is useful, for example, with POSTHOC (see above).

MCETA=n (NM73)
MCETA=0

Eta=0 is initial setting for MAP estimation (eta optimization). This is the default.

MCETA=1
     ETA=values  of previous iteration is initial setting for MAP

estimation, or ETA=0, whichever gives lower objective function.

MCETA>1

MCETA-1 Random samples of ETA, using normal random distribution with variance OMEGA, are tested. Plus previous ETA is tested, and ETA=0 is tested. Whichever gives the lowest objective function is used as initial setting for the MAP optimization.

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.” The conditional estimates of the etas are referred to as Conditional Parametric Etas (CPE).

METH=COND NOLAPLACIAN is referred to as the FOCE method.
METH=COND LAPLACE is referred to as the Laplace method.
METH=COND NOLAPLACE CENTERING is referred to as the Centering FOCE method.
METH=COND LAPLACE CENTERING is referred to as the Centering Laplace 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. Cannot be used with LAPLACIAN or CENTERING. The following methods are new to NONMEM 7. When any of these methods are used, the data are inferred to be population, and METHOD=1 is supplied if it is not already present. The first four methods are referred to as EM (Expectation-Maximization) Methods.

ITS Use the iterative two-stage method. This method evaluates the conditional mode and first order approximation of the conditional variance of parameters of individuals by maximizing the posterior density. This integration step is the same as used in the FO.
IMP Use the Monte-Carlo Importance Sampling Expectation Maximization method. This method evaluates the conditional mean and variance of parameters of individuals by Monte Carlo sampling. It uses the posterior density, which incorporates the likelihood of parameters relative to population means and variances with the individual’s observed data. The normal density near the mean or mode of the posterior is used as a proposal density, then weighted according to the posterior density as a correction.

IMPMAP Use the Importance Sampling method assisted by Mode a Posteriori (MAP) estimation. At each iteration, conditional modes and conditional first order variances are evaluated as in the ITS or FOCE method. These are then used as parameters to the multivariat SAEM Use the Stochastic Approximation Expectation Maximization method. As in importance sampling, random samples are generated from normal proposal densities. However, instead of always being centered at the mean or mode of the posterior density, the proposal BAYES Use the Markov Chain Monte Carlo (MCMC) Bayesian Analysis method. The goal of the MCMC Bayesian analysis is to obtain a large sample set of probable population parameters. Various summary statistics of the population parameters may then be obtained such a DIRECT Requests Monte Carlo Direct Sampling. Creates completely independent samples (unlike MCMC), and there is no chance of causing bias if the sampling density is not similar enough to the conditional density (unlike IMP). However, it is very inefficient, requiring ISAMPLE settings of 10000 to 300000 to properly estimate the problem.

NUTS (NM74)
     Requests No U-Turn Sampling (NUTS) Markov Chain Monte  Carlo
     (MCMC)  Bayesian  Analysis  Method.   Options unique to this
     method are  listed  alphabetically  under  NUTS_....   Other
     options of interest with their defaults are as follows:
          MASSRESET=-1
          MADAPT=-1
          KAPPA=1
          TTDF=0
          OLKJDF=0
          OVARF=1
          SLKJDF=0
          SVARF=1

CHAIN Allows the user to create a series of random initial values of THETAs and OMEGA’s, or for reading in initial population parameters from a file of rectangular (rows/column) format. Applies only to the Estimation Step.

LNTWOPI (NM74)

The objective function is reported including the N*LOG(2pi) constant term, where N is the total number of normally distributed data values in the data set. Compare OLNTWOPI. Either or both may be used.

MSFO=filename

A Model Specification File is output to a file with the given filename. Filename may not contain embedded spaces. If filename contains commas, semicolons, or parentheses, then it must be surrounded by quotes (’ or “). Filename may also contain equal signs if it is enclosed in quotes. Filename may contain at most 71 characters. If filename is the same as any option of the $ESTIMATION record, it must be enclosed in quotes. If the $NONPARAMETRIC record is present and also specifies the MSFO option, the filename is required on the record which appears first in the control stream. If filename is present on both, it must be the same. If the filename is omitted on the second of the two records, the MSF option must be the final option on that record. Default: If the MSFO option is not used, no MSF is output. If a MSFO is output, then the iteration estimates may also be seen in the original parameterization for those iterations whose summaries appear in intermediate printout. These estimates may be found in file INTER. When MAXEVAL=0 and the Covariance Step is implemented, the MSFO option may also be used, and then a model specification file will be output which will include information from the Covariance Step and from the input model specification file concerning the earlier Estimation Step (in this case there must be an input model specification file). (See model_specification_file).

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 the THETA should not be Mu modeled. D indicates the program will decide if the parameter should be Mu modeled or not. X indicates that THETA is involved in a covariate-dependent mixture model and is required if this is the case. Default is DDDD…

MUM=v1(n1):v2(n2):v3(n3)…

An alternative syntax may be used. V is a letter (N,M,D, or X), and n is a number list. For example, to specify that thetas 3 and 5 through 8 should not be MU modeled, theta 2 is a population mixture parameter, and thetas 6 and 12 are to be MU modeled: MUM=N(3,5-8):X(2):M(6,12)

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 n5 is the number of iterations for the non-stochastic accumulation phase. Default is 1000. When used with the BAYES method n5 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. It may be turned on again for the next estimation step with NOCOV=0. If NOCOV=1 is set for an FOCE/Laplace/FO step, this is equivalent to $COV NOFCOV setting. For ITS and IMP, covariance estimation can take some time for large problems, and you may wish to obtain only the objective function, such as in the case of $EST METHOD=IMP EONLY=1 after an SAEM estimation. NOCOV has no effect on BAYES analysis, as no extra time is required in assessing covariance for BAYES. By default, standard error information for the classical methods (FO/FOCE/Laplace) will be given only if they are the last estimation method, even if NOCOV=0 for an intermediate estimation step. If NOCOV=1 for the FOCE/LAPLACE/FO method, and it is the last estimation step, then standard error assessment for it will be turned off.

NOLABEL=[0|1]

1 indicates that the row of item names for FILE will not be written, otherwise 0, the default. Affects the raw output file and all additional output files.

NONINFETA=[0|1] (NM73)

Sometimes, gradients are not properly evaluated for classical NONMEM methods, when not all etas are used for all subjects. For example, an eta to a ka absorption rate constant during a fit of a subject with only IV dosing would be considered a non-influential data. If $EST METHOD=1 or 0 is used without the SLOW option, this can result in evaluating very large and incorrect gradients, which in turn affects the search path, and sometimes the final objective function value. Should this occur, add NONINFETA=1 to the $EST record. 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, and this prior information will be used. If NOPRIOR=1, then for the particular estimation, the prior information is not included in the analysis. This is useful if you do not want to use prior information during a maximization (METHOD=IMP, CONDITIONAL, IMPMAP, SAEM, or ITS), but then use it for the Bayesian analysis (METHOD=BAYES). With NOPRIOR=1, FOCE is still allowed to evaluate an S MATRIX, since prior information is not used. I.e., $EST NOPRIOR=1 and $COV MATRIX=S are permitted. With NONMEM 7.3, when NOPRIOR=1 is set, the estimation will not use TNPRI prior information (TNPRI should only be used with FO/FOCE/Laplace estimations). In previous versions of NONMEM, NOPRIOR=1 did not act on TNPRI priors.

NOSUB=[0|1] (NM74)

With NOSUB=0, label substitution will be performed for final estimates in the NONMEM report file. (See $ABBREVIATED). This is the default. With NOSUB=1, label substitution will not be performed.

NOTITLE=[0|1]

1 indicates the header for FILE will not be written, otherwise 0, the default. Affects the raw output file and all additional output files.

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). These numeric values are displayed in root.fgh, but are not used in estimation. 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)

See Guide INTRODUCTION TO NONMEM 7. Default is 0.8

NUTS_EPARAM (NM74)

See Guide INTRODUCTION TO NONMEM 7. Default is 0

NUTS_GAMMA (NM74)

See Guide INTRODUCTION TO NONMEM 7. Default is 0.05

NUTS_INIT (NM74)

See Guide INTRODUCTION TO NONMEM 7. Default is 0.075.

NUTS_MASS (NM74)

See Guide INTRODUCTION TO NONMEM 7. Default is B

NUTS_MAXDEPTH (NM74)

See Guide INTRODUCTION TO NONMEM 7. Default is 10

NUTS_OPARAM (NM74)

See Guide INTRODUCTION TO NONMEM 7. Default is 1

NUTS_REG (NM74)

See Guide INTRODUCTION TO NONMEM 7. Default is 0.0

NUTS_SPARAM (NM74)

See Guide INTRODUCTION TO NONMEM 7. Default is 1

NUTS_STEPINTER (NM74)

See Guide INTRODUCTION TO NONMEM 7. Default is 0

NUTS_STEPITER (NM74)

See Guide INTRODUCTION TO NONMEM 7. Default is 1

NUTS_TERM (NM74)

See Guide INTRODUCTION TO NONMEM 7. Default is 0.05

NUTS_TEST (NM74)

See Guide INTRODUCTION TO NONMEM 7. Default is 0

NUTS_TRANSFORM (NM74)

See Guide INTRODUCTION TO NONMEM 7. Default is 0

OACCEPT=n

Used only with the BAYES method. n has meaning only for OMEGA sampled by the Metropolis-Hastings algorithm. The scaling of degrees of freedom is adjusted so that samples are accepted n fraction of the time. See OSAMPLE_M2=. Default is

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, with OLKJDF degrees of freedom for all omega blocks. In addition, only diagonal elements of the OMEGA prior are used, assuming a density dependent on the OVARF value. OLKJDF may be set >0 when using METHOD=BAYES as well, but thetas will then be M-H sampled using the OSAMPLE_M1, OSAMPLE_M2, and OSAMPLE_M3 settings. 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 NETANINDLOG(2pi) constant term for SAEM and BAYES, where NETA is the number of etas, and NIND is number of individuals. Compare LNTWOPI. Either or both may be used.

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, i.e., to behave like NONMEM V in this regard. Any option listed above may be preceded by “NO”. The THETA, OMEGA, and SIGMA choices are independent of each other. E.g., it is possible to specify NOOBT (to prevent the “default OMEGA boundary test”) and permit both the “default THETA boundary test” and “default SIGMA boundary test”.

OMITTED

The Estimation Step is not implemented.

OPTMAP=n (NM73)

For alternative MAP (eta optimization) methods. With OPTMAP>0, SLOW option may be needed. OPTMAP=0 Standard variable metric (Broyden, Fletcher, Goldfarb, and Shanno (BFGS)) optimization method used by NONMEM to find optimal eta values (referred to as eta hat) for each subject at the mode of their posterior densities, using analytical derivatives of F with respect to etas (G), and analytical derivatives of F with respect to etas (H), that were supplied by NMTRAN or by the user. This is the default. OPTMAP=1 Variable metric method using numerical finite difference methods for first derivatives of F with respect to etas. Necessary when not all code used in evaluating F, G and H for observation event records is abbreviated code (some may be in verbatim code), and/or some portions of the computation of F, G and H are evaluated in a hidden subroutine specified by “$SUBROUTINES OTHER=” and the user-written code does not compute the eta derivatives. When OPTMAP=1 is present, values of G and H are ignored during eta optimization. This may be used to test user-coded deriatives, because two runs, one with OPTMAP=1 and one without it, should give very similar values for the OBJV, WRES, etc. if the user-coded derivatives are correct. OPTMAP=2 Nelder Mead method, which uses a secant method, rather than relying on derivatives.

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. (See order_option).

OSAMPLE_M1=n

Used only with the BAYES method. n is the number of times each iteration that OMEGA is generated using the Metropolis-Hastings algorithm and an inverse Wishart proposal density that has variance based on the previous samples. If n < 0 this indicates that

OSAMPLE_M2=n

Used only with the BAYES method. n has meaning only for OMEGA sampled by the Metropolis-Hastings algorithm. n is the number of times that OMEGA is generated using an inverse Wishart proposal density at the present OMEGA position and degrees of freedom

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, the normal density of the log square root of OMEGA centered about log square root of Omega prior, and scaled with OVARF (see below). That is, log(sqrt(Omega(i))) Normal(log(sqrt(OmegaPrior(i))),1/OVARF). If OVARF<0, then a half-t-distribution of degrees of ABS(OVARF) is used as the prior to the sqrt of OMEGA diagonal elements. Use OVARF=-1 for the half-Cauchy distribution. Default is 1. See also $OVARF control record.

PACCEPT=n

Used only with the BAYES method. n has meaning only for population parameters sampled by the Metropolis-Hastings algorithm. The scaling of variance is adjusted so that samples are accepted n fraction of the time. See PSAMPLE_M2=. Default is 0.5.

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 $ESTIMATION record. PARAFILE=OFF turns off parallelization for this $ESTIMATION record.

PARAFPRINT=n (NM74)

The print iteration intervals to the parallelization log file can be controlled by this option during parallelization of the $EST step. See also $COVARIANCE record and nmfe command. Default is PARAFPRINT=1.

PHYTYPE=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, where root is the root name of the control stream file. If you wish to have conditional mean etas reported, set PHITYPE=1. See “Stochastic Approximation Expectation Maximization (SAEM) Method” in Guide INTRODUCTION TO NONMEM 7.

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. To estimate the etas based on the initial estimates of THETA, OMEGA, and SIGMA (found either in the control stream or in a model specification file), also specify MAXEVAL=0 (which omits the Estimation Step). The conditional estimates of the etas are referred to as Conditional Parametric Etas (CPE).

NOPOSTHOC

Etas are not estimated. This is the default with METHOD=0. May not be used with METHOD=1.

PREDICTION

Indicates that Y (with NM-TRAN abbreviated code) or F (with a user-supplied PRED or ERROR code) will serve as a prediction variable, i.e., it will be set to a prediction. Upon simulation, the simulated observation is possibly also being set in Y or F. (However, the DV data item may instead be set directly to the simulated observation.) Also, etas (if any) are population etas only if epsilons also appear. 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 (so that summaries are printed for 0th and last iterations).

PRIORC (NM74)

The objective function is reported including the prior constant term (constant term to the prior).

PSAMPLE_M1=n

Used only with the BAYES method. n has meaning only for population parameters sampled by the Metropolis-Hastings algorithm. n is the number of times that a vector of THETA’s and SIGMA’s are generated using a multivariate normal proposal densit

PSAMPLE_M2=n

PSAMPLE_M3=n

Used only with the BAYES method. n has meaning only for population parameters sampled by the Metropolis-Hastings algorithm. n is the number of times in mode 3 that each parameter is individually sampled. 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 population parameters (theta/sigma) that are not Gibbs sampled, in order to meet the PACCEPT condition, is by default bounded by PSCALE_MIN of 0.01, and PSCALE_MAX=1000. This should left alone for MCMC sampling, but on occasion there may be a reason to expand the boundaries (perhaps to PSCALE_MIN=1.0E-06, PSCALE_MAX=1.0E+06).

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 (methods IMP, IMPMAP, and DIRECT) and only for the purpose of creating quasi-random samples of eta vectors. As of NONMEM 7.3, Sobol may be used for BAYES and SAEM methods as well. m: the type of scrambing desired 0: no scrambing (S0 is the same as S) 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, that will stay with that subject regardless of whether the job is run as a single process or parallel process. (NM74) The RANMETHOD specification propagates to subsequent $EST records in a given problem, but does not propagate to $CHAIN or $TABLE records.

REPEAT

The search is repeated with the initial estimates being the final estimates from the first search and with new UCP, so that a UCP value of 0.1 now corresponds to a final estimate 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. Cannot be used with STIELTJES.

REPEAT1

The search of the first stage of the Stieltjes method is repeated with the initial estimates being the final estimates from the first search and with new UCP, so that a UCP value of 0.1 now corresponds to a final estimate from the first search. May only be used with STIELTJES.

NOREPEAT1

The estimate obtained at the end of the search of the first stage of the Stieltjes method is taken to be the final parameter estimate at the first stage. This is the default. May only be used with STIELTJES.

REPEAT2

The search of the second stage of the Stieltjes method is repeated with the initial estimates being the final estimates from the first search and with new UCP, so that a UCP value of 0.1 now corresponds to a final estimate from the first search. May only be used with STIELTJES.

NOREPEAT2

The estimate obtained at the end of the search of the second stage of the Stieltjes method is taken to be the final parameter estimate at the second stage. This is the default. May only be used with STIELTJES.

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 (identical to R matrix in the $COV step) to be evaluated. Default is 0. See “Resetting the Search to Circumnavigate Saddle Points and Detect Inestimable Parameters” in Guide INTRODUCTION TO NONMEM 7 for a discussion of SADDLE_HESS and SADDLE_RESET options.

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

SELECT=[0|1|2|3] (NM73)

Used with METHOD=CHAIN and $CHAIN to specify how the sample is selected. SELECT=0 If ISAMPEND>=ISAMPLE, then the default action for selecting between ISAMPLE and ISAMPEND is taken, which for $EST METHOD=CHAIN is to find the one giving the best OBJ at the initial values, and for $CHAIN is to randomly select a sample, with replacement. This is the default. SELECT=1 The sample is selected sequentially from ISAMPLE to ISAMPEND with each new use of $CHAIN/$SIML with multiple sub-problems for the given problem, and with each new $EST METHOD=CHAIN with multiple sub-problems and across problems. When ISAMPEND is reached, the sample selection begins at ISAMPLE again. SELECT=2 Uniform random selection of sample, without replacement. Should the sample selection become exhausted, which would occur if CHAIN or $CHAIN records are utilized for more than ISAMPEND-ISAMPLE+1 times, subsequent sample selection then occurs with replacement. SELECT=3 Uniform random selection of sample, with replacement (this is equivalent to SELECT=0 for $CHAIN).

SIGDIGITS=n

Number of significant digits required in the final parameter estimate. SIGDIGITS is not used by the Monte-Carlo methods. Default: 3. May also be coded NSIGDIGITS.

SLKJDF=n (NM74)

Used with NUTS method, SLKJDF stands for Sigma LKJ density degrees of freedom. When 0, the usual inverse Wishart prior is used for Sigmas. When SLKJDF>0, then the LKJ density is used as the prior, with SLKJDF degrees of freedom. In addition, only diagonal elements of the Sigma prior are used. SLKJDF may be set >0 when using METHOD=BAYES as well, but Sigmas (in cholesky format) will then be M-H sampled using the PSAMPLE_M1, PSAMPLE_M2, and PSAMPLE_M3 settings (choleskys of sigma elements are treated as extensions of the THETA parameters in M-H sampling methods). Default is 0. See record $SLKJDF (NM75) to specify LKJ correlation degrees of freedom for each sigma block.

SIGL=n

n is used to calculate the step-size for finite difference derivatives independent of the SIGDIGITS value. If n=0 or n=100 then SIGL is ignored and SIGDIGITS is used as in versions prior to NONMEM 7. SIGL should usually be 2 to 3 times the value of NSIG. It is not used by the SAEM or BAYES methods.

SIGLO=n (NM72)

The precision to which the individual etas are optimized. The SIGL value set by the user continues to be the precision (or delta ) setting for the finite difference algorithms in the higher level estimation process for THETAS, OMEGAS, and SIGMAS. By default, if SIGLO is not specified, then SIGLO is set to the same value as SIGL. Should SIGLO be used, the recommended setting would be: SIGLO<=TOL SIGL<=SIGLO NSIG<=SIGL/3

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. If not present, the option is automatically supplied in these two cases. For problems where NONMEM VI does not behave as well (e.g. yields a higher OFV at termination) compared to NONMEM V, inclusion of the SLOW option may sometimes, but not always, yield NONMEM VI results that are similar to NONMEM V.

SLOW=1

Same as SLOW.

NOSLOW

Requests a faster method of computation. This is the default (but see SLOW)

SLOW=2

This option is permitted with STIELTJES.

SORT Individual contribution to the objective function value and indi-

vidual contributions to the gradients are sorted before they are summed, so that smaller numbers are summed before larger numbers.

NOSORT

Individual contribution to the objective function value and individual contributions to the gradients are summed in the order in which the individual records appear in the NONMEM data set, as was done prior to NONMEM VI. 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 under each subject between ISAMPLE and ISAMPEND, until the stochastic standard deviation of the objective function falls below STDOBJ.

STIELTJES

A set of tentative population estimates are first obtained using some 1st- or 2nd-order method (but not teh METHOD=HYBRID method). A tentative value for the integral (i.e. an area) is obtained. Then numerical integration is used to obtain second-stage estimates. A more detailed description of STIELTJES follows: Stieltjes is a two-stage method. In the first stage, a set of tentative population estimates are “quickly” obtained using some 1st- or 2nd-order population conditional method specified on the $ESTIM record in the usual way to obtain fairly reliable estimates. Include the METHOD=CONDITIONAL option on the $ESTIMATION record. However, the METHOD=HYBRID method cannot be used. At this first stage, for each individual, a tentative value for the integral (i.e. an area) is obtained. The first-stage estimates are used as initial estimates in the second stage, wherein another objective function is minimized to obtain a final set of parameter estimates. Numerical integration is used to obtain second-stage estimates. The integral will be exact in the case where the intraindividual model is of mean-variance kind and is linear in eta. The second stage takes much more time than the first stage, and the resulting parameter estimates are at least as good as the first-stage estimates, perhaps better. In the second stage, conditional estimates of eta are not used, but the functions that are minimized to obtain conditional estimates are still evaluated at many values of eta. Generally though, sufficiently good estimates are obtained by using conditional estimation methods, or even the First-Order Estimation method, and one needs to use the Stieltjes Estimation method only with somewhat pathological data designs. Simply also include the STIELTJES option (along with an optional GRID option) on the $ESTIMATION record. A default grid on eta-space is used for numerical integration, but one one may set one’s own grid. A grid is specified in terms of ellipsoidal coordinates, with origin at eta=0. With these coordinates, the length of a point P is given in fractile units - the first-stage estimate of the fraction of area enclosing all points with same or less length as that of P. A direction is specified by m=n-1 angles, where n is the number of (active) etas. At the second stage, the fraction of area enclosing all points of length less than r0 is taken to be identical to that computed at the first-stage. To obtain the fraction of area enclosing points of length greater than r0, numerical integration is used. A grid is obtained by first taking the interval [r0,r1] of the length axis and dividing this interval into nr equal subintervals. For each such subinterval, there is a region enclosing all points of length lying in the subinterval. There is yet another region (the tail region) enclosing all points of length between r1 and .9999. Within each region, the integrand is evaluated at a number of points, distributed fairly uniformly throughout the region, but with approximately the same length. The number of points is taken to be (ns**m)*(2n), where ns is some integer. Think of ns as the number of points in a single quadrant of a 2-dimensional ellipse in n-space, and nsm as the number of points in a orthant of m-dimensional space. 2**n is the total number of orthants. See the description to option GRID above to specify grid information.

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, the normal density of the log square root of SIGMA centered about log square root of SIGMA prior, and scaled with SVARF (see below). That is, log(sqrt(Sigma(i))) Normal(log(sqrt(SigmaPrior(i))),1/SVARF). If SVARF<0, then a half-t-distribution of degrees of ABS(SVARF) is used as the prior to the sqrt of SIGMA diagonal elements. Use SVARF=-1 for the half-Cauchy distribution. 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. See “Method for creating several instances for a problem starting at different randomized initial positions” in Guide INTRODUCTION TO NONMEM 7.

THETABOUNDTEST

See OMEGABOUNDTEST.

THIN=n (NM74)

The Bayesian records retained in the raw output file may be adjusted by every THINth iteration. So, if THIN=10, then every 10th iteration is recorded in the raw output file. The PRINT option controls only the iterations printed to the console and NONMEM report file. Default is 1.

TPU=n (NM75)

If TPU>0, use THETA_PRIORU routine in ..`THETA_PRIORU.f90. You can make a copy ofTHETA_PRIORU.f90, modify it, call itUSERPRIORT.f90, for example, then specify it as anOTHERroutine:$SUBR OTHER=USERPRIORT.f90.` See also \`$OLKJDFand \$SLKJDFforOMEGAandSIMGA`. Default is 0.

TTDF=n (NM74)

TTDF stands for Theta t-density degrees of freedom. It is used with NUTS method. Default is 0. When 0, the usual normal density prior is used as a prior density for thetas. When TTDF>0, a t-distributed prior is used. TTDF may be set >0 when using METHOD=BAYES as well, but thetas will then be M-H sampled using the PSAMPLE_M1, PSAMPLE_M2, and PSAMPLE_M3 settings. TTDF may be a real number. See also $TTDF control record (NM75) to specify degrees of freedom for each theta. The value of TTDF overrides $TTDF.

ZERO=list

Required with METHOD=HYBRID. A list of indices for etas which are fixed to zero during the Estimation Step. “list” contains one or more integers. If more than one, they must be surrounded by parentheses. The list must be contained entirely on one line. The indices may be separated by commas or spaces.

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. MUFIRSTREC=1 selects the covariate of the first record of the subject, rather than averaging among its records when using that covariate in a MU reference. The first statement of the $PRED or $PK block should be include nonmem_reserved_general.
OBJQUICK (NM74): The OBJQUICK option can speed up the NUTS method, and also ordinary BAYES, FAST FOCE, ITS, and the EM methods. Set OBJQUICK in $PRED or $PK. OBJQUICK=0 Default. Standard NONMEN processing of the model occurs. 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 in the model. The first statement of the $PRED or $PK block should be include nonmem_reserved_general.

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

15 `$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. For more details, see the format help item: (See format). See INTRODUCTION TO NONMEM 7, FORMAT=s1PE11.4 TBLN is the table number in the file. If TBLN is not specified, it defaults to 1, i.e., the first set of etas/phis are brought in. 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, if an ID column in the file exists, which it will, if you are using a .phi or .phm file generated from a previous nonmem analysis. 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, if an MSF file was not set up in the previous analysis (the MSF file system is still the most complete information transfer for resuming an analysis.

FURTHER DISUCSSION

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

In METHOD=0 (FO), they are ignored, because FO is specifically designed as a first order Taylor series approximation process centered around eta=0.

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.

For examples and discussion:

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

REFERENCES: Guide Introduction_7

16 `$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

17 `$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

18 `$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.EQ.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 abbreviated code). Specific rules for $INFN blocks are described elsewhere. (See Initialization-Finalization block, Finalization example).

RECORD ORDER:

Follows $SUBROUTINES.

REFERENCES: None

19 `$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, including control records as well as abbreviated code.

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

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 evid data item). 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 date data item).

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

20 `$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

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

21 `$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, i.e., above the previous super ID.
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 (i.e., the order in which they appear in each record of the data set) 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). For V1, eta(10) is the country variability that has nested in it the site variability eta(6), which in turn has nested in it the subject variability (the standard ID data) eta(2).

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, freely allowing all etas to vary on the first call of OBJ, then averaging the SID etas, fixing them to these averages, and going through another OBJ call to allow the subject (ID) etas to be assessed. This approximation method works very well for the EM and Monte Carlo methods, and reasonably well for the FOCE/Laplace methods.

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. For example, this is the case with $SUPER problems and $LEVEL.

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

REFERENCES: Guide Introduction_7

22 `$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.

General rules for abbreviated code are documented elsewhere (See abbreviated code). Specific rules follow.

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 ith. observation record of the individual record. TEMPLT may be used. (See MIX CONTR: TEMPLT).

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

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

23 `$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). [Amt=(total amount of drug thus far input into system) minus (total amount remaining in the system)] 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 (so that the amount therein remains zero) 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, advan9_15, $pk) (See Initial Steady State: I_SS,ISSMOD).

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” compartmet name substitution using $ABBR REPLACE records

For example:

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

allows susbsitutions 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

24 `$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 TNPRI). 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.5.0, choices are: $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 com-: pleted, 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

25 `$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 Nonparametric Density: DEN_,CDEN_)
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. If filename contains commas, semicolons, equal signs, or parentheses, it must be enclosed in quotes (’ or “). Filename may contain at most 71 characters. If filename is the same as any option of the $NONPARAMETRIC record, it must be enclosed in quotes. The MSFO option may appear without a file name. More precisely, if the $ESTIMATION record is also present, and it also specifies the MSFO option, then the filename is required only on one of the two records, $ESTIMATION or $NONPARAMETRIC, whichever one appears first in the control stream. If the filename appears present on both records, it must be the same on both records. If the filename is omitted on the second of the two records, the MSF option must be the final option on that record. Default: No MSF is output.
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 (even when EXPAND is selected). 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. While it is touted to be faster than EM (NNL is quadratically convergent whereas EM is linearly convergent), several tests have not indicated that NNL is any strong speed advantage. The reason is, that the computation time increases by at least the square of the number of support points (MAX(NSPSUPP,NIND)) with the NNL method, (least squares methods require matrix inversion, which is at least an N2 order process), whereas with EM the computation time increases in proporation to MAX(NSPSUPP,NIND). Thus the larger the number of support points, the greater the speed advantage of the EM method.
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

26 `$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 ..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

27 `$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. 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”).

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

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

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

FIXED indicates that the entire block is constrained to be fixed to its initial estimate.

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.

VARIANCE indicates that all initial estimates given for diagonal elements are understood to be initial estimates of variances of etas. This is the default.

STANDARD indicates that all initial estimates given for diagonal elements are understood to be initial estimates of standard deviations of etas. May also be coded SD.

COVARIANCE indicates that all initial estmates given for off-diagonal elements are understood to be initial estimates of covariances of etas. This is the default.

CORRELATON indicates that all initial estmates given for off-diagonal elements are understood to be initial estimates of correlations of etas.

CHOLESKY indicates that 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. The values desplayed in the NONMEM report and in the raw and additional output files are always variances 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. Initial estimates of some of the elements of the block may be 0, while initial estimates of some other elements may be nonzero, but only in the case where the block is constrained to be of band symmetric form. That is, given the diagonal and a group of contiguous subdiagonals symmetrically ocurring across the diagonal, the elements off both the diagonal and the subdiagonals are constrained to be zero. To specify the initial estimates of such a block, the initial estimates of those elements that are to be constrained to 0 should be given as 0, while all other initial estimates should be given as nonzero. E.g., with these structures for $OMEGA BLOCK(3), the 0’s are preserved: x 0x 00x

x xx 0xx

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. E.g., DIAGONAL SHIFT OF 1.1000E-03 WAS IMPOSED TO ENSURE POSITIVE DEFINITENESS

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). E.g., $OMEGA BLOCK(2) SAME(3) is equivalent to $OMEGA BLOCK(2) SAME $OMEGA BLOCK(2) SAME $OMEGA BLOCK(2) SAME

$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. Other options (such as FIXED, CHOLESKY, VARIANCE,STANDARD,COVARIANCE,CORRELATON, UNINT) may follow VALUES or be placed between BLOCK and VALUES. 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)

$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. If new $OMEGA records change the ordering, the abbreviated code does not have to be changed. 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. The abbreviated code can use this symbolic subscript instead of the numeric subscript. Then, these take effect on both ETA’s and MU_’s.

For example, suppose the following code is present for the first elements of THETA and ETA. Note that $OMEGA and $THETA records must be placed ahead of any records that use the symbolic label.

$THETA CL=(0.0,7.0)
$OMEGA ECL= 0.3
$PK
MU_ECL=THETA(CL)
CL=EXP(MU_ECL+ETA(ECL))

This is equivalent to

$THETA (0.0,7.0)
$OMEGA .3
$PK
MU_1+THETA(1)
CL=EXP(MU_1+ETA(1))

Another example defines symbolic labels for a block of OMEGA:

$OMEGA BLOCK(4)
ECL=  0.3
EV1=  0.01 0.35
EQ=   0.01 0.01 0.54
EV2=  0.01 0.01 0.01 0.67

Or, for diagonals,

$OMEGA
ECL= 0.3
EV1= 0.35
EQ=  0.54
EV2= 0.67

$OMEGA BLOCK(n) NAMES (label1,…,labeln) VALUES (odiag,diag)

: {.nmtran} (NM75)

With NONMEM 7.5, Symbolic label substitution may be specified for an entire block using the NAMES option. This is a compact way of defining one or more etas with labels and, when combined with VALUES, with initial values. For example

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

This is equivalent to

$OMEGA BLOCK(4)
ECL=  0.03
EV1=  0.01 0.03
EQ=   0.01 0.01 0.03
EV2=  0.01 0.01 0.01 0.03

If both are present, VALUES() must come after NAMES().

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. Furthermore, some theta parameters could be shared across subjects (“pooled fit parameters”), whereas etas are free to fit each individual without any population constraint. Parallelization is possible.

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:

$OMEGA 0.5 0.7 SCALE(2.0) 0.8 0.9 SCALE(1.5) 0.1 0.2

is equivalent to

$OMEGA 0.5 0.7 1.6 1.8 0.15 0.3

Other examples:

$OMEGAP SCALE(0.7) BLOCK(4) FIX VALUES(0.5,0.01)

is equivalent to:

$OMEGAP BLOCK(4) FIX VALUES(0.35,0.07)
$OMEGAP SCALE(0.7) BLOCK(4) FIX

0.5 0.01 0.5 SCALE(2.5) 0.02 0.02 0.003

Is equivalent to

$OMEGAP SCALE(0.7) BLOCK(4) FIX

0.5 0.01 0.5 0.05 0.05 0.0075

The SCALE is most useful when it is desired to scale an informed prior OMEGA from a previous analysis that differs from NONMEMs normal treatment. For example, you may wish to scale the omega prior by (df-p-1)/df, where df=degrees of freedom, and p=dimension of omega block. Rather than always re-calculate by hand, you can change the scale on the fly.

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

28 `$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 nwpri).

OPTIONS:

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

REFERENCES: Guide Introduction_7

29 `$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

30 `$DESIGN` (NM75)

MEANING: Requests that NONMEM perform clinical trial design evaluation or optimal design

CONTEXT: NM-TRAN Control Record

DISCUSSION:

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

See INTRODUCTION TO NONMEM 7, Clinical Trial Design Evaluation and Optimization (NM75)

REFERENCES: INTRODUCTION TO NONMEM 7

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. General rules for abbreviated code are documented elsewhere (See abbreviated code). Specific rules for $PK follow.

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 Compartment Initialization Block)

Initial steady state flag I_SS (Optional). (See advan68, advan9, $model) (See Initial Steady State: I_SS,ISSMOD).

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

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. Special rules apply to blocks of abbreviated code that are executed when ICALL is not 2. (See Initialization-Finalization block, Simulation block). (See Expectation block, Data_Average block).

Global Variables in Modules

Certain variables in FORTRAN modules can be used. (See Variables_in_modules) 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 Compartment Initialization Block)

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 $ERROR). General rules for abbreviated code are documented elsewhere (See abbreviated code). Specific rules for $PRED follow.

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

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.

Special rules apply to blocks of abbreviated code that are executed when ICALL is not 2. (See initialization, finalization, simulation). (See expectation, data average).

Variables in Fortran modules Certain variables in FORTRAN modules can be used. (See Variables_in_modules)

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, i.e., the subroutine is called if all the conditions in any one conditional clause are true. See the Examples, below. 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 PRIOR Simulation: ICMAX).

Subroutine arguments

Optional. The arguments are described in the help entries for NWPRI and TNPRI. They must be coded excatly 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

EXAMPLE:

$PRIOR TNPRI (ESTIMATION, PROB .GE.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. IFND is set to 1 with these calls; all other arguments are 0.

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

TNPRI (EST, PROB 4) IFND=1
TNPRI (EST, PROB 5) IFND=1

Same as the preceding example. TNPRI is called with the Estimation step of problem 3. IFND=1 with this call. Similarly with problems 4 and 5. 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 requrired. 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 TNPRI, TNPRI, prior). (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 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 etaepsilon 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 etaepsilon interaction. Always same as PRED, RES, and WRES.

CPRED, CRES, CWRES

Calculated assuming conditional estimation and no etaepsilon 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 And just interpret it as $SCAT ETA1 VS ETA3 With NONMEM 7.4, more flexible syntax is available, using TO and BY. (See $table).

With NONMEM 7.4, a symbolic label specified in $ABBR REPLACE may be listed in $SCAT. For example: $ABBR REPLACE ETA(CL)=ETA(1) … $SCAT ETA(CL) VS ETA3

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, corresponding to VECTRA(1), VECTRA(2),
   ..., VECTRA(9).
   The labels in the output will be 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.

For a discussion of the values of ETAs and PRED-defined items (e.g., are they based on initial or final values of theta? Simulated or zero or conditional values of eta?), see values.

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. G(k,1) is the partial of F (the prediction) with respect to ETA(1), and H(k,1) is the partial of F with respect to EPS(1). (HH may be coded instead of H, but it is treated as if it were H.) A variable of the form Gk1 or Hk1 is not a reserved variable. If it is previously defined (i.e., if it is listed in $INPUT, or used on the left in abbreviated code, or used as a synonym e.g., $TABLE G11=COM(1)), then that definition of the variable is used, and there is no change from previous versions of NM-TRAN. Only if there is no other previous definition of the variable will it be understood to be an element of G or H. What NM-TRAN actually displays is the variable in MODULE NMPRD4 that was used to compute the derivative of interest (a variable in the series A00nnn, C00nn, or D00nnn) with the appropriate synonym such as G11. If there is no such variable, this is an error. NMTRAN will not display variables that are not computed , e.g., G41 when there are only 3 etas in the problem, or when there are 4 etas but ETA(4) does not contribute to the value of Y. [There is a workaround if the zero is wanted as a place holder in the table. In abbreviated code ($ERROR or $PRED or $PK) G41=0 .

(See Displayed PRED-Defined Items).

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 superim-: posed 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 scatter-: plots. 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. If neither of ABS0 and NOABS0 is present, NONMEM automatically superimposes a zero line on the abscissa axis if it is appropriate for the type of data item.
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. The remaining options apply to all $SCATTERPLOT records.

NOSUB=[0|1]: With NOSUB=0, label substitution will be performed scatterpots. (See $ABBREVIATED). 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 2-9 points A-Z 10-35 points (A=10, B=11, … , Z=35) $ 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:

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 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 $SIGMA may be entered easily. 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”).

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 UNINT is used with NONMEM 7.5. UNINT is used during the Optimal Design Step to identify an eps 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 eps. This is the default.

Option STANDARD indicates that the initial estimate is understood to be a standard deviation of the eps. May also be coded SD.

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

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

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

FIXED indicates that the entire block is constrained to be fixed to its initial estimate.

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

VARIANCE indicates that all initial estimates given for diagonal elements are understood to be initial estimates of variances of eps. This is the default.

STANDARD indicates that all initial estimates given for diagonal elements are understood to be initial estimates of standard deviations of epsilons. May also be coded SD.

COVARIANCE indicates that all initial estmates given for off-diagonal elements are understood to be initial estimates of covariances of epsilons. This is the default.

CORRELATON indicates that all initial estmates given for off-diagonal elements are understood to be initial estimates of correlations of epsilons.

CHOLESKY indicates that 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. The values desplayed in the NONMEM report and in the raw and additional output files are always variances and covariances.

Examples:

The following describe the same block (within rounding errors): $SIGMA BLOCK(2) ; or $SIGMA VARIANCE COVARIANCE BLOCK(2) 0.64 -0.24 0.58 $SIGMA STANDARD BLOCK(2) 0.8 -0.24 0.762 $SIGMA STANDARD CORRELATION BLOCK(2) 0.8 -0.394 0.762 $SIGMA VARIANCE CORRELATION BLOCK(2) 0.64 -0.394 0.58 $SIGMA CHOLESKY BLOCK(2) 0.8 -0.3 0.7

x xx 0xx

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). E.g., $SIGMA BLOCK(2) SAME(3) is equivalent to $SIGMA BLOCK(2) SAME $SIGMA BLOCK(2) SAME $SIGMA BLOCK(2) SAME

$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. Other options (such as FIXED, CHOLESKY, VARIANCE,STANDARD,COVARIANCE,CORRELATON, UNINT) may follow VALUES or be placed between BLOCK and VALUES. E.g., $SIGMA BLOCK(6) VALUES(0.1,0.01) is the same as $SIGMA 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 sigma priors): $SIGMA BLOCK(6) FIX VALUES(0.15,0.0)

$SIGMA label=value (NM75)

The symbolic label substitution feature is new with NONMEM 7.5. This is a compact method of defining an EPS (an element of SIGMA) specifying its initial estimate, and specifying a label for the subscript for this element of SIGMA. The label may be used as a subscript for EPS in abbreviated code, and will also identify this element of SIGMA in the NONMEM output. If new $SIGMA records change the ordering, the abbreviated code does not have to be changed. For example, suppose the first element of SIGMA that is defined happens to be $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. The abbreviated code can use this symbolic subscript instead of the numeric subscript.

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.

Another example defines symbolic labels for a block of SIGMA:

$SIGMA BLOCK(2)
RSW=  0.3
EX=   0.01 0.35

Or, for diagonals,

$SIGMA
RSW= 0.3
EX= 0.35

$SIGMA BLOCK(n) NAMES (label1,…,labeln) VALUES (odiag,diag)

: {.nmtran} (NM75)

With NONMEM 7.5, Symbolic label substitution may be specified for an entire block using the NAMES option. This is a compact way of defining one or more epsilons with labels and, when combined with VALUES, with initial values. For example

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

This is equivalent to

$SIGMA BLOCK(2)
RSW=  0.03
EX=   0.01 0.03

If both are present, VALUES() must come after NAMES().

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:

$SIGMA 0.5 0.7 SCALE(2.0) 0.8 0.9 SCALE(1.5) 0.1 0.2

is equivalent to

$SIGMA 0.5 0.7 1.6 1.8 0.15 0.3

Other examples:

$SIGMAP SCALE(0.7) BLOCK(4) FIX VALUES(0.5,0.01)

is equivalent to:

$SIGMAP BLOCK(4) FIX VALUES(0.35,0.07)
$SIGMAP SCALE(0.7) BLOCK(4) FIX

0.5 0.01 0.5 SCALE(2.5) 0.02 0.02 0.003

Is equivalent to

$SIGMAP SCALE(0.7) BLOCK(4) FIX

0.5 0.01 0.5 0.05 0.05 0.0075

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. Rather than always re-calculate by hand, you can change the scale on the fly.

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

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. If a $ESTIM record does not appear, but a $SIMUL record appears, then unless the NOPREDICTION option appears on the $SIMUL record, etas are understood in the same way. 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 ICALL, Simulation Block). It is called a “simulation block”.

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, and the information coded within the parentheses defines the attributes of the source. The sources are ordered as they are defined on the $SIMUL record. The numbers from a source are explicitly available to the user via the NONMEM utility routine: RANDOM (See RANDOM). By default, the first source is earmarked for the simulation of etas and epsilons, and then the numbers from this source are not explicitly available to the user. However, see option SOURCE_EPS below.

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

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. It is understood that the etas are to be simulated from the nonparametric distribution rather than from the pseudo-normal distribution associated with the first source. The NONPARAMETRIC attribute can only be used in the definition of the second or subsequent source.

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 (next level-two record). That is, with NEW, a call to SIMETA will obtain new eta’s, even if ID has not changed. A call to SIMEPS will obtain new eps’s, even if L2 has not changed. The output NONMEM report describes this as “DIFFERENT ETA AND EPS WITH EACH CALL TO SIMETA AND SIMEPS”.

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. Also, see the PREDICTION and NOPREDICTION options.

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 all versions of NONMEM, the data set for each subproblem after the first is the same data set used by the previous subproblem, and includes any changes (transgeneration) made by the previous subproblem. With NONMEM 7.4 and higher, see REWIND, below. 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, either by NONMEM or by the user. However, the user may want the first-partial eta derivatives of a PRED-defined item and may want FIRSTEM to reflect this. With the REQUESTFIRST option, the FIRSTEM variable is set so to inform PRED that the derivatives need to be computed. In this case, if an abbreviated code is used to compute the PRED-defined item, the item should not be computed within a simulation block, because NM-TRAN does not provide derivatives for PRED-defined items in a simulation block.

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. Normally, during the Simulation Step, these derivatives are not needed, either by NONMEM or by the user. However, the user may want the second-partial eta derivatives of a PRED-defined item and may want the MSEC variable to reflect this. With the REQUESTSECOND option, the MSEC variable is set so to inform PRED that the derivatives need to be computed. In this case, if an abbreviated code is used to compute the PRED-defined item, the item should not be computed within a simulation block, because NM-TRAN does not provide derivatives for PRED-defined items in a simulation block. 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. E.g., if a line of code DV=… is used in a simulation block, be sure to follow this line with the additional line Y=DV.

NOPREDICTION

Permitted only with ONLYSIM. Indicates that the simulated observation will be taken to be the value to which the DV variable is set. The code Y=… is permitted inside or outside a simulation block, but if such code appears in a simulation block, be sure to also include e.g. DV=Y. 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 (“true 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. The UCP used with these other tasks are the same as with the previous run. 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. The UCP used with these other tasks are new, so that a UCP value of 0.1 now corresponds to a final estimate from the previous run.

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. See also $TTDF control record (NM75) to specify degrees of freedom for each theta. The value of TTDF overrides $TTDF See INTRODUCTION TO NONMEM 7, Simulating THETAS with t-Distribution

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 (which must already have legitimate DV values). 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. For example, if 400 subjects are in the simulation template data set, then 400 subjects are randomly selected. The random source is, in effect, uniform, because any subject is equally probable. If n is greater than the number of subjects, NONMEM will use the number of subjects. The BOOTSTRAP option in $SIML is most suitable for multi-subject data, in which there is an ID data column identifying the subjects. However, see the example “BOOTSTRAPPING SINGLE SUBJECT DATA” in the INTRODUCTION TO NONMEM 7.

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. The NOREPLACE feature is reasonable if there are many more than n subjects to choose from in the template dataset (for example, 1000 subjects in the template, and for each sub-problem, 50 of them are randomly chosen without replacement, that is, without repeating a subject).

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 in the base 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 subproblem, 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. If the data set is not changed during simulation, the NOREWIND and REWIND options give the same results.

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.   For
example:
$INFN
IF (ICALL==1) THEN
DOWHILE(DATA)
 ... data transgeneration statements here
ENDDO
ENDIF

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 superproblem, 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, so that each iteration serves as a new random instance.

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, that is nearly uniform distribution, with good mixing in multi-dimensional spaces. As of NONMEM 7.4, RANMETHOD will also act on the P modifier , which will retain separate seed sequences for each subject, so that the random variable patterns are retained regardless of whether the simulation is done in single computing or parallel computing mode. (See $ESTIMATION).

PARAFILE=filename

As of NONMEM 7.4, the Simulation Step computation may be parallelized. by default. By default, parallelization is not turned on, because simulation is very rapid anyway, and often does not need to be accelerated. When modeling with super-ID nested ETA levels ($LEVEL record is present), parallelization will not occur, since these etas are shared across individuals, and there is no guarantee that all subjects sharing the same etas will be simulated by the same process. PARAFILE=filename specifies a different parafile than was used for the previous step. PARAFILE=ON turns on parallelization for the Simulation Step. Set RANMETHOD=P to permit assure consistient 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 SIZES FSIZES prsizes)

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 SIZES FSIZES prsizes)

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 ..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, semi-colons, 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 ss_option). 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 Problem_Iteration_Counters).

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 etaepsilon 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 etaepsilon interaction. Always same as PRED, RES, and WRES. CPRED, CRES, CWRES Calculated assuming conditional estimation and no etaepsilon 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.

In addition the list may include:

Data item labels.

Labels ETA(1), ETA(2), … ,ETA(10), … , ETA(70), etc., or alternatively, labels ETA1, ETA2, … ,ETA10, … , ETA70, 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: 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 $ABBREVIATED). 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.

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, corresponding to VECTRA(1), VECTRA(2),
   ..., VECTRA(9).
   The labels in the output will be VA_1, VA_2, ... , VA_9.
   Similarly, for VECTRB and VECTRC.

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

For a discussion of the values of ETAs and PRED-defined items (e.g., are they based on initial or final values of theta? Simulated or zero or conditional values of eta?), see values.

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, 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. G(k,1) is the partial of F (the prediction) with respect to ETA(1), and H(k,1) is the partial of F with respect to EPS(1). (HH may be coded instead of H, but it is treated as if it were H.) A variable of the form Gk1 or Hk1 is not a reserved variable. If it is previously defined (i.e., if it is listed in $INPUT, or used on the left in abbreviated code, or used as a synonym e.g., $TABLE G11=COM(1)), then that definition of the variable is used, and there is no change from previous versions of NM-TRAN. Only if there is no other previous definition of the variable will it be understood to be an element of G or H. What NM-TRAN actually displays is the variable in MODULE NMPRD4 that was used to compute the derivative of interest (a variable in the series A00nnn, C00nn, or D00nnn) with the appropriate synonym such as G11. If there is no such variable, this is an error. NMTRAN will not display variables that are not computed , e.g., G41 when there are only 3 etas in the problem, or when there are 4 etas but ETA(4) does not contribute to the value of Y. [There is a workaround if the zero is wanted as a place holder in the table. In abbreviated code ($ERROR or $PRED or $PK) G41=0. Now G41 may be listed in $TABLE or $SCATTER.] This feature is designed so that the verbatim code in the “compute.cwres” R documentation is unnecessary.

E.g., Instead of:

$ABB COMRES=5
"LAST
"  COM(1)=G(1,1)
"  COM(2)=G(2,1)
"  COM(3)=G(3,1)
"  COM(4)=HH(1,1)  (or H(1,1) with $PRED)
"  COM(5)=HH(2,1)  (or H(2,1) with $PRED)
$TABLE ID COM(1)=G11 COM(2)=G21 COM(3)=G31
 COM(4)=H11 COM(4)=H21

IPRED MDV NOPRINT ONEHEADER FILE=cwtab1 Use only: $TABLE ID G11 G21 G31 H11 H21 IPRED MDV NOPRINT ONEHEADER FILE=cwtab1

(See Displayed PRED-Defined Items).

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. That is, a table with more than 8 data items also may not be sorted.
NOSUB=[0|1]: With NOSUB=0, label substitution will be performed for final estimates in table files. (See $ABBREVIATED). This is the default. With NOSUB=1, label substitution will not be performed.
list3: A list comprised of one or more items that are permitted in list1, e.g., data item labels and labels of PRED-defined items in MODULE NMPRD4. 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. Exclusion variables are not listed in the table file. They have no effect on the printed table or scatters in the NONMEM output, e.g., they do not cause any rows to be deleted from the printed table and are displayed in the printed table.
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=filename specifies a different parafile than was used for the previous step. PARAFILE=ON turns on parallelization for the weighted residuals. PARAFILE=OFF turns off parallelization for the weighted residuals. 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. This can speed up the Table Step when there are a large number of observations per individual.
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. 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.
RANMETHOD=[n|S|m]: n: the random number generator used for the Monte-Carlo simuations of weighted residual items. 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 sequence m: the type of scrambling desired 0: no scrambing (S0 is the same as S) 1: Owen type scrambling 2: Faure-Tezuka type scrambling 3: Owen plus Faure-Tezuka type scrambling. See the description of RANMETHOD for $ESTIM. Among the Sobol sequence methods, the S2 method appears to provide the least biased random samples, that is nearly uniform distribution, with good mixing in multi-dimensional spaces. See INTRODUCTION TO NONMEM 7, Reference [5] See INTRODUCTION TO NONMEM 7, Monte Carlo Importance Sampling EM 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. If it contains commas, semi-colons, 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. Filename may contain at most 71 characters. If filename is the same as any option of the $TABLE record, it must be enclosed in quotes. Filename can differ between $TABLE records. 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. However, when there are multiple $TABLE records within the same problem and having the same filename, the situation is a little more complicated; see the text describing the FORWARD option.
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 (i.e., user-chosen item types) 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. If items PRED, RES, and/or WRES are explicitly coded in list1, then they appear in the table, exactly as listed. (Previously to NONMEM VI 2.0, they could be included in the list, but were suppressed from the portion of the table described by list1 in favor of the automatically-generated items.)
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. For more details, see the format help item: (See format). Alternately, use LFORMAT and/or RFORMAT. See INTRODUCTION TO NONMEM 7, FORMAT=s1PE11.4
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. Both LFORMAT and RFORMAT affect table files until a different format is specified. Use LFORMAT="NONE" or RFORMAT="NONE" to resume use of the default format (which may have been specified by the FORMAT option) 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. If using RFORMAT formatting option, make sure to allow enough format fields to include reported standard errors. In addition, full variances-covariances among all user-defined variables and PREDPP parameters will be outputted to file root.vpd (the FORMAT used for this file is that defined in the $EST statement). 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. This option must be re-coded for each $TABLE record for which SE’s are wanted. If VARCALC=1 or 2 or 3 is requested at least once among any of the tables, then the variance items are written to the vpd and vpt files. VARCALC=0 requests neither SE’s nor vpd nor vpt, and is the default. Values of COMACT, which identify copying passes, may need to be tested in abbreviated code when this feature is used. See INTRODUCTION TO NONMEM 7, Requesting Standard Errors to UserDefined and PREDPP Parameters
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. In this way, the PRED evaluated will be, not of the total population, but of a given site level for that subject. List is a number-list of etas. For example, FIXEDETAS=(3-6) A number-list may contain a single integer, a range of integers (with -), or a series of integers and ranges separated by comma.
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. For example, by default, if the EXAMPLE=300, and a quantile position is 0.001, then the 1/300 value is returned, the lowest value from 300 samples. With INTERPTYPE=1, an extrapolation is performed to better represent the 0.001 value, and will be less than the lowest value among 300 samples simulated. The INTERPTYPE has less impact with increasing ESAMPLE.
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, in which case this form differs from the one described above only in so far as with this form, the initial estimate and the FIXED attribute are enclosed in parentheses. 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”). The values within the parenthesis may have any of the above forms. 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 assigment 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 diffently 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. 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 nwpri).

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 assigment 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 diffently 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 tdistribution 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 `$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.

 Option                   Classical   ITS   DIRECT   IMP   IMPMAP   SAEM   BAYES   NUTS
 -2LL                     X           X     X        X     X        X      X       X
 ATOL +                   X           X     X        X     X        X      X       X
 AUTO                                 X     X        X     X        X      X       X
 BAYES_PHI_STORE                                                           X       X
 BIONLY                                                                    X       X
 BOOTDATA                 X           X     X        X     X        X
 CALPHA                               X     X        X     X        X      X       X
 CENTERING                X
 CINTERVAL                            X     X        X     X        X      X       X
 CITER/CNSAMP                         X     X        X     X        X      X       X
 CLOCKSEED                                  X        X     X        X      X       X
 CONDITIONAL              X           X     X        X     X        X      X       X
 CONSTRAIN                            X     X        X     X        X      X       X
 CTYPE                    (CTYPE 4)   X     X        X     X        X      X       X
 DERCONT                                    X        X     X        X
 DF                                                  X     X
 DFS(CHAIN only)
 EONLY                                      X        X     X        X
 ETABARCHECK              X
 ETADER                   X           X              X     X
 ETASAMPLES                                                         X      X       X
 ETASTYPE                 X           X     X        X     X        X
 EVALSHRINK               X
 FAST                     X           X
 FILE                     X           X     X        X     X        X      X       X
 FNLETA                   X           X     X        X     X        X      X       X
 FORMAT/DELIM             X           X     X        X     X        X      X       X
 FPARAFILE                X           X     X        X     X        X      X       X
 Option                   Classical   ITS   DIRECT   IMP   IMPMAP   SAEM   BAYES   NUTS
 GRD                                  X     X        X     X        X      X       X
 GRDQ                                                X     X
 GRID(Stieltjes)          X
 HYBRID                   X
 IACCEPT                                             X     X        X      X       X
 IACCEPTL                                            X     X
 IKAPPA                                                                            X
 INTERACTION              X           X     X        X     X        X      X       X
 ISAMPEND                                   X        X     X        X
 ISAMPLE                                                            X      X       X
 ISAMPLE_M1                                                         X      X       X
 ISAMPLE_M1A                                                        X      X       X
 ISAMPLE_M1B                                                        X      X       X
 ISAMPLE_M2                                                         X      X       X
 ISAMPLE_M3                                                         X      X       X
 ISCALE_MAX                                          X     X        X      X       X
 ISCALE_MIN                                          X     X        X      X       X
 KAPPA                                                                             X
 KNUTHSUMOFF              X           X     X        X     X        X      X       X
 LAPLACE                  X           X     *        *     X        *      *       *
 LEVCENTER(for $LEVEL)    X           X     X        X     X        X      X       X
 LEVOBJTYPE(for $LEVEL)   X           X     X        X     X        X      X       X
 LEVWT (for $LEVEL)       X           X     X        X     X        X      X       X
 LIKE                     X           X     X        X     X        X      X       X
 LNTWOPI                  X           X     X        X     X        X      X       X
 Option                   Classical   ITS   DIRECT   IMP   IMPMAP   SAEM   BAYES   NUTS
 MADAPT                                                                            X
 MAPCOV                                              X     X
 MAPINTER                                            X     X
 MAPITER                                             X     X
 MAPITERS                                                           X      X
 MASSRESET                ***                                              X
 MAXEVAL                  X
 MCETA                    X           X              X     X
 MSFO                     X           X     X        X     X        X      X       X
 MUM                                  X     X        X     X        X      X       X
 NBURN                                                              X      X       X
 NITER/NSAMPLE                        X     X        X     X        X      X       X
 NOABORT                  X           X     X        X     X        X      X       X
 NOCOV**                              X     X        X     X        X      X       X
 NOHABORT                 X           X     X        X     X        X      X       X
 NOLABEL                  X           X     X        X     X        X      X       X
 NONINFETA                X
 NOOMEGABOUNDTEST         X
 NOPRIOR                  X           X     X        X     X        X      X       X
 NOSIGMABOUNDTEST         X
 NOSLOW                   X           X
 NOSUB                    X           X     X        X     X        X      X       X
 NOTHETABOUNDTEST         X
 NOTITLE                  X           X     X        X     X        X      X       X
 NSIG/SIGDIGITS           X           X
 NUMDER                   X           X     X        X     X        X      X       X
 NUMERICAL                X           X     *        *     X        *      *       *
 Option                   Classical   ITS   DIRECT   IMP   IMPMAP   SAEM   BAYES   NUTS
 NUTS_BASE                                                                         X
 NUTS_DELTA                                                                        X
 NUTS_EPARAM              ***                                              X
 NUTS_GAMMA                                                                        X
 NUTS_INIT                                                                         X
 NUTS_MASS                ***                                              X
 NUTS_MAXDEPTH                                                                     X
 NUTS_OPARAM              ***                                              X
 NUTS_REG                 ***                                              X
 NUTS_SPARAM              ***                                              X
 NUTS_STEPINTER                                                                    X
 NUTS_STEPITER                                                                     X
 NUTS_TERM                                                                         X
 NUTS_TEST                                                                         X
 NUTS_TRANSFORM                                                                    X
 Option                   Classical   ITS   DIRECT   IMP   IMPMAP   SAEM   BAYES   NUTS
 OACCEPT                                                                   X       X
 OLKJDF                                                                            X
 OLNTWOPI                                                           X      X       X
 OMEGABOUNDTEST           X
 OMITTED                  X           X     X        X     X        X      X       X
 OPTMAP                   X           X              X     X
 ORDER                    X           X     X        X     X        X      X       X
 OSAMPLE_M1                                                                X       X
 OSAMPLE_M2                                                                X       X
 OSAMPLE_M3                                                                X       X
 OVARF                                                                             X
 PACCEPT                                                                   X       X
 PARAFILE                 X           X     X        X     X        X      X       X
 PARAFPRINT               X           X     X        X     X        X      X       X
 PHITYPE                              X     X        X     X        X      X       X
 POSTHOC                  X           X     X        X     X        X      X       X
 PREDICTION               X           X     X        X     X        X      X       X
 PRINT                    X           X     X        X     X        X      X       X
 PRIORC                   X           X     X        X     X        X      X       X
 PSAMPLE_M1                                                                X       X
 PSAMPLE_M2                                                                X       X
 PSAMPLE_M3                                                                X       X
 PSCALE_MAX                                                                X       X
 PSCALE_MIN                                                                X       X
 RANMETHOD=nSmP                             X        X     X        X      X       X
 Option                   Classical   ITS   DIRECT   IMP   IMPMAP   SAEM   BAYES   NUTS
 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
 SIGLO                    X           X              X     X
 SIGMABOUNDTEST           X
 SLKJDF                                                                            X
 SLOW                     X           X
 SORT                     X
 STDOBJ                                              X     X
 STIELTJES                X
 SVARF                                                                             X
 TBLN(CHAIN only)
 THETABOUNDTEST           X
 THIN                                                                      X       X
 TPU                                                                               X
 TTDF                                                                              X
 ZERO                     X
 Option                   Classical   ITS   DIRECT   IMP   IMPMAP   SAEM   BAYES   NUTS

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

REFERENCES: Guide Introduction_7

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

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

56 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-offile 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. one

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

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

DISCUSION:

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

9 $DATA

10 $DEFAULT

11 $DES

12 $DESIGN (NM75)

13 $ERROR

14 $ESTIMATION, $ESTM

15 $ETAS, $PHIS

16 $FORMAT

17 $INDEX, $INDXS

18 $INFN

19 $INPUT

20 $LDFOLD

21 $LEVEL

22 $MIX

23 $MODEL

24 $MSFI

25 $NONPARAMETRIC

26 $OLKJDF

27 $OMEGA

28 $OMEGAP, $OMEGAPD

29 $OMIT

30 $DESIGN (NM75)

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 $ESTIMATION RECORD OPTIONS

55 FORMAT

56 INCLUDE

57 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`, `$ESTM`

15 `$ETAS`, `$PHIS`

16 `$FORMAT`

17 `$INDEX`, `$INDXS`

18 `$INFN`

19 `$INPUT`

20 `$LDFOLD`

21 `$LEVEL`

22 `$MIX`

23 `$MODEL`

24 `$MSFI`

25 `$NONPARAMETRIC`

26 `$OLKJDF`

27 `$OMEGA`

28 `$OMEGAP`, `$OMEGAPD`

29 `$OMIT`

30 `$DESIGN` (NM75)

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 `$ESTIMATION` RECORD OPTIONS