53 User-written FORTRAN Routines

Abbreviated code, reserved variables in user code, blocks within $PRED/$PK/$ERROR/$INFN.

1 ABBREVIATED CODE

MEANING: FORTRAN-like statements

CONTEXT: Abbreviated code

SAMPLE:

$PK CL = THETA(1) + ETA(1)

DISCUSSION:

Abbreviated code is FORTRAN-like language within an NM-TRAN control stream that is used to specify a model. The $PRED, $PK, $ERROR, $DES, $AES, $AESINITIAL, $TOL, $MIX, and $INFN records each begin a block of abbreviated code. Such a block ends with either the appearance of another record beginning with a $, or with the absence of any further records in the control stream.

The general rules are:

One statement of abbreviated per line, starting anywhere on the line.
No statement numbers (unlike with FORTRAN).
Comments may be included on any line after the semicolon character ;.
No statement types other than assignment, IF, THEN, ELSE, ELSEIF, ENDIF, DO WHILE, ENDDO, CALL, WRITE, PRINT, RETURN, OPEN, CLOSE, REWIND. (e.g., no GOTO, READ, FORMAT.)
With NONMEM 7.2 and higher, both lower and upper case may be used for all user-defined and reserved words.
Continuation lines are permitted using the character & at the end of the line.
A special statement type, EXIT, is permitted.

IF / ELSE spelling variants accepted by NM-TRAN

Verified against NONMEM 7.6.0 — the parser accepts Fortran-90 two-word forms in addition to the NM-TRAN one-word forms listed in the grammar above. All four permutations parse and execute identically:

Else-if: ELSEIF (cond) THEN (NM-TRAN canonical) or ELSE IF (cond) THEN (F90 form).
Closer: ENDIF (NM-TRAN canonical) or END IF (F90 form).
Forms may be mixed freely within the same block.

IF (K == 1) THEN
   Y = 10
ELSEIF (K == 2) THEN   ; or: ELSE IF (K == 2) THEN
   Y = 20
ELSE
   Y = 30
ENDIF                  ; or: END IF

This HTML edition prefers the canonical one-word forms (ELSEIF, ENDIF) and the F90 symbolic relational operators (== /= < <= > >=) for consistency.

ASSIGNMENT STATEMENTS

An assignment statement (A=B) uses right-hand quantities in an expression B in order to define a quantity A.

Permissible right-hand quantities are:

previously defined quantities, including declared variables that have also been used on the left side of an assignment statement. (See Section 50.1).
constants, e.g 1, 1.1, 3E+1 3E1, 3E01, 3E-1 3E-01, 3D+1, 3D1, 3D01, 3D-1 3D-01
THETA, OMEGA and SIGMA elements, e.g. THETA(1), OMEGA(2,2). When the two subscripts for an OMEGA or SIGMA element are the same, only one subscript is needed, e.g. OMEGA(2).
labels of data items defined in the $INPUT record
variables ETA(n), EPS(n), ERR(n), which are understood to have mean 0 and variances and covariances given by elements of the OMEGA and SIGMA arrays.
operators + - * / **
parentheses ()
built-in functions: LOG (natural log), LOG10, EXP, SQRT, SIN, COS, ABS, TAN, ASIN, ACOS, ATAN, INT, MIN, MAX, MOD
NONMEM functions: PHI, GAMLN

FORTRAN functions may have random variable arguments and the appropriate partial derivatives are computed. The partial derivative of ABS(X) with respect to η is mathematically undefined at X=0. We are arbitrarily defining it to be dX/deta. If the prediction depends on X, X must always be either positive or negative. If the argument of GAMLN is a random variable, it must always be positive. Function PHI may have a random argument but no partial derivates are computed.

The INT, MOD, MIN, and MAX functions produce discontinuous results. No partial derivatives are computed. If they are used outside of a simulation block and the function value affects the value of the objective function, then an error in the NONMEM Estimation Step will probably occur. If they are needed in the computations of DADT (differential equations; with ADVAN 6, 8, 9, 13, 14, 15, 16, 17, 18), then the functions should be used instead in the PK routine, and model event time (MTIME) parameters be used to set flags for DES. (See Section 60.39) (See Cirdadian example)

Other permissible quantities: abbreviated functions (See below), subscripted variables (See below).

With previous versions of NONMEM, constants were limited to 12 characters. With NONMEM 7 a constant may be up to 30 characters. (The length is specified by constant SCO in SIZES)

Further information about Assignment statements:

Parentheses may be nested in the right-hand side of an assignment statement.

Except in certain blocks of abbreviated code (i.e. a simulation block, an initialization block, a finalization block or a pred_ignore_data block), the variables ETA(n), EPS(n), ERR(n) are considered to be (the base) random variables, and quantities defined in terms of these variables (directly or indirectly) are themselves considered to be random variables. NM-TRAN sets up computations for derivatives of random variables with respect to the base random variables.

Left-hand variables that have no reserved meaning are called user-defined variables. With previous versions of NONMEM they were restricted to 8 characters in length and could not include the character _. With NONMEM 7 a user-defined variable name consists of 1-20 letters (A-Z), numerals (0-9), and the character _, beginning with a letter. (The length 20 is specified by constant SD in SIZES) (See Section 50.41).

With NONMEM 7, variables MU_1, MU_2, etc., are reserved and are used for mu modelling. See INTRODUCTION TO NONMEM 7, MU Referencing (See Section 53.60).

Left-hand quantities VECTRA(n), VECTRB(n), VECTRC(n) may be defined, and these become elements of pre-defined vectors VECTRA, VECTRB, VECTRC. If VECTRA, VECTRB, VECTRC is defined without a subscript, it is understood to be a simple variable. A subscript must be an integer constant, or a character string that is replaced by an integer constant using the $ABBR REPLACE feature. Whereas once it is defined, a vector element may be used as a right-hand quantity, the vector itself may be used only as an argument to an abbreviated function.

(See VECTORS and ABBREVIATED FUNCTIONS, below.)

Values may be assigned to certain special variables: RPTO, RPTON and PRDFL - with the repetition feature (See Section 53.94); SKIP_ (but only in a finalization block) - with superproblems or subproblems (See Section 53.103).

Variables, constants, and functions are all of double precision floating point type. (E.g., K=.5 gives K the value .5, not 0 as it would be under the FORTRAN convention that K is integer type.)

Except in certain blocks of abbreviated code (i.e. a simulation block, an initialization block, or a finalization block), a label in an $INPUT record may not appear on the left in an assignment statement.

There is a reserved storage area of module NMPRD4, and when defining the kth variable in this area, it may be referenced as COM(k). Then, even if the variable is defined in terms of random variables, it is not regarded as being a random variable; derivatives of COM(k) with respect to the base random variables are not computed.

CONDITIONAL STATEMENTS

Conditional statements have one of two forms:

IF (condition) assignment statement

IF (condition) THEN
 abbreviated code ...
ELSEIF (condition) THEN
 abbreviated code ...
ELSE
 abbreviated code ...
ENDIF

See below for a restriction on ELSEIF. Conditions may include the operators .EQ., .NE., .LE., .GE., .LT., .GT., .AND., .OR.. The arithmetic operators may be coded as ==, /=, <=, >=, <, >, respectively. They may include expressions that can be used as right-hand quantities with assignment statements. They may not include parentheses except in such expressions.

Valid: IF (Q.EQ.(R+C)/D) ... Invalid: IF (Q.EQ.R.AND.(C.GT.D.OR.E.EQ.F)) ...

With $PRED, $PK, and $ERROR records, a condition may test the ICALL argument. However, if the test is IF (ICALL.EQ.2), then ELSE may not be used.

A condition may also test certain variables defined in modules (See Section 53.111, Section 53.65, Section 53.85).

Abbreviated code in a particular THEN or ELSE clause may not contain multiple definitions of the same random variable. Random variables cannot be defined within nested conditionals. The use of ELSEIF ... THEN implies a nested conditional.

A special rule applies when random variables are defined via conditional statements. If a random variable is multiply defined within a series of IF ... THEN structures, but all conditions are false, then the value of the random variable is set to zero. If an ELSE appears, then not all conditions are false.

IF (WT > 0) TVK = THETA(1) * WT

If the condition is false, the non-random variable TVK retains the value set with the previous data record.

IF (WT > 0) K = THETA(1) * WT * EXP(ETA(1))

If the condition is false, the value of the random variable K is set to zero. NM-TRAN prints a warning message when it detects such code.

In $PK, $ERROR, and $PRED records, recursion code may be used in an explicit manner, as in this example:

IF (WT > 0) THEN
 K = THETA(1) * WT * EXP(ETA(1))
ELSE
 K = K
ENDIF

If the condition is false, K retains its value set with the previous data record.

Recursion code can be used in $PRED, $PK, and $ERROR records for other purposes as well. The following two fragments of code illustrate how one can use abbreviated code to implement recursive kinetics in $PRED:

K = THETA(1) * EXP(ETA(1))
IF (TIME == 0) THEN
 OLDA = AMT
 T = TIME
ENDIF
A = OLDA * EXP(-K * (TIME - T))

OLDA = A
T = TIME

K = THETA(1) * EXP(ETA(1))
IF (TIME == 0) THEN
 A = AMT
 T = TIME
ELSE
 A = A * EXP(-K * (TIME - T)) + AMT
ENDIF
T = TIME

The above forms of recursion work for recursion from one data record to the next (“inter-record” recursion). It is also possible to use recursion in a do-while loop (“intra-record”, or “do-while” recursion).

Example of a do-while recursive loop using a random variable:

TERM = THETA(1) * EXP(ETA(1))
SUM = 0
DO WHILE (condition)
 SUM = SUM + TERM
 ...
ENDDO

A product loop such as PROD=PROD*TERM is also possible, as are other ways the dowhile recursive variable can be used, so long as the variable appears on both sides of the equal sign within the DOWHILE loop: V= ... V ....

EXIT STATEMENT

The exit statement has three forms:

EXIT
EXIT n
EXIT n k

n is called the “PRED error return code”; (also called the “PRED exit code.”). It must be 1 or 2. Default is 1. k is the user error code. It may be omitted; if present, it must be integer-valued in the range 0-999. With NONMEM 7.5, it may also be in the range 1000-9999 when issued during the Simulation Step. Default is 0.

With all versions of NONMEM, the value of k is part of the error message in ETEXT, which is reported in the NONMEM output report and in file PRDERR. With NONMEM 7.5 and later, k tells NONMEM how to handle EXIT statements during the Simulation Step. (See Section 53.96). (See nmprd1)

The EXIT statement causes an immediate exit from the routine and, if PREDPP is being used, a subsequent immediate exit from PREDPP, with a return to NONMEM. It is typically used in an IF statement to avoid further computation of the users code when the values of theta/eta’s set by NONMEM are inappropriate or would lead to an arithmetic exception. If such an exit occurs during a Covariance, Table or Scatterplot Step, or during computation of the initial value of the objective function, NONMEM will abort. If the exit occurs during an Estimation or Initial Estimates Step, NONMEM’s action depends on the error return code value:

n=1 Suppose first that a search for eta is not underway. Then a search for theta is underway, and when a search is underway for theta, the following happens: If the NOABORT option is used, NONMEM will try to continue using different values for theta (i.e. “theta-recovery”); otherwise, NONMEM aborts. If theta-recovery fails, NONMEM aborts. Next, suppose a search for eta is underway. NONMEM will try to continue using different values for eta (i.e. “eta-recovery”). Suppose eta-recovery fails. If a search for theta is not also underway, NONMEM aborts. Otherwise, the above procedure regarding theta-recovery applies. (See Guide VI, section III.K)

n=2 NONMEM aborts immediately.

If NONMEM aborts, and k>0, a user message such as the following is printed in the output:

"PK SUBROUTINE: USER ERROR CODE = k"

This message is intended to help the user distinguish which EXIT statement caused NONMEM to abort when more than one EXIT statement is present in the abbreviated code.

WRITE AND PRINT STATEMENTS

(See Section 53.114).

SPECIAL STATEMENTS

Optional. Each of these special statements is permitted in special blocks of abbreviated code. (See Section 53.46, Section 53.96). (See Section 53.40, Data_Average block). (See Data_ingnore block).

CALL PASS(MODE): Must be coded exactly as shown. May be used only in $PRED initialization-finalization blocks, and in $INFN records. If present, MODE becomes a reserved variable with type INTEGER, and may not be used outside the block(s).
CALL SUPP(ie,ic): Must be coded as shown, with constant integer values 0 or 1 in place of ie and ic. A value 1 for ie (ic) suppresses output from the Estimation (Covariance) step. A value 0 does not suppress the output from the step. May be used only in $PRED initialization-finalization blocks, and in $INFN records. The ie (ic) value remains in force until changed by a call to SUPP.
CALL RANDOM(n,R): Must be coded as shown, with a constant integer value 1-10 in place of n. The value is the number of the random source. R is a random number from this source. May be used only in Simulation and Expectation blocks.
CALL SIMETA(ETA): Must be coded exactly as shown. May only be used in Simulation blocks. Note that NM-TRAN itself provides the minimum necessary call to SIMETA. This statement is used in abbreviated code only to obtain a different value of ETA, e.g., so that the eta distribution may be truncated:

DO WHILE (ETA(1) > 5)
 CALL SIMETA(ETA)
ENDDO

CALL SIMEPS(EPS): Must be coded exactly as shown. May only be used in Simulation blocks. Note that NM-TRAN provides the minimum necessary call to SIMEPS. This statement is used in abbreviated code only to obtain a different value of EPS, e.g., so that the distribution may be truncated (See SIMETA above).
DO WHILE ( condition ): With NONMEM 7, DOWHILE may be used in all blocks of abbreviated code. DOWHILE marks the beginning of a set of statements that are executed repeatedly until the condition is false. The ending of the set of statements is marked by the statement ENDDO. The non-FORTRAN syntax DO WHILE (DATA) is permitted in $PRED initialization and finalization blocks, and in the $INFN record. (See Section 53.46).
RETURN: May be used in all special blocks. RETURN statements must be used with caution because they by-pass certain normal final actions of the routine.

Another kind of special block is the pred_ignore_data block, which may be part of $PRED, $PK, or $INFN blocks. It uses the reserved variables PRED_IGNORE_DATA_TEST and PRED_IGNORE_DATA. By setting values of PRED_IGNORE_DATA=1 for certain data records, it causes these records to be dropped from the NONMEM data set. Ordinary Fortran syntax is used in such blocks. (See PRED_IGNORE_DATA block) (See Guide Introduction_7 “Extension to $DATA IGNORE=st filtering”)

VECTORS and ABBREVIATED FUNCTIONS

Reserved variable names VECTRA, VECTRB, VECTRC, etc. may be used for pre-defined vectors. elements. Elements can be defined in any order.

Vectors that are defined outside of $DES (or $AES) may not be used in the $DES (or $AES) code. I.e., a vector may not be an implicit basic PK parameter.

If FUNCA, FUNCB, FUNCC, etc. is defined without a subscript, it is understood to be a simple variable, and then it may appear as such as a right-hand quantity. If FUNCx appears for the first time as a right-hand quantity, it is understood to be the reserved name of an abbreviated function, and then it must include a single argument, e.g. FUNCA(VECTRA)) or FUNCA(THETA(1)). Complete FORTRAN code for an abbreviated function is supplied by the user (See Section 53.2).

The argument of an abbreviated function may be any expression that can be used in an assignment statement (possibly involving explicit vector elements), or it can be simply a vector. In the latter case, any VECTR may be used with any FUNC, e.g. X=FUNCA(VECTRB).

With NONMEM VI 2.0: Function names may be FUNCA through FUNCC. Reserved argument vector names may be VECTRA through VECTRC. A given reserved function may have at most 9 elements in the argument vector, and may appear in abbreviated code at most 9 times.

With NONMEM 7.3: Function names may be FUNCA through FUNCI, and constant NFUNCX in SIZES may be used to increase the number. Reserved argument vector names may be VECTRA through VECTRC.

With NONMEM 7.4: Function names may be FUNCA through FUNCZ. Reserved argument vector names may be VECTRA through VECTRZ. 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. A reserved function may appear in abbreviated code more than 9 times.

The $ABBR FUNCTION and $ABBR VECTOR feature allows the user to declare the names of user-defined functions and the names and sizes of user-defined argument vectors. Restrictions such as the number of user functions, the number of elements in a vector, and the number of times a given function may appear in abbreviated code are more flexible and may be modified by the user. (See Section 50.1). (See Section 53.2).

PSEUDO ASSIGNMENT STATEMENTS

Pseudo-assignment statements are optional and provide certain special instructions. If present, they must appear (in any order) at the beginning of a record, before the rest of the essential abbreviated code comprising that record. They may be enclosed in parentheses, but two or more pseudo-assignment statements enclosed by parentheses must be separated by a semicolon ;. The following pseudo-statement may be used in all records except $MIX.

COMRES=-1: All quantities defined in abbreviated code are to be stored locally; they are not to be stored in the (global) MODULE NMPRD4. (Variables in MODULE NMPRD4 can be used for communication between various user-routines, and can be displayed in tables and scatterplots.)

See the entries for specific records for information about pseudo-assignment statements special to those records.

RESERVED VARIABLE NAMES

Reserved variable names include names of those variables that have special meaning for the user, as well as names of variables that are used internally by NM-TRAN. Entries for $PRED, $PK, $ERROR, $DES, $AES, $AESINITIAL, and $TOL describe the reserved variable names for these abbreviated codes.

A variable name that is reserved in an abbreviated code may not be used as the name of a variable defined in this code, or in any other abbreviated code unless the pseudo-assignment statement COMRES=-1 is used (in some code). If a reserved variable name is inappropriately used, NM-TRAN will generate an error message.

The following names are reserved in all abbreviated codes for internal use by NM-TRAN:

Names of modules and of variables in the modules (See Section 53.111).
GETETA SIMETA SIMEPS
COMSAV NWIND ETEXT IERPRD IERPRDU MSEC MFIRST NETEXT
ETA1-ETA9, ETA10-ETA99
Annnnn Bnnnnn Cnnnnn Dnnnnn Ennnnn Fnnnnn Pnnnnn Qnnnnn
MCnnnn MEnnnn MGnnnn MTnnnn
(where nnnnn is numeric 00000-99999, and nnnn is numeric 0000-9999)

SUBSCRIPTED VARIABLES

Subscripts may be used with user-defined variables that are declared to be arrays using the $ABBR DECLARE record, and also with certain reserved variables:

THETA, THETAFR, SETHET, THSIMP, SETHETR, THSIMPR
OMEGA, OMEGAF, SEOMEG, OMSIMP
SIGMA, SIGMAF, SESIGM, SGSIMP
CNTID, IIDX
CDEN_
A, A_0 (when used in a WRITE or PRINT statement)
ETA, EPS, ERR (when used in a WRITE OR PRINT statement)

Where a subscript is permitted or necessary, it may be an integer expression. An integer expression is an integer constant, a declared integer variable that has appeared on the left (i.e., has been given a value), a constant defined in SIZES, an expression involving integer constants and integer variables and arithmetic operators +, -, *, /, **. It may also be a character string that is replaced by an integer expression using the $ABBR REPLACE feature. The number of subscripts must be equal to the number of dimensions. If there are two subscripts, either or both may be constants or expressions. If a subscripted variable may be used on the left side, then the subscript may also be an integer expression. E.g.,

$ABBR DECLARE INTEGER IND
...
$PK
IND = 1
X = THETA(IND + 1)

With reserved random variables such as ETA(n) EPS(n) ERR(n) A(n) A_0(n) integer expressions may be used only if they are listed in WRITE or PRINT statements. Otherwise n must be an integer constant, or a character string that is replaced by an integer constant using the $ABBR REPLACE feature.

NONMEM RESERVED VARIABLES

There are many variables that are generally internal to NONMEM, and often are not needed by users except occasionally, which are not explicitly recognized by NMTRAN, and so cannot be used in abbreviated code, but must be used with verbatim code (" at beginning of line). A convenient means of accessing such variables, as well as letting NMTRAN allow you to use the variables in abbreviated code is to place the MODULE definitions in an include file that begins with the name NONMEM_RESERVED (case insensitive). Insert include statements for such files at the beginning of the block(s) of abbreviated code in which you want to use them. The user may use any of these variables without using verbatim code. NMTRAN “reads” the nonmem_reserved file, and remembers the variables declared in there as acceptable to use.

A list of useful variables and their meanings are listed in ..\guides\useful_variables.pdf. Be careful in their use, as you have the ability to change the values of these reserved variables, and this could crash the system if you change the wrong thing.

NONMEM_RESERVED_GENERAL in the ..\util directory has a few of the quite useful variables listed. It needs to be copied to the present run directory so that NM-TRAN has access to it. Note that there may be user-defined variable names in the control stream that inadvertently have the same names as variables in NONMEM_RESERVED_GENERAL, which may cause compiler errors. If so, make a smaller version of NONMEM_RESERVED_GENERAL with a name also starting with NONMEM_RESERVED that contains only those reserved variables of interest.

As an example, NONMEM_RESERVED_GENERAL contains:

" USE NMBAYES_INT, ONLY: ITER_REPORT,BAYES_EXTRA_REQUEST,BAYES_EXTRA

These variables can be used as shown in example 8:

$PK
include nonmem_reserved_general
BAYES_EXTRA_REQUEST = 1

....
IF(BAYES_EXTRA==1 .AND. ITER_REPORT>=0 .AND. TIME==0.0) THEN
 WRITE(50, *) ITER_REPORT,ID,CL,V1,Q,V2
ENDIF

ITER_REPORT contains the present iteration number as reported to the console or NONMEM report file. BAYES_EXTRA and BAYES_EXTRA_REQUEST are described in example8.ctl.

RESERVED AND OTHER FUNCTIONS

The nonmem_reserved_general file contains function declarations, such as TFI and TFD, which are convenient functions to easily convert an integer to text (“text from integer” TFI) or double precision value to text (“text from double” TFD).

If you wish to define your own function for use in abbreviated code and have the information about its proper use of arguments be conveyed upon its execution, so the compiler may detect errors, then one method is to package the definition of the function in a USE module, such as is done in the example User-defined Reserved Function.

REFERENCES: Guide IV, section IV; Guide VI, section III.K; Guide Introduction_7

2 ABBREVIATED FUNCTION

MEANING: User-supplied function that may be used in abbreviated code.

CONTEXT: Fortran coded function

The following applies to all versions of NONMEM.

USAGE:

FUNCTION FUNCA(X,X1,X2)
DOUBLE PRECISION X,X1,X2,FUNCA
DIMENSION X(9),X1(9),X2(9,9)

The constant “9” must be used exactly as shown.

DISCUSSION:

The FORTRAN function FUNCA may be used in abbreviated code. Similarly, the functions FUNCB, FUNCC, etc. may be used; their constructions would be similar to that of FUNCA. In abbreviated code, the function is referenced with a single argument, either a (scalar) expression or a vector. Certain reserved names such as VECTRA, VECTRB, etc. may be used in the abbreviated code, but the name of the argument is not in the code defining the function. (See Section 53.1). In the code defining the function, the function has three arguments.

Input Argument:

X: The value of the argument (which may be a vector).

Output Argument:

FUNCA: The value of the function is to be stored in FUNCA.

There are two other outputs.

X1: X1(n) is the first-partial derivative of the function with respect to the nth element of the argument. If the value of X(n) will not be a value of a random variable, X1(n) need not be set. If the argument X is a (scalar) expression, only X1(1) is needed.
X2: X2(n,m) is the second-partial derivative of the function with respect to the nth and mth elements of the argument. If the value of either X(n) or X(m) will not be a value of a random variable, X2(n,m) need not be set. Nor need any value of X2 be set if a test of MSEC=1 is false (See Section 53.73). If the argument is a (scalar) expression, only X2(1,1) may be needed. If the argument is a vector and if the value of X2(n,m) is needed, then the value of X2(m,n) is needed as well, even though these two values will be identical.

The Fortran code for the functions should be placed in one or more files. Suppose there is one such file and its name is funcfile. It should be listed on the $SUBROUTINES record. It may contain more than one FUNCTION. E.g.,

$SUBROUTINES ... OTHER = funcfile

With NONMEM VI 2.0, reserved function names are FUNCA through FUNCC. Reserved names for vectors are VECTRA through VECTRC.

With NONMEM 7.3, reserved function names are FUNCA through FUNCI.

With NONMEM 7.4, reserved function names are FUNCA through FUNCZ. Reserved names for vectors are VECTRA through VECTRZ.

If the abbreviated code uses one of these reserved function names, but the user does not supply the code via $SUBR OTHER, the NONMEM executable will be created, but there will be an error message in the NONMEM report file such as:

FUNCA WAS CALLED, BUT NO CODE WAS SUPPLIED.

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. If the abbreviated code uses one of these extended reserved function names, but the user does not supply the code via $SUBR OTHER, the NONMEM executable cannot be created, and there will be an error message from the Fortran compiler such as:

Undefined Symbols
_funcaaa_

(See Abbreviated function example).

The following applies only to NONMEM 7.4 and higher.

The $ABBR FUNCTION allows the user to declare the name of the function, the name of the vector of input arguments (which is of no use to the function), and the length of the vector of input arguments, which is passed to the function as argument NDIM. Constant NVECX in SIZES gives the maximum value size of the vector of input arguments.

In the NONMEM control stream:

$ABBR FUNCTION function_name(input_vector_name,dimension,usage)

(See Section 50.1). (See VECTORS and ABBREVIATED FUNCTIONS)

The function should be coded as follows:

FUNCTION function_name(X,X1,X2,NDIM)

USE SIZES, ONLY: DPSIZE,ISIZE

INTEGER(KIND=ISIZE) :: NDIM

REAL(KIND=DPSIZE), INTENT(IN)                  :: X

REAL(KIND=DPSIZE), INTENT(IN OUT) :: X1,X2

REAL(KIND=DPSIZE):: function_name

DIMENSION X(NDIM),X1(NDIM),X2(NDIM,NDIM)

Function_name must be exactly as specified via $ABBR FUNCTION. The value coded as “dimension” is passed to the function as NDIM. (The value coded as “usage” is optional and does not appear in code for the function.)

The value of the function is to be stored in function_name. Otherwise, the function is coded exactly as described above, with X1 and X2 as output arguments. The input_vector_name is never used in the Fortran code for the function.

REFERENCES: none

3 ACTIVE ETA LIST FOR PREDPP

MEANING: PREDPP read-only global variables

CONTEXT: PK, ERROR, TRANS routines

USAGE:

USE PROCM_INT, ONLY: NACTIV,M=>IDXETA

GLOBAL DECLARATION:

USE SIZES, ONLY: LVR
INTEGER(KIND=ISIZE) :: NACTIV,IDXETA(LVR)

DISCUSSION:

NACTIV: NACTIV = # of etas in the problem - NRETA. (See Section 53.64).

NACTIV tells how many of the etas in the problem have partial derivatives that NONMEM is not currently ignoring.

M: M(k) is the index of the kth 0-valued element of LVOUT (for k=1,...,NACTIV).

Suppose a user-written TRANS routine modifies the kth element of GG. Here is code that might be used to modify only those of its first eta derivatives that are of current interest to NONMEM:

         DO 100 I=1,NACTIV           + ...
  100 GG(K,M(I)+1,1)=GG(K,M(I)+1,1)

Location prior to NONMEM 7: procm5

REFERENCES: None.

4 ADDITIONAL_RECORD_COUNTERS

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

include nonmem_reserved_general

DISCUSSION:

In addition to the record counters NDREC and NIREC, NONMEM 7.4 provides additional record counters. All except IRECIDX refers to a record number within the current individual record.

FIRSTREC: First record of the individual.
LASTREC: Last record of the individual.
FIRSTOBS: First observation record of the individual (for which MDV=0 or 100).
LASTOBS: Last observation record of the individual (for which MDV=0 or 100).
FIRSTDOS: With PREDPP, first dose record of the individual (for which EVID=1 or 4, and MDV=1 or MDV=101). Without PREDPP, -1.
LASTDOS: With PREDPP, last dose record of the individual (for which EVID-1 or 4, and MDV=1 or MDV=101). Without PREDPP, -1.
EFIRSTREC: First record of the individual during Estimation or Covariance Steps (for which MDV=0 or MDV=1).
ELASTREC: Last record of the individual during Estimation or Covariance Steps (for which MDV=0 or MDV=1).
EFIRSTOBS: First observation record of the individual during Estimation or Covariance Steps (for which MDV=0).
ELASTOBS: Last observation record of the individual during Estimation or Covariance Steps (for which MDV=0).
EFIRSTDOS: With PREDPP, first dose record of the individual during Estimation or Covariance Steps (for which EVID=1 or 4, and MDV=1). Without PREDPP, -1.
ELASTDOS: With PREDPP, last dose record of the individual during Estimation or Covariance Steps (for which EVID=1 or 4, and MDV=1). Without PREDPP, -1.
IRECIDX: IRECIDX+1 is the starting record number in the NONMEM data set for the current individual record. NDREC starts at 1 for the first record of each individual record, so that NDREC+IRECIDX is the number of the current data record within the NONMEM data set.

Like NIREC and NDREC, the additional record counters also change value in conjunction with calls to PASS, a NONMEM utility routine. They may all be used as right-hand quantities in $PRED, $PK, and $ERROR blocks, and in a $INFN block in conjunction with PASS.

REFERENCES: Guide Introduction_7

5 ADVAN7: FACTOR

MEANING: PREDPP global variables

CONTEXT: For use with PREDPP

USAGE:

$PK
"FIRST
" USE PRCM2_REAL, ONLY: FACTOR=>FAC
"MAIN
" FACTOR=10.

GLOBAL DECLARATION:

USE SIZES, ONLY: DPSIZE
REAL(KIND=DPSIZE) :: FAC

DISCUSSION:

This feature is not fully documented. The interested user may be able to obtain more information by studying the appropriate sections of PREDPP code.

USAGE:

A message similar to the following is sometimes produced by ADVAN7:

NUMERICAL DIFFICULTIES OBTAINING THE SOLUTION. NON - REAL
EIGENVALUES. PERHAPS ADVAN5 SHOULD BE USED FOR THIS PROBLEM.
"LARGEST" VALUE ALONG SUBDIAGONAL OF SCHUR MATRIX: 0.423E-01
(DIAG: 0.84E+00 0.84E+00)

FACTOR is a “fudge factor” that affects ADVAN7’s determination of how large the subdiagonal element is relative to the two diagonal elements. The default value of FACTOR is 1.

These error messages arise when the computations of the eigenvalues produce unexpected values. The question is whether the subdiagonal elements are too large to ignore (e.g., when the eigenvalues are truly complex) in which case ADVAN5 must be used, or whether trivially small quantities have been produced by the accumulation of rounding error in the floating point computation, in which ADVAN7 can be used. (Non-real eigenvalues result when the system is non-mamillary, and may also occasionally occur when there are etas associated with rate constants Kij).

If the maximum value printed is very small (e.g., E-15), then the computations will proceed correctly using a value of FACTOR such as 10 or 100. Values such as FACTOR=10 or FACTOR=100 are more permissive, and allow larger subdiagonal elements. If no reasonable value of FACTOR eliminates the error messages, then ADVAN5 should be used.

Location prior to NONMEM 7: prcomw

REFERENCES: None.

6 AES

MEANING: AES subroutine

CONTEXT: User-supplied subroutine; for use with PREDPP’s ADVAN9 and ADVAN15 and ADVAN17

USAGE:

SUBROUTINE AES (INIT,A,P,T,E,IR,DA,DP,DT)
USE SIZES, ONLY: DPSIZE,ISIZE
INTEGER (KIND=ISIZE) :: INIT,IR
REAL(KIND=DPSIZE) :: A,P,E,DA,DP,DT
DIMENSION :: A(*),P(*),E(*),DA(IR,*),DP(IR,*),DT(*)

DISCUSSION:

The AES subroutine is called by PREDPP to evaluate algebraic expressions for ADVAN9, ADVAN15, and ADVAN17.

Input argument:

P(n): The value of the nth PK parameter.
T: Time. T takes values continuously over an integration interval.

Input/output arguments:

INIT: When AES is called with INIT=1, this is an initial condition call at the start of an integration interval. Approximate amounts in each equilibrium compartment n at time T must be stored in A(n). (The amounts in the non-equilibrium compartments are already stored in the lower-numbered elements of A.) DA, DP, DT need not be computed.

If AES stores approximate values in A, it must set INIT=0. If AES stores exact values in A, it must leave INIT unchanged.

When AES is called with INIT=2, the values of the algebraic expressions must be stored in E and the derivatives in DA, DP, and DT.

A(n): The amount in the nth compartment at time T.

Output argument:

E(k): The value of the algebraic expression g(k).
DA(k,j): The derivative of g(k) with respect to A(j).
DP(k,j): The derivative of g(k) with respect to P(j).
DT(k): The derivative of g(k) with respect to T.

Also see variables in NONMEM modules, NONMEM-PRED modules, and PREDPP modules. (See Section 53.111) In particular, (See Section 53.29, Section 53.29, Section 53.29).

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

7 BIOAVAILABILITY BEHAVIOR

MEANING: PREDPP global variables

CONTEXT: For use with PREDPP

This feature is not fully documented. The interested user may be able to obtain more information by studying the appropriate sections of PREDPP code.

USAGE:

$PK
"FIRST
" USE PRCOM_LOG, ONLY: NEWBIO=>NEWWAY
"MAIN
" NEWBIO=.FALSE.

GLOBAL DECLARATION:

LOGICAL NEWWAY

DISCUSSION:

This variable allows the user to change the way bioavailability fraction parameters are used by PREDPP. Prior to 1990 (i.e., with NONMEM III / PREDPP I) bio-availability fractions applied to all transient doses except infusions (doses with AMT > 0 and RATE > 0). Similarly, it did not apply to steady-state doses with multiple infusion and with a positive rate data item.

After the change, bio-availability fractions apply to all transient (non steady-state) doses, and to steady-state doses for which the AMT is specified. The only doses to which bio-availability fractions do not apply are steady-state with constant infusion.

By default, NEWBIO is true and the new rules apply. If NEWBIO is set to false, bioavailability fraction parameters revert to their pre-1990 behavior.

Location prior to NONMEM 7: prcomu

REFERENCES: None.

8 CALLFL

MEANING: Control calls to PK and ERROR subroutine and ADVAN9/15/17

CONTEXT: Abbreviated code

USAGE:

CALLFL=n

DISCUSSION:

This pseudo-assignment statement may be present in $PK abbreviated code, in which case it controls when PREDPP calls the PK routine. It may be present in $ERROR abbreviated code, in which case it controls when PREDPP calls the ERROR routine. It may be present in $AESINITIAL abbreviated code when the TIME data item is not used, in which case it controls when PREDPP calls the ADVAN9, ADVAN15, or ADVAN17 routine. The use of CALLFL in each of these three abbreviated codes is independent of its use in the others. The pseudo-assignment statement may be enclosed in parentheses. A calling protocol phrase may be used within parentheses instead of a pseudo-assignment statement CALLFL (See calling protocol). The pseudo-assignment statement may take these forms:

OPTIONS:

CALLFL=-2: Call the PK subroutine with every event record, with additional and lagged doses, and at modeled event times. Does not apply to the ERROR or ADVAN9, ADVAN15, or ADVAN17 routines.

The following messages will appear in the NONMEM output report:

PK SUBROUTINE CALLED WITH EVERY EVENT RECORD
PK SUBROUTINE CALLED AT NONEVENT (ADDITIONAL AND LAGGED) DOSE TIMES

PK SUBROUTINE CALLED AT NONEVENT (ADDITIONAL AND LAGGED) DOSE TIMES
AND AT MODEL TIMES

CALLFL=-1: Call the subroutine with every event record. This is the default.

Some of the following messages will appear in the NONMEM output:

PK SUBROUTINE CALLED WITH EVERY EVENT RECORD
PK SUBROUTINE NOT CALLED AT NONEVENT (ADDITIONAL OR LAGGED) DOSE TIMES

ERROR SUBROUTINE CALLED WITH EVERY EVENT RECORD

ADVAN9 CALLED WITH EVERY EVENT RECORD
ADVAN15 CALLED WITH EVERY EVENT RECORD
ADVAN17 CALLED WITH EVERY EVENT RECORD

CALLFL=0: For the PK subroutine: If the data are population data, call the subroutine with the first event record of each individual record; if the data are single-subject data, call the subroutine with the first event record of the data set. In addition, call the subroutine with with every event record where the event time differs from the previous event time.

The following messages will appear in the NONMEM output report:

PK SUBROUTINE CALLED ONLY WITH NEW INDIVIDUAL OR NEW TIME
PK SUBROUTINE NOT CALLED AT NONEVENT (ADDITIONAL DOSE OR LAGGED) DOSE TIMES.

For the ERROR subroutine: When the Simulation Step is being implemented, call the subroutine with every event record. Otherwise, call the subroutine only with observation event records.

The following messages will appear in the NONMEM output report:

DURING SIMULATION, ERROR SUBROUTINE CALLED WITH EVERY EVENT RECORD
OTHERWISE, ERROR SUBROUTINE CALLED ONLY WITH OBSERVATION EVENTS

Does not apply to the ADVAN9, ADVAN15, or ADVAN17 routine.

With CALLFL=0, The CALL data item may be used to request calls with additional event records.

CALLFL=1: For the PK and ADVAN9, ADVAN15, or ADVAN17 subroutines: If the data are population data, call the subroutine with the first event record of each individual record; if the data are single-subject data, call the subroutine with the first event record of the data set.

The following messages appear in the NONMEM output report:

PK SUBROUTINE CALLED ONCE PER INDIVIDUAL RECORD
PK SUBROUTINE NOT CALLED AT NONEVENT (ADDITIONAL DOSE OR LAGGED) DOSE TIMES

ADVAN9 CALLED ONCE PER INDIVIDUAL RECORD.
ADVAN15 CALLED ONCE PER INDIVIDUAL RECORD.
ADVAN17 CALLED ONCE PER INDIVIDUAL RECORD.

For the ERROR subroutine: When the Simulation Step is being implemented, call the subroutine with every event record. Otherwise, if the data are population data, call the subroutine with the first event record of each individual record; if the data are single-subject data, call the subroutine with the first event record of the data set.

The following messages appear in the NONMEM output report:

DURING SIMULATION, ERROR SUBROUTINE CALLED WITH EVERY EVENT RECORD
OTHERWISE, ERROR SUBROUTINE CALLED ONCE PER INDIVIDUAL RECORD

With CALLFL=1, The CALL data item may be used to request calls with additional event records.

In a block of abbreviated code, the CALLFL=n pseudo-assignment statement must precede all the other abbreviated code (except for verbatim code or other pseudo-assignment statements). The pseudo-assignment statement may not be used conditionally. CALLFL may not be used as a variable elsewhere in the abbreviated code.

NOTE: If the $ERROR record consists of exactly one of these four statements:

Y = F + ERR(1)
Y = F * (1 + ERR(1))
Y = F + F * ERR(1)
Y = F * EXP(ERR(1))

with no other lines of code (except for comment lines), NM-TRAN will automatically limit calls to ERROR to once-per-problem (unless the Simulation Step is being implemented, in which case. calls are made with every event record). In effect, this amounts to yet another way to control when it is that calls may occur to the ERROR routine, but one which may not be explicitly specified in $ERROR via the use of CALLFL.

With the last three models (proportional and exponential), NM-TRAN will also cause PREDPP to output the message:

ERROR IN LOG Y IS MODELED

(This does not mean that a model is fit to Log Y data.)

REFERENCES: Guide IV, section V.C.5

9 CALLING PROTOCOL PHRASE

MEANING: Control calls to PK and ERROR and ADVAN9, ADVAN15, and ADVAN17

CONTEXT: Abbreviated code

USAGE:

$PK (ONCE PER INDIVIDUAL RECORD)
$ERROR (ONCE PER INDIVIDUAL RECORD)
$AESINITIAL (ONCE PER INDIVIDUAL RECORD)

DISCUSSION:

A calling protocol phrase can be used instead of the CALLFL pseudo-statement in $PK, $ERROR, and $AESINITIAL abbreviated codes. The phrase must be enclosed in parentheses. Either upper or lower case may be used. In an abbreviated code, the line of code containing the phrase must precede all the other abbreviated code (except for verbatim code or other pseudo-assignment statements), and it may be the same line that marks the beginning of the code, as in the above usage examples. Pseudo-statements defining COMRES may be coded within the same parentheses, separated by a semicolon “;”. No abbreviated code may follow “)” on the same line as the “)”.

Phrases equivalent to CALLFL=-2 for the $PK record:

(NON-EVENT)
(ADDITIONAL OR LAGGED)

The following messages will appear in the NONMEM output report:

PK SUBROUTINE CALLED WITH EVERY EVENT RECORD
PK SUBROUTINE CALLED AT NONEVENT (ADDITIONAL AND LAGGED) DOSE TIMES

PK SUBROUTINE CALLED AT NONEVENT (ADDITIONAL AND LAGGED) DOSE
TIMES AND AT MODEL TIMES

Phrases equivalent to CALLFL=-1 for the $PK, $ERROR and $AESINITIAL records (the default):

(EVERY EVENT)
(EVERY)

The following messages will appear in the NONMEM output report (as appropriate):

PK SUBROUTINE CALLED WITH EVERY EVENT RECORD
PK SUBROUTINE NOT CALLED AT NONEVENT (ADDITIONAL OR LAGGED) DOSE TIMES

ERROR SUBROUTINE CALLED WITH EVERY EVENT RECORD

ADVAN9 CALLED WITH EVERY EVENT RECORD.
ADVAN15 CALLED WITH EVERY EVENT RECORD.

Phrases equivalent to CALLFL=0 for the $PK record:

(NEW TIME)
(NEW EVENT TIME)

The following messages appear in the NONMEM output report:

PK SUBROUTINE CALLED ONLY WITH NEW INDIVIDUAL OR NEW TIME
PK SUBROUTINE NOT CALLED AT NONEVENT (ADDITIONAL OR LAGGED) DOSE TIMES.

Phrases equivalent to CALLFL=0 for the $ERROR record:

(OBSERVATION EVENT)
(OBS)
(OBSERVATION ONLY)
(OBS ONLY)

One or more of the following messages appear in the NONMEM output report when calls are limited in this manner:

DURING SIMULATION, ERROR SUBROUTINE CALLED WITH EVERY EVENT RECORD
OTHERWISE, ERROR SUBROUTINE CALLED ONLY WITH OBSERVATION EVENTS

Phrases equivalent to CALLFL=1 for the $PK, $ERROR and $AESINITIAL blocks:

(ONCE PER INDIVIDUAL RECORD)
(ONCE/IND.REC.)

The following messages appear in the NONMEM output (as appropriate):

PK SUBROUTINE CALLED ONCE PER INDIVIDUAL RECORD
PK SUBROUTINE NOT CALLED AT NONEVENT (ADDITIONAL OR LAGGED) DOSE TIMES

DURING SIMULATION, ERROR SUBROUTINE CALLED WITH EVERY EVENT RECORD
OTHERWISE, ERROR SUBROUTINE CALLED ONCE PER INDIVIDUAL RECORD

ADVAN9 CALLED ONCE PER INDIVIDUAL RECORD.
ADVAN15 CALLED ONCE PER INDIVIDUAL RECORD.

REFERENCES: Guide IV, section V.C.5

10 CCONTR: F, G, H

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

This feature is not fully documented. The interested user may be able to obtain more information by studying the appropriate sections of NONMEM code and previous examples that may be available from advanced users.

USAGE:

USE ROCM_REAL, ONLY: F=>FL2,G=>GL2,G2=>GGL2,H=>HL2

GLOBAL DECLARATION:

USE SIZES, ONLY: NO,LVR,LVR2,DPSIZE
REAL(KIND=DPSIZE) :: FL2(NO),GL2(NO,LVR),GGL2(NO,LVR2*(LVR2+1)/2), &
                     HL2(NO,LVR*LVR/4+LVR/2)

DISCUSSION:

These variables change values with each L2 record. They may be used by CCONTR.

OPTIONS:

F: F(n) = value returned in F from PRED for the nth observation of the L2 record.
G: G(n,i) = Partial derivative of F(n) with respect to eta(i).
G2: G2(n,i*(i-1)/2+j) = second partial derivative of F(n) with respect to eta(i) and eta(j) (j<=i). G2 is arranged in symmetric storage, e.g.

1
23
456

G2(n,1) = 2nd. partial of F(n) wrt. eta(1) eta(1)
G2(n,2) = 2nd. partial of F(n) wrt. eta(2) eta(1)
G2(n,3) = 2nd. partial of F(n) wrt. eta(2) eta(2)
G2(n,4) = 2nd. partial of F(n) wrt. eta(3) eta(1)
G2(n,5) = 2nd. partial of F(n) wrt. eta(3) eta(2)
G2(n,6) = 2nd. partial of F(n) wrt. eta(3) eta(3)

H: H(n,i) = Partial derivative of F(n) with respect to eps(i) for i=1,neps, where neps is the number of epsilons in the problem. H(n,j*neps+i) = second partial derivative of F(n) with respect to eps(i) and eta(j).

E.g. suppose that there are two epsilons in the problem:

135
246

H(n,1) = partial derivative of F(n) wrt. eps(1)
H(n,2) = partial derivative of F(n) wrt. eps(2)
H(n,3) = 2nd. partial of F(n) wrt. eps(1) eta(1)
H(n,4) = 2nd. partial of F(n) wrt. eps(2) eta(1)
H(n,5) = 2nd. partial of F(n) wrt. eps(1) eta(2)
H(n,6) = 2nd. partial of F(n) wrt. eps(2) eta(2)

Location prior to NONMEM 7: rocm5

REFERENCES: None.

11 CCONTR: Y, DATA, N1, N2, DIM

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE ROCM_REAL, ONLY: Y=>DV_ITM2,DATA=>CDATA
USE ROCM_INT, ONLY: N1=>NL2_OBS,N2=>L2NO,DIM=>L2CR_DIM

GLOBAL DECLARATION:

USE SIZES, ONLY: NO,DPSIZE
REAL(KIND=DPSIZE) :: DV_ITM2(NO),CDATA(NO,3)
INTEGER(KIND=ISIZE) :: NL2_OBS,L2NO,L2CR_DIM(NO)

DISCUSSION:

These variables change values with each L2 record. They may be used by CCONTR. When the epsilons are correlated between L2 records these variables change values with each L1 record. (See Section 53.23)

OPTIONS:

Y(k): DV data item on the kth observation record of the L2 (L1) record.
DATA(k,i): The ith type of data item specified in NM-TRAN’s $CONTR record, appearing on the kth observation record of the L2 (L1) record.
N1: Number of observations in the L2 record. When the epsilons are correlated between L2 records, N1 is the number of L2 records within the L1 record.
N2: Number of the L2 record within the L1 record. When the epsilons are correlated between L2 records, N2 is 0.
DIM: When the epsilons are correlated between L2 records, DIM gives the lengths of the L2 records.

Location prior to NONMEM 7: rocm3

REFERENCES: None.

12 COM COMACT COMSAV COMRES

MEANING: Variables related to the module NMPRD4

CONTEXT: Abbreviated code, verbatim code, user-supplied routines, NM-TRAN

Reserved labels starting COM are related to each other. They all refer in some manner to the module NMPRD4. (This module was originally a global COMMON; hence the use of the letters “COM”.)

OPTIONS:

COM(n) (in $TABLE and $SCATTER records): Certain positions of MODULE NMPRD4 may be reserved, and the variables stored in these positions may be displayed by listing them as COM(1), COM(2), etc. on $TABLE and $SCATTER records, e.g.,

$TABLE COM(1) COM(2)

COM(n) (in abbreviated and verbatim code): Certain positions of MODULE NMPRD4 may be reserved, and the variables stored in these positions are referenced in abbreviated and verbatim code as COM(1), COM(2), etc.
COMACT (in any user code): Reserved variable COMACT is set by NONMEM. It may be tested in PRED (e.g., in abbreviated code, verbatim code, or in user-written routines) to determine when NONMEM is making a copying pass, i.e., when the data records are being passed to PRED for the purpose of computing values of variables which will be obtained (i.e. copied) from NMPRD4 for tables and scatterplots. NONMEM only makes a copying pass when PRED-defined items are listed in $TABLE or $SCATTER records. There may be a few copying passes. With the first copying pass, the value of COMACT is 1. As copying passes proceed, the value of COMACT may remain the same or increase. The values used in tables and scatterplots are those copied from NMPRD4 with the last copying pass.

COMACT=0: This is not a copying pass.
COMACT=1: This is a copying pass with final thetas and zero-valued etas.
COMACT=2: This is a copying pass with final thetas and conditional estimates of etas.
COMACT=3: This is a copying pass with conditional (nonparametric) estimates of etas.

Such a pass takes place when the control stream includes this record:

$NONPARAMETRIC ETAS

COMRES=n1 (option of $ABBREVIATED record): COMRES (“common reserve”) is an option of the $ABBREVIATED record. It gives instructions to NM-TRAN about NMPRD4.

COMRES=-1: Do not store any variables in module NMPRD4.
COMRES=0: Store variables in NMPRD4, but do not reserve any positions (the default).
COMRES=n1: Store variables in NMPRD4, and reserve the first n1 positions.

COMRES=-1 (in abbreviated code): The pseudo-assignment statement COMRES=-1 may be used in any block of abbreviated code to prevent any variable defined in the block from being stored into NMPRD4.
COMSAV=n2 (option of $ABBREVIATED record): Values of variables displayed in tables and scatterplots are obtained from module 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 module NMPRD4 is the initial part of NMPRD4. If a variable is stored in the SAVE region, then the value of the variable computed with a given data record during a copying pass will be found in NMPRD4 when the same record is passed during the next copying pass, i.e. it will have been saved from the previous copying pass. This is in contrast to the usual behaviour, where with a given data record, the value in NMPRD4 is the value computed with the previous data record.

n2 is the initial size of the SAVE region, i.e. the number of positions in this region. n2 = 0 is the default value. n2 may not exceed n1.

The SAVE region has size n2 initially, but NM-TRAN may extend it if SAVE variables are used. However, if n2 = -1, the SAVE region is not to be extended, and there is to be no SAVE region altogether. (See Section 53.22).

NM-TRAN causes the generated routines to store the value of COMSAV at ICALL=1.

COMSAV=n2 (in user written code): In the absence of abbreviated code, COMSAV may be set by a user-written PRED routine at ICALL<=1, or at COMACT=1 with the very first data record. n2 is as described above.

(See Section 53.13, Section 53.13) (See Section 53.84) (See Section 50.1, Section 53.1, displayed_values).

REFERENCES: Guide IV, section III.B.7, IV.E.2; Guide VI, section III.J

13 COMACT, COMSAV

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

USAGE:

USE NMPRD_INT, ONLY: COMACT,COMSAV

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: COMACT,COMSAV

DISCUSSION:

COMACT is set by NONMEM; COMSAV is set by PRED.

OPTIONS:

COMACT

COMACT=0: NONMEM is not making a copying pass, i.e., values from NMPRD4 will not be copied for tables and scatterplots. (NONMEM only makes a copying pass when PRED-defined items are listed in $TABLE or $SCATTER records.)

COMACT=1: This is a copying pass with final thetas; etas are zero.
COMACT=2: This is a copying pass with final thetas and conditional eta estimates.
COMACT=3: This is a copying pass with conditional (nonparametric) estimates of etas. Such a pass takes place when the control stream includes this record:

$NONPARAMETRIC ETAS

COMSAV: Set by PRED at ICALL<=1 or at COMACT=1 with the very first data record. The Save Region is an initial part of NMPRD4. If with a given data record, the value of a PRED-defined variable is stored in this region, then during a copy pass with COMACT = 2, the value of the variable is initialized to the value obtained during the copy pass with the same data record and COMACT=1. COMSAV is the size of this region, i.e., the number of variables whose values are stored in this region.

When NM-TRAN is used, COMACT may be tested in abbreviated code. COMSAV may not be referenced in abbreviated code. Instead, the COMSAV option of the $ABBREVIATED record is coded, and NM-TRAN causes the specified value to be stored in COMSAV.

Location prior to NONMEM 7: nmprd3

REFERENCES: Guide IV, section III.B.7, IV.E.2; Guide VI, section III.J, IV.E

14 COMPARTMENT INITIALIZATION BLOCK

MEANING: Abbreviated code for compartment initialization

CONTEXT: $PK abbreviated code

SAMPLE:

$PK
IF (A_0FLG == 1) THEN

 ... compartment initialization block ...
ENDIF

DISCUSSION:

A “compartment initialization block” is a block of abbreviated code that sets the initial state of the kinetic system. It is to be executed only when A_0FLG=1. Such a block may be present only in $PK. PREDPP sets A_0FLG to 1 at a call to PK with the first event record of an individual record (if the data are population data), with the first event record of the data set (if the data are single-subject data), and with a reset record.

Special rules apply to such a block.

Values may be assigned to reserved variables A_0(n), but only in a compartment initialization block. The value of the amount in the nth compartment (the nth element of the state vector) is set to the value assigned to A_0(n). If PK is called with a dose record or a dose-reset record where the dose is input into the nth compartment, this amount is then increased by the amount of the (bioavailable) dose. If a value is assigned to A_0(n), then it is not necessary that values be assigned to any of the remaining variables A_0(m). A value to the output compartment cannot be assigned. A_INITIAL(n) is a synonym for A_0(n).
The statement IF (A_0FLG.EQ.1) and the corresponding ENDIF statement may be included explicitly in abbreviated code, thus defining an explicit compartment initialization block. (See example 1 below.)
A_0(n) may be assigned a value with an unconditional statement. This defines an implicit compartment initialization block; NMTRAN inserts IF (A_0FLG.EQ.1) ... before the statement and ENDIF after it. (See example 2 below.) Indicator variables may be included in the unconditional statement. (See example 3 below.)
An IF statement testing ICALL and A_0FLG together is not permitted. Instead, two separate nested IF statements must be used: an IF statement testing ICALL must occur as the outermost statement, and an IF statement testing A_0FLG must occur as the innermost statement. The latter may be supplied by NM-TRAN as a result of using an implicit initialization block. (See example 4 below.)
Within an explicit compartment initialization block, A_0(n) may be assigned conditionally. The usual rules apply if A_0(n) is a random variable. E.g., A_0(n) cannot be assigned within a nested IF, and it defaults to 0 if it is assigned conditionally but incompletely. However, in checking for a nested IF, tests of A_0FLG and of ICALL are ignored. (See example 3 below.)
User-defined variables may be defined in compartment initialization blocks, but not reserved variables such as basic or additional PK parameters.

EXAMPLES OF USAGE:

The following two fragments of code yield identical results:

Explicit compartment initialization block:

IF (A_0FLG == 1) THEN

 A_0(1) = THETA(1) * (1 + ETA(1))
ENDIF

Implicit compartment initialization block:

A_0(1) = THETA(1) * (1 + ETA(1))

This is an example of conditional assignment of A_0(n) (X is a data item or user-defined variable):

IF (A_0FLG == 1) THEN

 IF (X == 1) THEN
 A_0(1) = THETA(1) * (1 + ETA(1))
 ELSE
 A_0(1) = THETA(2) * (1 + ETA(2))
 ENDIF
ENDIF

Note that this can be expressed unconditionally with the use of an indicator variable. E.g., if X is a 0/1 variable, then the above is equivalent to

A_0(1) = X * THETA(1) * (1 + ETA(1)) + (1 - X) * A_0(1) = THETA(2) * (1 + ETA(2))

Suppose compartment initialization should occur only during the Simulation step. The following is not permitted:

IF (ICALL == 4 .AND. A_0FLG == 1) A_0(1) = THETA(1) * (1 + ETA(1))

Instead, use:

IF (ICALL == 4) THEN
 IF (A_0FLG == 1) A_0(1) = THETA(1) * (1 + ETA(1))
ENDIF

or simply

IF (ICALL == 4) THEN
 A_0(1) = THETA(1) * (1 + ETA(1))

ENDIF

or even more simply

IF (ICALL == 4) A_0(1) = THETA(1) * (1 + ETA(1))

(See Compartment Initialization: A_0) (See Compartment Initialization: A_0FLG) (See Section 53.77).

REFERENCES: None.

15 COMPARTMENT INITIALIZATION: A_0

MEANING: PREDPP-PK global variables

CONTEXT: PK routine

USAGE:

USE PRMOD_REAL, ONLY: A_0,DA_0,D2A_0

GLOBAL DECLARATION:

USE SIZES, ONLY: PC,LVR,DPSIZE
REAL(KIND=DPSIZE) :: A_0(PC),DA_0(PC,LVR),D2A_0(PC,LVR,LVR)

DISCUSSION:

PREDPP sets A_0FLG to 1 (See compartment initialization: a_0flg) at a call to PK with the first event record of an individual record (if the data are population data), with the first event record of the data set (if the data are single-subject data), and with a reset record. At such times, the amounts in the various compartments can be set by the PK routine. It can do this by storing the initial values for the state vector and its partials in A_0,DA_0,D2A_0. The amount in the output compartment can not be set.

OPTIONS:

A_0: A_0(n) = the amount for compartment n
DA_0: DA_0(n,i) = the derivative of A_0(n) wrt eta(i)
D2A_0: D2A_0(n,i,j) = the second derivative of A_0(n) wrt eta(i), eta(j) (lower-triangular; j=1, …, i)

There is a one-to-one correspondence between A_0,DA_0,D2A_0 and A,DAETA,D2AETA (See Section 53.106). NM-TRAN includes A_0,DA_0,D2A_0 in the PK routine when the $PK block includes references to variables A_0FLG, A_0, or A_INITIAL, or when verbatim code is present. (See Compartment Initialization: A_0FLG, Section 53.106).

Location prior to NONMEM 7: prdpk3

REFERENCES: None.

16 COMPARTMENT INITIALIZATION: A_0FLG

MEANING: PREDPP read-only global variables

CONTEXT: User-supplied PK routine

USAGE:

USE PROCM_INT, ONLY: A_0FLG

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: A_0FLG

DISCUSSION:

A_0FLG: When ICALL>=2, at a call to PK with the first record of of an individual record or with a reset record, PREDPP sets A_0FLAG=1. At such a call, the state vector A and its first and second eta partials (DAETA and D2AETA) have been set to zero. A_0FLG=0 at all other calls to PK.

When A_0FLG=1, PK may initialize compartments. It can do this by storing the initial values for the state vector and its partials in A_0,DA_0,D2A_0. NM-TRAN includes A_0FLG in the PK routine when the $PK block includes references to variables A_0FLG, A_0(n), or A_INITIAL(n), or when verbatim code is present. (See Compartment Initialization: A_0, Section 53.106).

Location prior to NONMEM 7: procmc

REFERENCES: None.

17 COMPARTMENT UPDATE BLOCK (NM75)

MEANING: Abbreviated code for compartment update

CONTEXT: $PK abbreviated code

SAMPLE:

$PK
IF (A_UFLG == 1) THEN

 ... compartment update block ...
ENDIF

DISCUSSION:

With NONMEM 7.5, a compartment update block is a block of abbreviated code that is very similar to a compartment initialization block.

In a compartment initialization block, PREDPP sets A_0FLG to 1 at a call to PK with all the compartments at their initial state so that values may be assigned to reserved variables A_0(n). (See Compartment Initialization: A_0)

In a compartment update block, the user sets A_UFLG to 1 in PK to indicate to PREDPP that PK is going to update the compartments. The desired compartment values may be set in the array A_U(n). The user should use MTIME to designate a variable time position at which an abrupt change in compartment amounts occurs. One could input a dose as follows:

MTIME(1) = wtime
MTDIFF = 1
AZTEST = A_0FLG
IF(TSTATE==MTIME(1) .AND. AZTEST==0) A_UFLG = 1
IF(A_UFLG==1) THEN
 A_U(1) = A(1) + wdose
 A_U(2) = A(2)
 A_U(3) = A(3)
ENDIF

With the Compartment Update Block, the user sets A_UFLG to 1 when the compartments are to be updated. The A_UFLG event must be triggered with an IF(TSTATE==MTIME()) condition as indicated in the above example. Values may be assigned to reserved variables A_U(n). The value of the amount in the nth compartment (the nth element of the state vector) is set to the value assigned to A_U(n). Any A_U(x) not explicitly defined are set to 0. An un-assigned A_U(k) should retain its value, A_u(k)=A_u(k).

The code IF(A_UFLG==1)...THEN...ENDIF is optional, as NMTRAN will insert it if not present. A_0FLG must be 0 whenever A_UFLG is set to 1, as shown in the example above (..\examples_uflg.ctl).

The rules for compartment update blocks are similar to those for compartent initialization blocks.

PREDPP expects to find the A_U values in the A_0 arrays. NMTRAN converts A_U() in abbreviated code to A_0() during FSUBS code construction.

(See Guide Introduction_7, “Updating Amounts in Compartments at any Time: The A_UFLG Flag (NM75)”)

REFERENCES: Guide Introduction_7

18 CONTR: F, G, H

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE ROCM_REAL, ONLY: F=>FL1,G=>GL1,G2=>GGL1,H=>HL1

GLOBAL DECLARATION:

USE SIZES, ONLY: NO,LVR,LVR2,DPSIZE
REAL(KIND=DPSIZE) :: FL1(NO),GL1(NO,LVR), &
                     GGL1(NO,LVR2*(LVR2+1)/2), &
                     HL1(NO,LVR*LVR/4+LVR/2)

DISCUSSION:

These variables changes values with each individual record. They may be used by CONTR.

OPTIONS:

F: F(n) = value returned in F from PRED for the nth observation of the individual record.
G: G(n,i) = Partial derivative of F(n) with respect to eta(i).
G2: G2(n,i*(i-1)/2+j) = second partial derivative of F(n) with respect to eta(i) and eta(j) (j<=i). G2 is arranged in symmetric storage, e.g.

1
23
456

G2(n,1) = 2nd. partial of F(n) wrt. eta(1) eta(1)
G2(n,2) = 2nd. partial of F(n) wrt. eta(2) eta(1)
G2(n,3) = 2nd. partial of F(n) wrt. eta(2) eta(2)
G2(n,4) = 2nd. partial of F(n) wrt. eta(3) eta(1)
G2(n,5) = 2nd. partial of F(n) wrt. eta(3) eta(2)
G2(n,6) = 2nd. partial of F(n) wrt. eta(3) eta(3)

H: H(n,i) = Partial derivative of F(n) with respect to eps(i) for i=1,neps, where neps is the number of epsilons in the problem. H(n,j*neps+i) = second partial derivative of F(n) with respect to eps(i) and eta(j).

E.g. suppose that there are two epsilons in the problem:

135
246

H(n,1) = partial derivative of F(n) wrt. eps(1)
H(n,2) = partial derivative of F(n) wrt. eps(2)
H(n,3) = 2nd. partial of F(n) wrt. eps(1) eta(1)
H(n,4) = 2nd. partial of F(n) wrt. eps(2) eta(1)
H(n,5) = 2nd. partial of F(n) wrt. eps(1) eta(2)
H(n,6) = 2nd. partial of F(n) wrt. eps(2) eta(2)

Location prior to NONMEM 7: rocm3

REFERENCES: None.

19 CONTR: III, DIM

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE ROCM_INT, ONLY: III=>NL2_RECS, DIM=>L2_DIM

GLOBAL DECLARATION:

USE SIZES, ONLY: NO
INTEGER(KIND=ISIZE) :: NL2_RECS,L2_DIM(NO)

DISCUSSION:

These variables change values with each individual record. They may be used by CONTR.

OPTIONS:

III: Number of L2 records in the individual record.
DIM: Length of each L2 record.

When there is no L2 data item, III = number of observations in the individual record, and all values in DIM = 1.

Location prior to NONMEM 7: rocm2

REFERENCES: None.

20 CONTR: KCALL

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE ROCM_INT, ONLY: KCALL=>K_CONTR

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: K_CONTR

DISCUSSION:

KCALL

KCALL=1 with a unique pass through data calling PRED and CONTR with final parameter estimates.

KCALL=0 otherwise.

Location prior to NONMEM 7: rocm13

REFERENCES: None.

21 CONTR: Y DATA NOBS

MEANING: NONMEM read-only global variables

CONTEXT: CONTR routine

USAGE:

USE ROCM_REAL, ONLY: Y=>DV_ITM,DATA=>RDATA
USE ROCM_INT, ONLY: NOBS=>NOBSIND2

GLOBAL DECLARATION:

USE SIZES, ONLY: NO,DPSIZE
REAL(KIND=DPSIZE) :: DV_ITM(NO),RDATA(NO,3)
INTEGER(KIND=ISIZE) :: NOBSIND2

DISCUSSION:

These variables change values with each individual record. They may be used by a user-written CONTR subroutine.

OPTIONS:

Y(k): DV data item on the kth data record of the individual record, ignoring data records with MDV=1.
DATA(k,i): The value of the ith type of data item specified in NM-TRAN’s $CONTR record, appearing on the kth observation record of the individual record.
NOBS: Number of observations in the individual record.

DATA is used also in MIX (See data_for_mix).

Location prior to NONMEM 7: rocm1

REFERENCES: Guide IV, section III.B.4

22 COPYING BLOCK

MEANING: Abbreviated code especially for copying pass

CONTEXT: $PRED, $PK, $ERROR, $AES, $DES abbreviated code

SAMPLE:

IF (COMACT == 1) TVCL = CL

DISCUSSION:

Values of variables displayed in tables and scatterplots are obtained (i.e. copied) from module 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 variable COMACT signals that a copying pass is in progress when its value is positive. There may be a number of copying passes, but if (and only if) values of variables are to be displayed, there is at least one copying pass. With the first copying pass, the value of COMACT is 1 and that of MIXNUM is 1. If a mixture model with k subpopulations is used, then COMACT remains 1 during a total of k copying passes, and with each copying pass the value of MIXNUM increments by 1. If conditional estimation is used (or if the POSTHOC option appears), then there follows a set of copying passes where the value of COMACT is 2 and again, MIXNUM increases from 1 to k. If a mixture model is not used, there are altogether at most two copying passes, one with COMACT=1 and another with COMACT=2.

If values of a variable from earlier copying passes are needed in later passes, the values for the variable should be stored in the SAVE region of module NMPRD4. (See Section 53.13). When the values are stored in the SAVE region, that value 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 (with a noncopying pass), where with a given data record, the value in NMPRD4 is the value computed with the previous data record. The value is 0 when a record is passed during the first copying pass, and though PRED may set it or reset it during a subsequent copying pass, this need not be done (See discussion below about COMACT).

The values used in tables and scatterplots (whether or not these values are stored in the SAVE region) are those copied from NMPRD4 with the last copying pass.

A copying block is a block of abbreviated code that is only executed during a copying pass, i.e. when COMACT has a positive value. Special rules apply, which allow the user to be less concerned about using the COMSAV option of the $ABBREVIATED record (See example below):

COM(i) variables that are defined in a copying block are referred to as explicit SAVE variables. PRED-defined variables that are defined in a copying block, other than COM(i) variables, are referred to as implicit SAVE variables. Collectively, the two types of SAVE variables are referred to as SAVE variables. NM-TRAN stores SAVE variables in the SAVE region of module NMPRD4.

Implicit and explicit SAVE variables cannot both appear in abbreviated code. The COMRES option of the $ABBREV record cannot be used when any implicit SAVE variables are used, but it must be used when explicit SAVE variables appear (as whenever COM(i) variables appear).

The size of the SAVE region of NMPRD4 depends on the COMSAV option of the $ABBREV record. This option may be used in three ways:

No COMSAV option. The SAVE region of module NMPRD4 will nonetheless include all the SAVE variables.
COMSAV=n (n>=0). NM-TRAN will, if necessary, extend the size of the SAVE region from n to a larger value so that all SAVE variables will be included in the region.
COMSAV=-1. There is to be no SAVE region. Variables defined in a copying block will not be SAVE variables.

EXAMPLE OF USAGE:

$ERROR
Y = F + F * EPS(1)
IPRED = F
IF (COMACT == 1) FT = F
WR = (DV - IPRED) / FT

$EST ... POSTHOC
$TABLE FT IPRED WR

With the first copying pass the value of COMACT is 1, which signals that during this copying pass, all ETA variables are set to 0. Since the option POSTHOC appears, with a subsequent copying pass the value of COMACT is 2, which signals that during this copying pass, all ETA variables are set to their conditional estimates.

In this example, WR is set to the weighted intra-individual residual. When COMACT=1, the prediction for the typical individual (ETA=0) is computed and stored in FT. FT is a SAVE variable, so this value will have been saved, and when COMACT=2, this same value will be found in FT. With COMACT=2, the weight used with the residual is computed to be the reciprocal of this FT value, while IPRED is computed from conditional estimates of the ETA variables and thus its value applies to to the individual with these estimates, rather than to the typical individual. The values of IPRED and WR appearing in the table are those obtained during the last copying pass. The tabled value of IPRED is based on the conditional estimate of ETA. The value of FT is also the value obtained during the last copying pass, but it in turn is also the value obtained from the first copying pass, as the value of FT has not changed during any subsequent copying pass, and this value is based on ETA=0.

Since FT is a SAVE variable, a SAVE region will have been allocated where this variable will be stored, and (unless there is some reason to use the COMSAV option other than to insure this) the user not be concerned about this option.

(See Section 53.13, Section 53.13) (See Section 53.84). (See Section 50.1).

REFERENCES: None.

23 CORRELATION ACROSS L2 RECORDS

MEANING: NONMEM-PRED global variables

CONTEXT: PRED and ERROR routines

USAGE:

CORRL2(n,m)=...

DISCUSSION:

An individual record is divided into L2 records. An L2 record may contain one or more observations (on one or more separate data records respectively), in which case it is called an observation-L2 record. The values of epsilons used in the intraindividual model may be correlated across the observations contained in the L2 record, and thus the L2 record may define a multivariate observation - the L2 observation. (When all L2 observations in the data set are univariate, L2 data items need not appear, and when L2 data items do not appear, NONMEM assumes that each data record is a distinct L2 record.)

By default, the values of a given epsilon are statistically independent across L2 observations within an individual record. Using CORRL2, however, these values may be correlated. More precisely, the values of the epsilons associated with the mth diagonal block of SIGMA may be correlated across L2 observations, and it will be understood that for two different epsilons (eps1 and eps2, say) associated with the mth block, the correlation between the values of eps1 for L2 observations A and B will be taken to be the same as the correlation between the values of eps2 for these same two L2 observations.

With NONMEM 7.3, reserved variable CORRL2 is used and code such as the following may be used in $ERROR and $PRED blocks.

Proceed as follows. With the first data record of the nth observation-L2 record, and with respect to the values of the epsilons associated with the mth diagonal block of SIGMA, the PRED routine should set CORRL2(k,m), for k=1,…,n, to the correlation between the values for the kth L2 observation and the nth L2 observation. (CORRL2(n,m) should be set to 1.0; in particular, with the first data record of the 1st observation-L2 record, CORRL2(1,m) should be set to 1.0.)

E.g. Suppose that the L2 observations are bivariate and chronologically ordered by a TIME data item, and suppose that the intraindividual model has two epsilons (one for each element of the bivariate L2 observation), each associated with the same diagonal block of SIGMA, Then the values of these epsilons may be autocorrelated across the L2 observations, as specified by the above code. But if the two epsilons are associated with two different diagonal blocks, then one might use this code, in which each sigma block has its own autocorrelation parameter theta(4) or theta(5):

$ABBREVIATED DECLARE T1(NO)
$ABBREVIATED DECLARE INTEGER I1
$ABBREVIATED DECLARE DOWHILE J1

IF (NEWL2 == 1 .AND. EVID == 0) THEN
 I1 = I1 + 1
 T1(I1) = TIME
 J1 = 1
 DO WHILE (J1 <= I1)
 CORRL2(J1,1) = EXP(-THETA(4) * (TIME - T1(J1))) ; Sigma block 1
 CORRL2(J1,2) = EXP(-THETA(5) * (TIME - T1(J1))) ; Sigma block 2
 J1 = J1 + 1
 ENDDO
ENDIF

$THETA 2 ; [CL]
$THETA 30 ; [V]
$THETA 0.05 ; [Rho1]
$THETA 0.075 ; [Rho2]

If you wish to have more control as to when the CORRL2 is used to model among the individual data records within the L2 records, consider the following example:

$ABBR DECLARE T1(NO),
$ABBR DECLARE INTEGER I1, DOWHILE J1

$ERROR
IF (NEWIND /= 2) I1 = 0

IF (NEWL2 == 1) THEN
 I1 = I1 + 1
 T1(I1) = TIME
 J1 = 1
 DO WHILE (J1 <= I1)
 IF (MV1 == 0.0) CORRL2(J1,1) = EXP(-THETA(4) * (TIME - T1(J1)))
 IF (MV2 == 0.0) CORRL2(J1,2) = EXP(-THETA(5) * (TIME - T1(J1)))
 J1 = J1 + 1
 ENDDO

ENDIF
IF (CMT == 1) Y = F + F * EPS(1) + EPS(2)
IF (CMT == 2) Y = F + F * EPS(3) + EPS(4)

...
$SIGMA BLOCK(2)
0.3
0.001 0.04
$SIGMA BLOCK(2)
0.7
0.001 0.08

Here MV1 and MV2 data item that is assumed to exist in the data set, and MV signals the desire to use CORRL2 on an L2 observation within an L2 record, on the first data record of the L2 record. The following is a section of data to indicate more clearly how this may be set up:

ID   TIME   L2   MV1   MV2   CMT   DV
1    2.0    1    0     0     1     0.8
1    2.0    1    0     0     2    10.0
1    4.0    2    0     0     1     0.6
1    4.0    2    0     0     2    12.0
1    6.0    3    1     1     1     0.3
1    6.0    3    1     1     2    20.0
1    10.0   4    1     0     1     0.1
1    10.0   4    1     0     2    15.0
1    14.0   5    1     1     1     0.03

Only data points with times 2, 4, and 10 hours will incorporate the correlation of the CORRL2 model. Furthermore the record of time 10 hours has MV1=1 and MV2=0, so the observation record in the 10 hour L2 record that uses Sigma block 2 will have a CORRL2 assessment, whereas the observtation in the 10 hour L2 record that uses Sigma block 1 will not be CORRL2 modeled. In the above example, Sigma block 1 consists of EPS(1) and EPS(2), and Sigma block 2 consists of EPS(3) and EPS(4), with the CMT value determining which data records use which Sigma blocks (epsilons sets) based on how Y is evaluated.

RESTRICTIONS:

SIMULATION WITH POPULATION DATA AND AUTO-CORRELATION

If population data are simulated, the correlations must be stored in CORRL2 before the NONMEM utility routine SIMEPS is called. With NONMEM 7.3, code such as the following may be used in $ERROR and $PRED blocks. Because the value of CORRL2 is set before SIMEPS is called, NM-TRAN omits the usual default call to SIMEPS.

$ABBR DECLARE T(NO), INTEGER I, DOWHILE J

IF (ICALL == 4) THEN
 IF (NEWIND /= 2) I = 0
 IF (MDV == 0) THEN
 I = I + 1
 T(I) = TIME
 J = 1
 DO WHILE (J <= I)
 CORRL2(J,1) = EXP(-THETA(4) * (TIME - T(J)))
 J = J + 1
 ENDDO
 ENDIF
 CALL SIMEPS(EPS)
ENDIF

RESTRICTIONS:

With versions of NONMEM before 7.3, C should be used rather than CORRL2. Because C is not recognized by NM-TRAN, and because of other restrictions regarding abbreviated code, a specification of C, as above, within a block of abbreviated code, must be done using verbatim code. Since NM-TRAN generated code has a call to SIMEPS in its second section (See Guide IV), this means that correlations must be computed and stored using verbatim code in the “FIRST block. (Details can be supplied on request.)

SINGLE-SUBJECT DATA

“Single-subject data” with correlated residual error, can be simulated and analyzed. To do this, though, a technique is needed which can always be used with such data: the data are handled as data from a population sample with a single individual, and OMEGA is constrained to be 0.

(See Section 53.100)

Location prior to NONMEM 7: nmprd5

REFERENCES: None.

24 CSVALIGN

MEANING: Pad a csv File with Spaces to align columns (NM75)

CONTEXT: NONMEM data file

The utility program csvalign.f90 in the util directory will pad a csv file with spaces so that the columns align, and more easily readable.

USAGE:

csvalign source.csv output.csv {number of header lines to exclude}

OPTIONS:

Inputfile: Should be the name of a data file (comma delimited) (e.g., data.csv).
Outputfile: The results are written to outputfile (will also be comma delimited).
Number of header lines to exclude: An integer value. Perhaps the header line should not be modified (so first line, and value would be 1).

EXAMPLE:

Consider file 501.csv:

C,DataDesc:Problem3,,,,,,,

C,ID,TIME,DV,AMT,RATE,WT,AGE,SEX

.,1,0,0,1000,200,58.4,51,1

.,1,1,6.47,0,0,58.4,51,1

You may not want to include the header line in considering the maximum spacing needed, so execlude it:

csvalign 501.csv 504_new.csv 1

The result is:

C,DataDesc:Problem3,,,,,,,

C ,ID ,TIME ,DV          ,AMT ,RATE ,WT ,AGE ,SEX

. ,1 ,0 ,0               ,1000 ,200 ,58.4 ,51 ,1

. ,1 ,1 ,6.47 ,0 ,0 ,58.4 ,51 ,1

See INTRODUCTION TO NONMEM 7, csvalign: Pad a csv File with Spaces to align columns.

REFERENCES: Guide Introduction_7

25 CTLO

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

USAGE:

USE NMPR_REAL, ONLY:CTLO=>CTLW,DCTLO=>DCTLW,DDCTLO=>DDCTLW

GLOBAL DECLARATION:

USE SIZES, ONLY: LVR,DPSIZE
REAL(KIND=DPSIZE) :: CTLW,DCTLW(LVR),DDCTLW(LVR,LVR)

DISCUSSION:

An observation may be the event that the value of a normally distributed variable falls in a given interval. The likelihood for this event may be automatically computed. With the data record containing the observation, one specifies the mean and variance of the variable for NONMEM, as usual, and one sets CTLO to the lower endpoint of the interval. If with population data, this endpoint depends on an eta variable, then the first- and second-derivatives of the endpoint with respect to etas should also be set. Derivatives equal to 0 need not be explicitly set, and the only elements of DDCTLO that need be set are those in the lower triangle. CTLO may be set in a $PRED or $ERROR abbreviated code, and then NM-TRAN automatically sets the derivatives. NONMEM can detect when CTLO is not set. When CTLO is set, the Laplacian estimation method must be used.

CTUP may be used in conjunction with CTLO. (See Section 53.27).

PR_CT is the estimated probability that an observation will be of the category in question. (See pr_ct, Section 53.26).

Limitation:

May not be used with the LIKELIHOOD or -2LOGLIKELIHOOD options.

Location prior to NONMEM 7: nmpr13

REFERENCES: None.

26 CTLO CTUP PROBABILITY: PR_CT

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE ROCM_REAL, ONLY PR_CT

GLOBAL DECLARATION:

USE SIZES, ONLY: DPSIZE
REAL(KIND=DPSIZE) :: PR_CT

DISCUSSION:

When with a given data record, either of the limits CTLO or CTUP are set, thus defining an interval of values comprising one of several categories equated with the possible values of a potential observation, then during a copying pass (and during ICALL=5 and 6), PR_CT is the estimated probability that an observation will be of the category in question.

(See Section 53.25, Section 53.27) (See Section 53.22, expectation, data_average)

If the mean and variance of the intra-individual model for a potential observation are specified, and if the limits CTLO or CTUP are set, a value of PR_CT will be computed, whether the record has MDV=0 or MDV=1. If neither CTLO nor CTUP are set, the value PR_CT will be 1.

PR_CT may be used as a right-hand quantity in abbreviated code for $PRED, $PK, $ERROR, and $INFN blocks.

Location prior to NONMEM 7: rocm45

REFERENCES: None.

27 CTUP

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

USAGE:

USE NMPR_REAL, ONLY CTUP,DCTUP,DDCTUP

GLOBAL DECLARATION:

USE SIZES, ONLY: DPSIZE,LVR
REAL(KIND=DPSIZE) :: CTUP,DCTUP(LVR),DDCTUP(LVR,LVR)

DISCUSSION:

An observation may be the event that the value of a normally distributed variable falls in a given interval. The likelihood for this event may be automatically computed. With the data record containing the observation, one specifies the mean and variance of the variable for NONMEM, as usual, and one sets CTUP to the upper endpoint of the interval. If with population data, this endpoint depends on an eta variable, then the first- and second-derivatives of the endpoint with respect to etas should also be set. Derivatives equal to 0 need not be explicitly set, and the only elements of DDCTUP that need be set are those in the lower triangle. CTUP may be set in a $PRED or $ERROR abbreviated code, and then NM-TRAN automatically sets the derivatives. NONMEM can detect when CTUP is not set. When CTUP is set, the Laplacian estimation method must be used.

CTLO may be used in conjunction with CTUP. (See Section 53.25).

PR_CT is the estimated probability that an observation will be of the category in question. (See pr_ct, CTLO_TUP_Probability:_PR_CT).

Limitation:

May not be used with the LIKELIHOOD or -2LOGLIKELIHOOD options.

Location prior to NONMEM 7: nmpr14

REFERENCES: None.

28 DES

MEANING: DES subroutine

CONTEXT: User-supplied subroutine; for use with PREDPP’s ADVAN 6,8,9,13,14,15,16,17,18

USAGE:

SUBROUTINE DES (A,P,T,DADT,IR,DA,DP,DT)
USE SIZES, ONLY: DPSIZE,ISIZE
INTEGER(KIND=ISIZE) :: IR
REAL(KIND=DPSIZE) :: A,P,DADT,DA,DP,DT
DIMENSION :: A(*),P(*),DADT(*),DA(IR,*),DP(IR,*),DT(*)

DISCUSSION:

The DES subroutine is called by PREDPP to evaluate right-sides of differential equations.

OPTIONS:

A(n) (input): The amount in the nth compartment at time T.
P(n) (input): The value of the nth PK parameter.
T (input): Time. T takes values continuously over an integration interval.
DADT(n) (output): The derivative with respect to T of the nth compartment’s amount. It is important to note that PREDPP itself adds in the rates for any infusions that may be active.

It is possible to introduce 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. Specifically, the amount in the output compartment may be thought of as being calculated by summing all relevant doses from the INPUT file (i.e., those that precede the time of the present record, accounting for bioavailability), subtracting all amounts present in compartments other than the output compartment, and then multiplying the result by the output fraction parameter.

For example, suppose differential equations were used for ADVAN2, rather than the analytic solution. They would be:

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

DA(n,j) (output): The derivative of DADT(n) with respect to A(j). Continuing the above example,

DA(1,1)=-P(3)
DA(2,1)= P(3)
DA(2,2)=-P(1)

DP(n,j) (output): The derivative of DADT(n) with respect to P(j). Continuing the above example,

DP(1,3)=-A(1)
DP(2,3)= A(1)
DP(2,1)=-A(2)

DT(n) (output): The derivative of DADT(n) with respect to T.

The format of arrays DA, DP, DT described above is called “full format”. Alternately, compact format may be used (See prdde1). It is the default format for these arrays. A description of compact format is beyond the scope of this document, but is described in the NONMEM 7.4 version of Guide VI, Appendix IV. Compact Arrays in DES.

Also see variables in NONMEM modules, NONMEM-PRED modules, and PREDPP modules. (See Section 53.111) In particular, (See Section 53.29, Section 53.29, Section 53.29)

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

29 DES AES: ICALL, IDEFD, IDEFA

MEANING: PREDPP read-only global variables

CONTEXT: DES and AES routines

USAGE:

USE PRMOD_INT, ONLY ICALL=>ICALLD,IDEFD,IDEFA

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: ICALLD,IDEFD(2),IDEFA(2)

DISCUSSION:

OPTIONS:

ICALL: Identical to the argument ICALL passed by NONMEM to PREDPP.
IDEFD: DES may set IDEFD when ICALL is 1, as follows. IDEFD(1) may optionally be set by DES to indicate how many thetas it uses. Set to 0 if none. Otherwise, set to the index of the highest numbered theta used. IDEFD(1)=-9 means “unknown”. PREDPP determines from the value stored in IDEFD(1) how many elements of theta to copy from its input argument THETA to THETAS. (See Section 53.31).

When IDEFD(1) is set by DES to -9, PREDPP copies all thetas in the problem to THETAS (See Section 53.31). With NM-TRAN, IDEFD(1) is set to -9 when the $DES block contains verbatim code. If a user-written DES leaves IDEFD(1) unchanged, it defaults to -9, which does no harm, but may cause the run to be slower than necessary.

IDEFD(2) The full/compact flag for DES. DES sets this as follows:

IDEFD(2)=0 DES will return compact arrays.
IDEFD(2)=1 DES will return full arrays (the default).

IDEFA: AES may set IDEFA when ICALL is 1, as follows. IDEFA(1) is set by AES to indicate how many thetas it uses. See above remarks for IDEFD and DES.

IDEFA(2) Calling protocol for ADVAN9 and ADVAN15 and ADVAN17. AES sets this as follows:

IDEFA(2)=-1 “call with every event record” (the default)
IDEFA(2)=1 “call once per individual record”

IDEFA(2) applies only when no TIME data item is defined. It is ignored when the TIME data item is defined.

Location prior to NONMEM 7: prdde1

REFERENCES: None.

30 DES AES: ISFINL

MEANING: PREDPP read-only global variables

CONTEXT: User-supplied DES and AES routines

USAGE:

USE PROCM_INT, ONLY: ISFINL

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: ISFINL

DISCUSSION:

ISFINL: When NONMEM is performing simulation or a copying pass (COMACT>0), DES and AES are called immediately after the advance to an event time or non-event time, with a value of T equal to this time. ISFINL = 1 at such a call; otherwise =0.

NM-TRAN includes this global variable in the DES or AES routine when the $DES or $AES block includes references to variable ISFINL, or when verbatim code is present.

Location prior to NONMEM 7: procmb

REFERENCES: None.

31 DES AES: THETA

MEANING: PREDPP read-only global variables

CONTEXT: User-supplied DES, AES routines

USAGE:

USE PROCM_REAL, ONLY: THETA=>THETAS

GLOBAL DECLARATION:

USE SIZES, ONLY: LTH,DPSIZE
REAL(KIND=DPSIZE) :: THETAS(LTH)

DISCUSSION:

THETA: The THETA vector passed as an argument by NONMEM to PRED, PK, ERROR. IDEFD(1) and IDEFA(1) affect how many elements are copied. (See Section 53.29, Section 53.29)

Location prior to NONMEM 7: procm6

REFERENCES: None.

32 DIFF EQ SOLVER SETTINGS

MEANING: PREDPP global variables

CONTEXT: For use with PREDPP

This feature is not fully documented. The interested user may be able to obtain more information by studying the appropriate sections of PREDPP code.

USAGE:

$PK
"FIRST
" USE PRCOM_INT, ONLY: METH,MITER,IMAX,ISTFLG,INTFLG
"MAIN
" IMAX=200000

DISCUSSION:

These variables allow the user to over-ride certain default settings in ADVAN6, ADVAN8, ADVAN9, ADVAN13, ADVAN14, ADVAN15, ADVAN16, ADVAN17, ADVAN18, SS6, and SS9.

OPTIONS:

DES_DER, MITER, and METH: PREDPP sets MITER and METH to default values with every new individual or reset record. METH is the solver method type, and MITER determines whether analytical Jacobian is to be used (MITER=1, based on DA() array calculated in DES subroutine), or Jacobian is to be numerically determined by the solver (MITER=2). As of NM75, MITER may be accessed by the reserved variable DES_DER, without requiring the “FIRST” and “USE” header lines, or verbatim code. For example:

$PK
DES_DER = 1

ADVAN8

METH=2 is always used.
If user set MITER, use his value. Otherwise, use MITER=2.

ADVAN9

If METH=1, then Adams implicit method, and METH=2 (default, BDF method).
If user did set MITER, use his value.

ADVAN13

METH set in $PK is not used. LSODA determines whether ADAMS NON-stiff (METH=1) or BDF stiff (METH=2) is to be used as it works its way through the problem.
MITER (or DES_DER) should be set only to 1 (analytical Jacobian) or 2 (numerical Jacobian determined by LSODA). Usually should be left alone.

ADVAN14

METH=2 by default. Could be set in cvodeu.f90 or $PK.
Setting MITER=1 (or DES_DER=1) is required if it is desired that the Jacobian be analytically evaluated for ODE models (ADVAN8, 9, 13, 14, 15, 16, 17), for IMP, SAEM, BAYES problems that normally do not have first derivatives turned on. In addition to setting DES_DER=1 in $PK, various options of Jacobians (analytical/numerical, full/band, etc) should be set in CVODEU.f90, where there are many other things the user can set.

ADVAN15

METH is not used. It is always METH=2 (BDF stiff).
Setting MITER=1 is required if it is desired that the Jacobian be analytically evaluated for ODE models (ADVAN8, 9, 13, 14, 15), for IMP, SAEM, BAYES problems that normally do not have first derivatives turned on. In addition to setting DES_DER=1 in $PK, various options of Jacobians (analytical/numerical, full/band, etc) should be set in IDAU.f90, where there are many other things the user can set.

ADVAN16

METH and MITER are not used. Instead, IJAC would set in RADAR5u.f90, but presently this is not functional.

ADVAN17

METH and MITER are not used. Instead, IJAC would set in RADAR5u.f90, but presently this is not functional.

ADVAN18

METH and MITER are not used.

IMAX: ADVAN6, ADVAN8, ADVAN9, ADVAN13, ADVAN14, ADVAN15, ADVAN16, ADVAN17, ADVAN18, SS6

The variable MAXCAL gives the maximum number of calls to FCN1 (ADVAN6, ADVAN8, ADVAN13, ADVAN14, ADVAN16, ADVAN18, SS6) or RES (ADVAN9, ADVAN15, ADVAN17) during an integration interval. Each of the above routines sets MAXCAL to the value given by MAXFCN (a parameter in the MODULE SIZES) at the start of each integration interval unless the user supplies a value in IMAX, in which case the user’s value is used.

ISTFLG: ADVAN9, ADVAN15, ADVAN17

ISTFLG controls how ADVAN9 calls LSODI1 and what it does if LSODI1 returns and indicates that an integration failed. ISTFLG is set to 0 (default) at ICALL=0. If changed by the user, it retains the changed value until the user changes it again. ISTATE is a variable that is passed from the ADVAN to LSODI1. ISTATE=1 indicates that the integration is starting. ISTATE=2 indicates that this call is a continuation from a prior successful integration. Default: Use ISTATE=1 for the first integration, and ISTATE=2 for a continuation when nothing external to the ADVAN has changed. In case of failure with ISTATE=2, restore original inputs and try again with ISTATE=1.

ISTFLG=1 Never try ISTATE=2, always use ISTATE=1.
ISTFLG=2 Never retry (only try ISTATE=2).

ADVAN15 also uses ISTFLG for calls to IDA, but uncertainty exists as to what its usefulness is.

INTFLG: ADVAN6, SS6, ADVAN8, ADVAN13, ADVAN14, ADVAN16, ADVAN18

INTFLG stands for “Integration Flag” and affects the number of calls to the integrating subroutine during each advance. It is only of interest when second derivatives of the state vector are calculated.

It is present because there may be some trade-off between run time and accuracy of computation. More calls to the integrator, with a smaller number of derivatives obtained with each call, result in longer run times, but might also produce more accurate derivatives. Also, it might provide more consistent computations when the number of compartments and/or etas is to be changed.

Default is -1. User may set to any other value in user-written code (e.g., with verbatim code in $PK).

PREDPP examines this value after the first call to PK for an individual record, so that it can be set on an individual-by-individual basis. PREDPP examines INTFLG when NEWIND=0 or 1 (i.e., at the start of an individual’s data). Presumably, this is the only time that NONMEM might change the LVOUT array (See Section 53.64).

When INTFLG is set to any other value than -1, ADVAN 6,8,13,14,16,18 and SS6 calculate second derivatives “one group at a time”.

E.g., with ADVAN6, suppose etas 1, 2, 3 are active.

call DVERK to obtain 2nd derivatives 1,1
call DVERK to obtain 2nd derivatives 1,2 and 2,2
call DVERK to obtain 2nd derivatives 1,3 and 2,3 and 3,3

(Each calculation involves the integration of the state vector, augmented by the relevant first derivative(s) and the second derivatives for one eta.)

Thus, the maximum number of differential equations that would ever be integrated at one time is

\[PW = 2 \cdot PE \cdot PM + PM\]

Where: (PE is the maximum number of etas; currently 10) (PM is the maximum number of compartments - 1; currently 9) PW is the size defined for various work arrays in the source code. It is currently defined as above (189).

When INTFLG is -1, the ADVAN routines and SS6 makes the most efficient use of the work arrays when computing second derivatives, to reduce the number of calls to DVERK.

At NEWIND=0 or 1, PREDPP looks at the number of active etas for this individual and the number of user-defined compartments defined by the MODEL subroutine (NCM), and creates a scheme to calculate as many groups of 2nd. derivatives at once as it can. (Although compartments may be turned on and off within the data set, PREDPP does not revise the scheme of integration each time.)

E.g., with the current values of PE, PM, and PW, here are some schemes of integration. Under “nth. call” are the etas whose second derivatives are computed with that call to DVERK.

# compts. 1st. call 2nd. call 3d. call 4th. call
  9 etas 1 - 5 etas 6 - 7 eta 8 eta 9
  8 etas 1 - 5 etas 6 - 7 eta 8 eta 9
  7 etas 1 - 5 etas 6 - 7 eta 8 - 9
  6 etas 1 - 6 etas 7 - 8 eta 9
  5 etas 1 - 7 etas 8 - 9
  4 etas 1 - 8 etas 9
  3 etas 1 - 9

Changing the size of the work arrays:

If the system is large enough that integration involves more than one call to DVERK, and the user would like all second derivatives to be computed with a single call to DVERK, the source code must be changed to define a larger value for PW.

To integrate the maximum number of etas and compartments in one call, set:

\[PW = PM \cdot (1 + PE + PE \cdot (PE+1)/2)\]

With the current values of PE and PM, PW=594.

Suppose PW is changed, but by accident is made smaller than the default (2*PE*PM+PM=189). Then for problems with large numbers of compartments and/or etas, the work arrays will not be large enough, with either INTFLG=-1 or INTFLG!=-1.

A new error message exists in PREDPP, for which PRED exit code is 2 (always abort).

WORK ARRAYS ARE TOO SMALL FOR 2ND. DERIVS. INCREASE PW, OR
DECREASE NO. OF. COMPTS AND/OR ETAS, OR USE DERIV2=NO

Again, this message cannot occur unless the source code of PREDPP is changed incorrectly.

Location prior to NONMEM 7: prcomg

REFERENCES: None.

33 DOSE RECORD: DOSREC

MEANING: PREDPP read-only global variables

CONTEXT: User-supplied PK, DES, AES routines

USAGE:

USE PROCM_REAL, ONLY: DOSREC

GLOBAL DECLARATION:

USE SIZES, ONLY: VSIZE,DPSIZE
REAL(KIND=DPSIZE) :: DOSREC(VSIZE)

DISCUSSION:

DOSREC: At a call to PK which occurs at a non-event dose time (i.e., at the time of an additional or lagged dose), DOSREC contains the (last data record of the) event record describing the dose. When PK is called at an event time, DOSREC contains 0’s.

(See Section 53.34).

Location prior to NONMEM 7: procm3

REFERENCES: Guide VI, section III.I

34 DOSE TIME NON-EVENT: DOSTIM

MEANING: PREDPP read-only global variables

CONTEXT: User-supplied PK, DES, AES routines

USAGE:

USE PROCM_REAL, ONLY: DOSTIM,DDOST,D2DOST

GLOBAL DECLARATION:

USE SIZES, ONLY: LVR,DPSIZE
REAL(KIND=DPSIZE) :: DOSTIM,DDOST(LVR),D2DOST(LVR,LVR)

DISCUSSION:

OPTIONS:

DOSTIM

DOSTIM=0: this call to PK occurs at an event time. DDOST, D2DOST, and DOSREC contain zeros.

DOSTIM>0: this call to PK occurs at a non-event dose time DOSTIM, i.e., at the time of an additional or lagged dose. DDOST, D2DOST, and DOSREC contain values of interest. (See Section 53.33).

DDOST: DDOST(i) = Partial derivative of DOSTIM with respect to eta(i).
D2DOST: D2DOST(i,j) = Second partial derivative of DOSTIM with respect to eta(i), eta(j) (lower-triangular; j=1, …, i).

When DOSTIM>0, TIME and all user (concomitant) data items in EVTREC are from the next event record. All other NONMEM/PREDPP reserved data items are from the initiating dose event record. (The $BIND record may be used to override this; (See Section 50.5))

Location prior to NONMEM 7: procm2

REFERENCES: Guide VI, section III.I

35 DOWHILE BLOCK

MEANING: Coding technique

CONTEXT: Abbreviated code

Spelling variants accepted by NM-TRAN

NM-TRAN accepts several equivalent forms for loop syntax and logical operators in abbreviated code. Verified against NONMEM 7.6.0 — all combinations parse and execute identically:

Opener: DOWHILE (cond) (one-word NM-TRAN shorthand) or DO WHILE (cond) (Fortran 90 form). Opener and closer may be mixed freely within the same block.
Closer: ENDDO (NM-TRAN abbreviated form, listed in the Part IV grammar) or END DO (Fortran 90 form).
Relational operators: F90 symbolic == /= < <= > >= or the F77 dot forms .EQ. .NE. .LT. .LE. .GT. .GE..

This HTML edition prefers DOWHILE / ENDDO and the F90 symbolic operators for consistency, but the source PDF mixes forms freely and either style is valid.

SAMPLE:

$ABBR DECLARE DOWHILE ILOOP $PK
ILOOP = 1
DOWHILE (condition)

 .. statements ..
 ILOOP = ILOOP + 1
ENDDO

DISCUSSION:

DOWHILE blocks allow loops in abbreviated code. Previously, they were permitted only in initialization-finalization, simulation, data average, and expectation blocks. See the separate descriptions of these blocks. With NONMEM 7.3, DOWHILE may also be used in data-analytic blocks (i.e., in code that is executed at ICALL=2).

When it is used in data-anlytic code, DOWHILE must be used with a looping variable. Such a variable meets three criteria:

It is declared as such, e.g. $ABBR DECLARE DOWHILE ILOOP
It is given a value in the statement immediately before DOWHILE.
It is given a value in the statement immediately before ENDDO.

Usually, the looping variable will be tested in the condition, but this is not necessary.

DOWHILE blocks may be nested.

DOWHILE blocks may not include IF/THEN/ENDIF blocks. Only single-statement IF statements are permitted. E.g., IF (condition) statement.

Subscripted variables may be used within the block. These are variables that have been declared arrays using the $ABBR statement, or subscripted reserved variables such as THETA. Subscripts may be integer expressions using declared integer variables and integer values. E.g.

$ABBR DECLARE X(10)
$ABBR DECLARE DOWHILE ILOOP

...
$PK
ILOOP = 1
DOWHILE (condition)
 X(ILOOP) = THETA(ILOOP + 1)
 ILOOP = ILOOP + 1
ENDDO

(See Section 53.1).

A DOWHILE loop may compute recursive random variables. These are variables that are modified recursively in a dowhile block and which have eta derivatives. For example,

TERM = THETA(1) * EXP(ETA(1))
SUM = 0
ILOOP = 1
DO WHILE (ILOOP <= IMAX)
 SUM = SUM + TERM
 ILOOP = ILOOP + 1
ENDDO

The dowhile recursive variable must be initialized to a non-random variable outside the loop and must appear on both sides of the equal sign only once within the DOWHILE loop: V= ... V ....

The syntax is very limited. The following are not permitted:

ILOOP = 1
DO WHILE (ILOOP <= IMAX)
 IF (ILOOP == 1) SUM = 0 ; initialization within the loop
 SUM = SUM + TERM
 ILOOP = ILOOP + 1
ENDDO

ILOOP = 1 ; initialization within the loop
DO WHILE (ILOOP <= IMAX) ; else statement
 IF (ILOOP == 1) THEN
 SUM = 0
 ELSE
 SUM = SUM + TERM
 ENDIF
 ILOOP = ILOOP + 1
ENDDO

Although the example given is a summing loop, a product loop such as

PROD = PROD * TERM

is also possible, as are other ways the dowhile recursive variable can be used. The looping variable ILOOP may also be set and tested and incremented with different integers than shown.

EXAMPLES:

Several examples are present in the examples directory:

Auto-correlation (See ar1mod.ctl)
Auto-correlation with Simulation (See ar1newsim.ctl).
Dose Superposition (See sumdosetn.ctl)
Summing elements of THETA (See superid3_6.ctl)

REFERENCES: None.

36 ERROR

MEANING: ERROR subroutine

CONTEXT: User-supplied subroutine; for use with PREDPP

USAGE: Versions before NONMEM 7.2:

SUBROUTINE ERROR (ICALL,IDEF,THETA,IREV,EVTREC,NVNT,INDXS,F,G,HH)
USE SIZES, ONLY: DPSIZE,ISIZE,LVR
INTEGER (KIND=ISIZE) :: ICALL,IDEF,IREV,NVNT,INDXS
REAL(KIND=DPSIZE) :: THETA,F,G,HH
DIMENSION IDEF(*),THETA(*),EVTREC(IREV,*),INDXS(*),G(LVR,*)
DIMENSION HH(LVR,*)

With NONMEM 7.2 and higher:

SUBROUTINE ERROR (ICALL,IDEF,THETA,IREV,EVTREC,NVNT,INDXS,F,G,HH)

USE SIZES,       ONLY: DPSIZE,ISIZE

USE PRDIMS, ONLY: GERD,HERD

IMPLICIT REAL(KIND=DPSIZE) (A-Z)

REAL(KIND=DPSIZE) :: EVTREC

INTEGER(KIND=ISIZE) :: ICALL,IDEF,IREV,NVNT,INDXS

DIMENSION :: IDEF(*),THETA(*),EVTREC(IREV,*),INDXS(*)

REAL(KIND=DPSIZE) :: G(GERD,*),HH(HERD,*)

DISCUSSION:

The ERROR subroutine is called by PREDPP to model intra-individual error in observed values. 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).

OPTIONS:

ICALL (input)

ICALL=1: ERROR has been called for initialization at the beginning of a NONMEM problem; one such call per problem. EVTREC contains the first event record. THETA contains the initial estimates. ERROR must return values in IDEF which inform PREDPP what tasks it will perform at later calls. It may also set elments of HH to the appropriate derivatives, when it has requested that ERROR be called only once per problem.

ICALL=2: ERROR has been called to obtain the modeled value; multiple calls occur. ERROR should compute derivatives of F for HH. If ERROR changes F, it should also change the derivates of F in G.
ICALL=4: ERROR has been called during the Simulation Step; multiple calls occur. ERROR should compute simulated observations and store them in F.
ICALL=5: ERROR has been called during the computation of expectations; multiple calls occur. Such calls occur when the marginal (MRG_) data item is defined in the data set and has non-zero values for some records. If the MRG_ data item has the value 1 or 2, expectations are computed for that record, and the value returned by ERROR in F contributes to the expectation that is being computed for the PRED data item. The value of an ERROR-defined item contributes to the expectation computed for the item.
ICALL=6: ERROR has been called during the computation of raw data averages; multiple calls occur. Such calls occur when the raw-data (RAW_) data item is defined in the data set and has the value 1 for some records (See template). ERROR may re-compute DV when the value of DV in the data record is not the quantity to be included in the average. ERROR may return a value of 1 in F if no DV item is to be included in the average with the particular record.

THETA (input): The NONMEM THETA vector.
EVTREC (input): The PREDPP event record.
INDXS (input): The values specified in the $INDEX record of the NM-TRAN control stream. (This is the NONMEM INDXS array starting at position 12, the first position beyond those positions used by PREDPP itself.)
IDEF (output): ERROR should store values in IDEF only when ICALL=1. A value of 1 in IDEF(1) indicates that ERROR will store the derivatives of log y in HH (which causes PREDPP to multiply each element of HH by F). That is, PREDPP understands that the “error in log y” is modeled.

The value in IDEF(2) describes when ERROR should be called:

-1 call with every event record.
0 call once per observation record.
1 call once per individual record.
2 call once per problem.

The value in IDEF(3) describes whether ERROR uses derivatives of compartment amounts (i.e. whether compartment amounts themselves are used as random variables in arithmetic statements in ERROR).

-1 ERROR may use derivatives of A.
0 ERROR does not use derivatives A.
1 ERROR does use derivatives of A.

The default used by PREDPP is IDEF(3)=-1. However, when ERROR does not use A, then if IDEF(3) is set to 0, PREDPP can avoid some time-consuming processing. Indeed, when $ERROR abbreviated code is supplied, and there is no reference to a compartment amount A(n) (as a random variable in an arithmetic statement) in the abbreviated code (or to its derivatives in verbatim code), then NM-TRAN sets IDEF(3)=0.

F (input/output): On input, the prediction based on the pharmacokinetic model, i.e., the value of the scaled drug amount in the observation compartment. On output, F may be unchanged, or it may be modified, e.g., when a PD prediction is needed. If ERROR modifies F and uses population eta variables to do so, then at ICALL=2 ERROR must call GETETA to obtain eta values prior to modifying F. When ICALL=4, ERROR should calculate the simulated observation (after calling SIMETA and/or SIMEPS to obtain simulated etas and epsilons, as necessary) and place its value in F. With the Simulation Step, ERROR may return the simulated observation as the DV data item, rather than in the argument F. With odd-type data the simulated observation must be returned as the DV data item. (See Section 50.15).
G (input/output): On input, at ICALL=2 when the data are population, an array of partial derivatives of F with respect to etas. G(i,1) is the partial derivative of F with respect to eta(i). G(i,j+1) is the second derivative of F with respect to eta(i), eta(j) (lower-triangular; j=1, …, i). (Second derivatives are only needed with estimation by the Laplacian method.) On input, G contains zeros when the data are single-subject data. At ICALL=2, ERROR must modify G when it has changed F and has thus changed the derivatives of F with respect to the population etas.
HH (output): An array of partial derivatives of F with respect to etas (when the data are single-subject data) or epsilons (when the data are population). Values should be stored when ICALL=2 and also when ICALL=1 if ERROR sets IDEF(2)=2. HH(i,1) is the derivative of F with respect to eta(i) or eps(i). HH(i,j+1) is the derivative of H(i,1) with respect to eta(j) (but are only needed with conditional estimation when the dependence on etas of the variance of intra-individual random error should be preserved in the computation of the objective function; see the INTERACTION option (See Section 50.15)).

Also see NONMEM read-only modules (of the form ROCMn), NONMEM-PRED modules (of the form NMPRDn), and PREDPP read-only modules (of the form PROCMn).

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

37 ESTIM COVAR ERROR CODES

MEANING: NONMEM read-only global variables

CONTEXT: PRED routine

USAGE:

USE ROCM_INT, ONLY: IERE=>IEST_ERR,IERC=>ICOV_ERR

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: IEST_ERR,ICOV_ERR

DISCUSSION:

IERE: The return code from the Estimation Step.
IERC: The return code from the Covariance Step.

Values of 0 indicate normal termination.

These variables may be used as right-hand quantities in abbreviated code for initialization/finalization blocks.

Location prior to NONMEM 7: rocm9

REFERENCES: None.

38 ETASXI

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

USAGE:

USE NMPRD_INT, ONLY: ETASXI

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE), ALLOCATABLE, DIMENSION(:) :: ETASXI

DISCUSSION:

With NONMEM 7, an alternative eta shrinkage evaluation using empirical Bayes variances (EBVs, or conditional mean variances) are now also reported. The $ESTIMATION record option ETASTYPE=0 requests that eta shrinkage be averaged for all subjects. This is the default. With ETASTYPE=1, eta shrinkage is averaged only among subjects that provided a non-zero derivative of their data likelihood with respect to that eta.

Reserved variable ETASXI(i) may be used to specify certain etas of particular subjects to be included, or to specify certain etas of certain subjects to be excluded, from the average eta shrinkage assessment. ETASXI stands for eta shrinkage exclude/include. The subscript i refers to ETA(i).

If ETASXI(i) is set to 2, ETA(i) is included. If ETASXI(i) is set to 1, ETA(i) is excluded.

This overrides whatever would happen based on ETASTYPE.

EXAMPLE:

ETASXI(3) = 1
ETASXI(4) = 2

For all subjects, ETA(3) is excluded and ETA(4) is included.

ETASXI can be set differently for certain subjects.

EXAMPLE:

IF (ID == 3) ETASXI(1) = 1
IF (ID == 23) ETASXI(3) = 2

This excludes ETA(1) for subject 1, and includes ETA(3) for subject 23.

ETASXI may be set only in $PK and $PRED blocks.

The additional output file root.shm (which stands for shrinkage map) will contain information which etas were excluded in the eta shrinkage assessment.

REFERENCES: Guide Introduction_7

39 EVENT RECORD: EVTREC

MEANING: PREDPP read-only global variables

CONTEXT: User-supplied DES and AES routines

USAGE:

USE PROCM_REAL, ONLY: EVTREC
USE PROCM_INT, ONLY: NVNT=>NEVENT

GLOBAL DECLARATION:

USE SIZES, ONLY: PD,DPSIZE
REAL(KIND=DPSIZE) :: EVTREC(5,PD+1)
INTEGER(KIND=ISIZE) :: NEVENT

DISCUSSION:

OPTIONS:

EVTREC: Identical to the argument EVTREC passed by PREDPP to PK and ERROR routine.
NVNT: Identical to the argument NVNT passed by PREDPP to PK and ERROR routines.

Location prior to NONMEM 7: procm7

REFERENCES: Guide VI, section III.C

40 EXPECTATION BLOCK

MEANING: Abbreviated code for computation of expectations

CONTEXT: Abbreviated code

SAMPLE:

$ERROR
IF (ICALL == 5) THEN

 ... expectation block ...
ENDIF

DISCUSSION:

An expectation block is a block of abbreviated code that is only executed when ICALL=5. This value of ICALL occurs when the marginal (MRG_) data item is defined in the data set and has a non-zero value for some records. Expectation blocks are not required when the marginal data item is present, but they allow the user additional functionality. Such blocks may be present in $PRED, $PK, $ERROR.

If the MRG_ data item has the value 1 in a data record, PRED- (PK- and ERROR-) defined items displayed for the record (e.g. in the row of a table corresponding to the record) are expectations. When ICALL=5, the expectations are being computed. With each call to PRED with the data record, the value being set in Y is contributing to the expectation being computed for the PRED item, and the value being set for a PRED-defined item that will be displayed in a table or scatterplot (except for an item stored in the SAVE region) is contributing to the expectation being computed for that item.

In this example, the displayed value of PRED with a record having MRG_=1 is the expectation of the 0-1 variable taking the value 1 if and only if F > 10.

IF (ICALL == 5) THEN
 Y = 0
 IF (F > 10) Y = 1
 RETURN

ENDIF

Special rules apply to expectation blocks and passes through the data with ICALL=5.

No eta derivatives are computed in an expectation block.
Calls to certain NONMEM utility routines are permitted in an expectation block:

CALL RANDOM(n,R)

where n is an integer 1-10. If CALL RANDOM is present, R becomes a reserved variable, and may not be used outside the expectation block. Multiple calls to RANDOM may be present.

A RETURN statement may be used in an expectation block. If Y= appears (i.e. Y is assigned a value) in an expectation block before the RETURN (not necessarily the in same block containing the RETURN), then F is set to Y (F=Y); otherwise F is set to 0 (F=0). If there is no RETURN statement in the expectation block, then as usual, F is set to the value of Y assigned by the time PRED (PK, ERROR) exits.
Loops are permitted in an expectation block. The syntax is as follows.

DO WHILE (condition)
 .. statements ..
END DO

If a mixture model is used, then during calls with ICALL=5, both MIXNUM and MIXEST are the index of the subpopulation into which the individual (whose data record is being passed) has been classified.

(See mrg).

REFERENCES: None.

41 F_FLAG

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

USAGE:

USE NMPR_INT, ONLY: F_FLAG=>IPRDFLG1

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: IPRDFLG1

DISCUSSION:

When either of the options LIKELIHOOD or -2LOGLIKIHOOD appear in the $ESTIMATION record, this indicates that for all observations, the variable Y (with NM-TRAN abbreviated code) or F (with a user-supplied PRED or ERROR routine) is being set to a likelihood (or -2 log likelihood) value for the observation. Suppose, though, that neither option appears. Then for a given observation, the default indication is that Y or F is being set to a “prediction” of the observation. This is equivalent to setting the variable F_FLAG to its default value of 0. When, however, the variable F_FLAG is set to the value 1 (or 2) in the PRED or ERROR routine, this signals that Y or F is being set to a likelihood (or -2 log likelihood) value for this particular observation.

F_FLAG may be set in NM-TRAN abbreviated code.

IF (TYPE == 1) THEN
 Y = THETA(1) + ETA(1) + ERR(1) ; a prediction
ELSE
 F_FLAG = 1
 A = EXP(THETA(2) + ETA(2))
 B = 1 + A
 Y = DV * A / B + (1 - DV) * 1 / B ; a likelihood
ENDIF

A nonzero value of F_FLAG has no effect during a Simulation Step. But note: When single-subject data are simulated for which, when the data are later analyzed, Y (F) would always be set to a likelihood, and when the ONLYSIMULATION option is used in the $SIMULATION record, then usually the NOPREDICTION option can also be used. When the NOPREDICTION option is used, if any eta’s are used in the model, the data are regarded as population data, but the model for the data in question usually does not involve eta variables. When, however, single-subject data are simulated for which, when the data are analyzed, Y (F) would sometimes be set to a likelihood and sometimes to a “prediction”, and when the ONLYSIMULATION option is used in the $SIMULATION record, then the PREDICTION option will need to be used (this is the default option!). The reason is that the expression of residual variability associated with the predictions will involve eta variables.

RESTRICTIONS:

When F_FLAG is set to a non-zero-value for some observation, neither the LIKELIHOOD or -2LOGLIKIHOOD option may be used.

When F_FLAG is set to a nonzero-value for an observation, the Laplacian estimation method must be used.

Unless with all observations within an individual record, F_FLAG is 0, the RES and WRES items will be 0 for all data records in the individual record.

When F_FLAG is set to a nonzero-value for an observation within an individual record, inter-L2 correlated epsilons are not allowed with the observations within the individual record. (See Section 53.23)

If the data are population data, a nonzero value of F_FLAG cannot be used within a multiple-observation L2 record. If the data are single-subject data, a nonzero value of F_FLAG cannot be used within a multiple-observation L1 record.

Location prior to NONMEM 7: nmpr17

REFERENCES: None.

42 `ICALL`

MEANING: Argument of user-supplied subroutines

CONTEXT: User-supplied routines

DISCUSSION:

ICALL is an argument passed by NONMEM to user-supplied subroutines CCONTR, CONTR, CRIT, PRED, PRIOR and MIX.

PREDPP selectively passes the same argument to PK, ERROR, and INFN. ICALL can be used in $PK, $ERROR, and $PRED abbreviated code. The discussion below describes the values of ICALL as seen by PRED.

ICALL=-1: the routine has been called for the PRED_IGNORE_DATA feature of NONMEM 7.5. One call per data record, at the start of the run. These calls occur only if abbreviated code uses variables PRED_IGNORE_DATA or PRED_IGNORE_DATA_TEST, or if the PRED_IGNORE_DATA option of $DATA is used. Otherwise, there are no calls to PRED with ICALL=-1.

ICALL=0: the routine has been called for initialization at the beginning of the NONMEM run; one such call per run.

ICALL=1: the routine has been called for initialization at the beginning of a NONMEM problem; one such call per problem.

ICALL=2: the routine has been called for a prediction. Multiple calls occur.

ICALL=3: the routine has been called for finalization at the end of a NONMEM problem; one such call per problem.

ICALL=4: the routine has been called during the Simulation Step; multiple calls occur, as with ICALL=2.

ICALL=5: the routine has been called when expectations are being computed; multiple calls occur.

ICALL=6: the routine has been called when raw data averages are being computed; multiple calls occur.

NOTE: Some subroutines are called with only a subset of the possible values of ICALL.

REFERENCES: Guide I, section C,4.2

REFERENCES: Guide IV, section IV.D, IV.E.1

REFERENCES: Guide VI, section III.C, IV.B.1

43 INDICATOR VARIABLES

MEANING: Coding technique

CONTEXT: Abbreviated code

DISCUSSION:

An indicator variable is a variable whose value is 0 or 1. It may be identified with an input data item, or it may be a variable defined in the abbreviated code. It is used to make a choice in a computation.

Suppose, for example, ICU is a variable which is either 0 or 1. The following code can be used:

IF (ICU == 0) THEN
 CLM = TVCLM + ETA(1)
ELSE
 CLM = TVCLM + ETA(2)
ENDIF

This can be coded unconditionally using an indicator variable:

CLM = TVCLM + (1 - ICU) * ETA(1) + ICU * ETA(2)

Unconditional code is preferred when MU variables are computed.

In Guide V, Chapter 12, appears this example involving observations of two types, CP and effect. The latter is modeled by the Emax model. Observations of both types are recorded in the DV data item. A data item called TYPE with values 1 and 2 is used to distinguish between them. This data item may be used to compute the appropriate prediction in the $ERROR block, as follows:

$ERROR
EMAX = THETA(5) + ETA(3)
C50 = THETA(6) + ETA(4)
EFF = EMAX * F / (C50 + F)
Y1 = EFF + ERR(1)
Y2 = F + ERR(2)
IF (TYPE == 2) THEN
 Y = Y2
ELSE
 Y = Y1
ENDIF

The last five lines of this example can also be coded as follows:

Q = 1
IF (TYPE == 2) Q = 0
Y = Q * Y1 + (1 - Q) * Y2

A more general technique is to use two indicator variables. This technique can easily be extended to the case of three or more choices.

$ERROR
EMAX = THETA(5) + ETA(3)
C50 = THETA(6) + ETA(4)
EFF = EMAX * F / (C50 + F)
Y1 = EFF + ERR(1)
Y2 = F + ERR(2)
Q1 = 0
Q2 = 0
IF (TYPE == 1) Q1 = 1
IF (TYPE == 2) Q2 = 1
Y = Q1 * Y1 + Q2 * Y2

REFERENCES: Guide V, section 7.5.3, 7.5.4, 12.5

44 `INFN`-DEFINED VARIABLES

MEANING: INFN-defined global variables

CONTEXT: User-supplied routines

USAGE:

MODULE INFNP
USE PRINFN, ONLY: TLCOM=>ITV
END MODULE INFNP

GLOBAL DECLARATION:

MODULE PRINFN
USE SIZES, ONLY : DPSIZE,DIMTMP
IMPLICIT NONE
SAVE
REAL(KIND=DPSIZE), TARGET, DIMENSION (DIMTMP):: ITV
END MODULE PRINFN

DISCUSSION:

PRINFN is a module for INFN-defined variables. It contains an array ITV. (TLCOM is suggested above as an alternate to the name ITV to be consistent with generated code, but this is optional.) Variables are stored in PRINFN for communication with other other blocks of abbreviated code or with user-written codes. These are variables defined first in $INFN or in $PK-INFN or $ERROR-INFN blocks. Module PRINFN is declared in all generated routines PK, ERROR, etc., and the variables can be used as right-hand quantities in these routines. INFN-defined variables are not initialized or modified by NONMEM or PREDPP. Hence the variables in the module may be initialized or modified at ICALL values 0 or 1 or 3, and will retain whatever values they are given. These variables cannot be displayed in tables or scatterplots. If they are to be displayed, WRITE statements can be used, or their values can be assigned to variables that are listed in module NMPRD4. (See Section 53.84).

Variables from PRINFN can be used in a user-written code. MODULE INFNP must be defined as above prior to the SUBROUTINE statement. The variables have names TLCOM(1), TLCOM(2), etc. E.g., X=TLCOM(1)/TLCOM(2). It is possible to give the variables the same (non-subscripted) names that they had in $INFN. Suppose variables X1 and X2 are used in $INFN, and the following is present in the generated INFN routine:

      X1=>TLCOM(00001); X2=>TLCOM(00002)

In the user-written code, after the last declaraction, include:

      POINTER :: X1,X2

Prior to the first executable statement, include:

      X1=>TLCOM(1); X2=>TLCOM(2)

Now the code is X=X1/X2.

Code generated by NM-TRAN is somewhat more complex, but achieves the same result.

REFERENCES: None.

45 INITIAL STEADY STATE: I SS, ISSMOD

MEANING: PREDPP-PK global variables

CONTEXT: PK routine

USAGE:

USE PRMOD_INT, ONLY: I_SS,ISSMOD

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: I_SS,ISSMOD

DISCUSSION:

Used for the Initial Steady State feature of PREDPP, with the general non-linear models (ADVAN6, ADVAN8, ADVAN9, ADVAN13, ADVAN14, ADVAN15, ADVAN16, ADVAN17, ADVAN18). By default, the initial conditions (i.e., compartment amounts) are zero at the start of each individual record. Different initial conditions may be computed using the I_SS (Initial Steady State) feature of MODEL and/or PK.

ISSMOD may be set by MODEL. (Note that the option of the $MODEL record is I_SS, not ISSMOD.)

Default: -1 (MODEL does not request the I_SS feature)

Values 0, 1, 2 and 3 are permitted. Value 0 requests that no steady state be computed. ISSMOD values 1, 2, or 3 requests that PREDPP compute an initial steady state for the model before the first event record of an individual record, or after a reset event. The results are identical to those that would be computed by a steady-state dose event record with SS=ISSMOD and AMT=0 and RATE=0. If endogenous drug is specified in the differential equations, non-zero initial conditions will be computed.

I_SS may be set by PK.

Default: -1 (PK does not request the I_SS feature)

Values are the same as ISSMOD, with the same effect. This allows I_SS to be set conditionally, e.g., if some subjects are at steady-state and others are not. If both ISSMOD and I_SS are set, then the value of I_SS overrides that of ISSMOD.

There is no difference between values 1, 2 and 3 of I_SS unless the PK routine also uses the compartment initialization feature A_0. The I_SS feature behaves exactly like a steady state dose record in this regard. Specifically,

With I_SS=1 (“reset”), values of A_0 are ignored.
With I_SS=2 (“sum”), values of A_0 are added to the SS values.
With I_SS=3 (“initial ests”), values of A_0 are used as initial estimates when computing the SS values.

(and similarly for ISSMOD).

If ISSMOD is set, or I_SS is set at ICALL=1, PREDPP will acknowlege the fact in the NONMEM output.

When I_SS or ISSMOD is set, even if only to 0, then SSS and the appropriate SS routine are included in the NONMEM executable.

When I_SS or ISSMOD is set, even if only to 0, or verbatim code is present in the $PK or $INFN block, then NM-TRAN includes I_SS,ISSMOD in the PK and/or INFN routine.

Example: $PK may include code such as

IF (TYPE == 1) THEN
 I_SS = 1
ELSE
 I_SS = 0
ENDIF

(See Section 53.55, Section 53.77, Section 53.55, Section 53.77).

Location prior to NONMEM 7: prdpk4

REFERENCES: None.

46 INITIALIZATION-FINALIZATION BLOCK

MEANING: Abbreviated code for initialization and finalization

CONTEXT: $PRED, $PK, $ERROR, $INFN abbreviated code

SAMPLE:

$PRED

IF (ICALL == 1) CALL SUPP(0,1)

DISCUSSION:

A run consists of one or more problems, and each problem consists of one or more subproblems, which are iterations of various tasks specified in the problem. The “end” of a subproblem refers to the end of such an iteration. Problems themselves may be organized into superproblems, which may be iterated. The “beginning” and “end” of a superproblem refers to the beginning and end of the first and last iterations of the superproblem.

There are opportunities to make some rudimentary computations at:

the beginning of a run (run initialization)
the beginning of a superproblem (superproblem initialization)
the beginning of a problem (problem initialization)
the end of a subproblem (subproblem finalization)
the end of a problem (problem finalization)
the end of a superproblem (superproblem finalization)
the end of a run (run finalization)

For example, data transgeneration may take place at problem initialization. Or, a variable may be initialized at problem initialization and modified at each subproblem finalization, and its final value written to a user file at problem finalization. There is no opportunity to do subproblem initialization. When using abbreviated code, initialization and finalization opportunities are signalled by values of the variable ICALL:

ICALL=0

Run initialization.

ICALL=1

Superproblem and Problem initialization. ICALL is set to 1 to signal problem initialization. When this happens: If a superproblem requires initialization, test

S1IT (number of current superproblem iteration) equals 1 (or S2IT=1),
S1NUM (number of current superproblem) equals appropriate value, and
IPROB (number of current problem) equals number of first problem in superproblem,

and if (i)-(iii) are true, do superproblem initialization (See Section 53.89).

ICALL=3

Subproblem, Problem, Superproblem and Run finalization. ICALL is set to 3 to signal problem finalization. When this happens: If a problem with subproblems requires finalization, test IREP=NREP (number of the current subproblem equals total number of subproblems) and if true, do problem finalization (See Section 53.99, Section 53.99). If a superproblem requires finalization, test

S1IT=S1NIT (number of the current superproblem iteration equals total number of superproblem iterations) (or S2IT=S2NIT),
S1NUM (number of current superproblem) equals appropriate value,
IPROB (number of current problem) equals number of last problem in the superproblem, and
IREP=NREP, if there are subproblems with the last problem in the superproblem

and if (i)-(iv) are true, do superproblem finalization. If a run having multiple problems requires finalization, test

S1IT=S1NIT (or S2IT=S2NIT), if there are superproblems
S1NUM equals number of last superproblem, if there are superproblems,
IPROB=NPROB (number of the current problem equals total number of problems), and
IREP=NREP, if there are subproblems with the last problem in the superproblem

and if (i)-(iv) are true, do run finalization.

An initialization block is a block of abbreviated code that is only executed at ICALL=0 or ICALL=1. A finalization block is a block of abbreviated code that is only executed at ICALL=3. E.g.,

IF (ICALL == 1) THEN
 ... initialization block ...
ENDIF

Such blocks may be present in $PRED, $PK, $ERROR, and $INFN blocks of abbreviated code. If such blocks are present in $PK or $ERROR, an INFN routine is used to implement the logic in these blocks. Initialization and finalization blocks will be implemented by means of a generated FORTRAN subroutine.

Variables may be used as right-hand quantities even before they are defined; if an expression which uses such a variable is computed before any value of the variable is computed, the computation of the expression will be uncertain.

Assignment, conditional, WRITE and PRINT statements may be used.

In addition, these rules apply:

Defined quantities are not regarded as random variables; eta derivatives are not computed in an initialization or finalization block

Transgeneration of the data is permitted. NONMEM data items ID and MDV may not be changed. If a data item label may appear on the left of an assignment statement, then NM-TRAN generates assignment statements changing first the data item in the event or data record, and then the value of the local variable having that label. Note, however, that at ICALL=0,1,or 3, by default, references to data items are references to those data items in the first data or event record. To transgenerate an item in any data or event record (including the first), use of the NONMEM utility routine PASS is required. See below.

Calls to certain NONMEM routines are permitted:

CALL PASS(MODE)
CALL RANDOM(n,R)
CALL SUPP(ie,ic)

CALL PASS(MODE) must be coded exactly in this way. If CALL PASS(MODE) is present, MODE becomes a reserved variable and may be used only with other instances of CALL PASS(MODE). Multiple calls to PASS may be present.

If CALL RANDOM(n,R) is present, R becomes a reserved variable and may be used only with other instances of CALL RANDOM(n,R). n may only be an integer value 1-10.

SUPP is used to suppress portions of the NONMEM output report. (See Section 59.20). The arguments ie and ic may only be 0 or 1.

The following variables may be used on the right (their values change with calls to PASS):

Data record items (See Section 53.76).
NEWIND (See Section 53.75).
NIREC, NDREC (See Section 53.92, Section 53.92).
NEWL2 (See Section 53.74).
ETA when ICALL=3 (See Section 53.97, Section 53.97)
LIREC (See Section 53.101)
PRED_, RES_, WRES_ when ICALL=3 (See Section 53.79, Section 55.16, Section 55.16).
IERE, IERC when ICALL=3 (See Section 53.37).
NINDR, INDR1, INDR2 (See Section 53.63).
NREP, IREP (See Section 53.99, Section 53.99).
NPROB, IPROB, S1NUM, S2NUM, S1NIT, S2NIT, S1IT, S2IT (See Section 53.89).

RETURN and EXIT statements may be used.

DOWHILE loops are permitted. The syntax is as follows.

DO WHILE (condition)
 .. statements ..
END DO

Here is an example of a transgeneration loop.

$PRED
IF (ICALL == 0) THEN
 MODE = 0
 CALL PASS (MODE)
 MODE = 2
 CALL PASS (MODE)
 DO WHILE (MODE == 2)
 ... transgeneration statements ...
 CALL PASS (MODE)
 ENDDO
 RETURN
ENDIF

This type of usage of the PASS routine can be coded more simply, as follows:

$PRED
IF (ICALL == 0) THEN
 DOWHILE (DATA)
 ... transgeneration statements ...
 ENDDO
 RETURN
ENDIF

The DOWHILE (DATA) causes the transgeneration statements to be executed with each data record. In effect, NM-TRAN supplies the statements MODE=... and CALL PASS(MODE) that are shown in the above.

Variables that are first defined in an initialization block or finalization block are not stored globally in NMPRD4, but rather, are stored in module PRINFN. (This makes them available to subroutine MIX.)

Variables defined in an initialization or finalization block may be used freely outside of such blocks, and vice versa: PRED-defined variables defined outside such blocks may be used within them.

THETA variables may be used in initialization and finalization blocks. They are obtained from the subroutine argument.

At ICALL=0, THETA contains the initial estimates for the first problem.
At ICALL=1, THETA contains the initial estimates for the current problem.
At ICALL=3, THETA contains the final estimates for the current problem.

Here is an example of code that could be used during a simulation with multiple subproblems.

$PRED
IF (ICALL == 1) THEN
 SUM = 0
 N = 0
 RETURN
ENDIF

IF (ICALL == 3) THEN
 N = N + 1
 SUM = SUM + THETA(1)
 RETURN
ENDIF

IF (ICALL == 3 .AND. N == NREP) THEN
 MEAN = SUM / N
 PRINT *,MEAN
ENDIF

The following variables may be referenced as right-hand quantities in initialization and finalization blocks. (Note also that unsubscripted arrays may appear in a WRITE statement.)

OMEGA(n,m)
SIGMA(n,m)

(See Section 53.71).

(See Section 53.114).

The following variables may be referenced as right-hand quantities in finalization blocks. (Note also that unsubscripted arrays may appear in a WRITE statement.)

SETHET(n)
SETHETR(n)
SEOMEG(n,m)
SESIGM(n,m)
OBJECT

(See Section 53.104).

(See Section 53.68).

(See Section 53.114).

The following statements are forbidden:

CALL SIMETA(ETA)
CALL SIMEPS(EPS)

When the PRED repetition feature is used, the variables RPTO and PRDFL may appear as left-hand quantities in initialization blocks. (See Section 53.94).

(See Section 50.1).

REFERENCES: Guide II, section D.2.2

REFERENCES: Guide VI, section VI.A, Figure 37

47 MDVRES

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

USAGE:

USE NMPRD_INT, ONLY: MDVRES

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: MDVRES

DISCUSSION:

MDVRES stands for missing dependent variable (MDV) for residual (RES). Setting MDVRES to 1 is equivalent to temporarily declaring an observation as missing during the computation of residuals and weighted residuals.

MDVRES=0 (default)

Set MDVRES to 1 in the $ERROR or $PRED routine if you do not want to include a particular observation in the computation of residual and weighted residuals.

One situation in which this may be useful is when F_FLAG is used because some observations are predictions (F_FLAG=0) and others are likelihood or -2 log likelihood values (F_FLAG=1 or F_FLAG=2). By default, if F_FLAG is set to 1 or 2 for any observation within an individual record, the RES and WRES items will be 0 for all data records in the individual record. When MDVRES is set to 1 for any observation, this overrides the default. NONMEM will compute RES and WRES for all observations for which MDVRES is set to 0. MDVRES should be set to 1 with all observations having F_FLAG=1 or F_FLAG=2, but may be set to 1 for other observations as well.

EXAMPLE:

Supose that some observations are assessed by a non-normal distribution likelihood such as the PHI() function for below detection limit values, in which F_FLAG is set. By setting MDVRES=1 to these particular below detection values, the weighted residual algorithm can assess the remaining normally distributed values for that subject.

$ERROR
SD = THETA(5)
IPRED = LOG(F)
DUM = (LOQ - IPRED) / SD
CUMD = PHI(DUM)
IF (TYPE == 1) THEN
 F_FLAG = 0
 Y = IPRED + SD * ERR(1)
ENDIF
IF (TYPE == 2) THEN
 F_FLAG = 1
 Y = CUMD
 MDVRES = 1
ENDIF

REFERENCES: Guide Introduction_7

48 MIX CONTR: TEMPLT

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied PRED routine

USAGE:

USE ROCM_REAL, ONLY: TEMPLT=>VRAW

GLOBAL DECLARATION:

USE SIZES, ONLY: VSIZE,DPSIZE
REAL(KIND=DPSIZE) :: VRAW(VSIZE)

DISCUSSION:

TEMPLT

This variable serves two different purposes.

At ICALL=6, the template data record is stored in TEMPLT.
When MIX is called, the first data record of the individual record is stored in TEMPLT.

TEMPLT(n) may be used as a right-hand quantity in blocks of abbreviated code that test for ICALL=6 and in $MIX blocks. The “n” may be either a position in the data record or the label of the data item, e.g. TEMPLT(1) or TEMPLT(ID).

Location prior to NONMEM 7: rocm31

REFERENCES: None.

49 MIX CONTR: THETA

MEANING: NONMEM read-only global variables

CONTEXT: MIX, CONTR, CCONTR routine

USAGE:

USE ROCM_REAL, ONLY: `THETA`=>THETAC

GLOBAL DECLARATION:

USE SIZES, ONLY: LTH,DPSIZE
REAL(KIND=DPSIZE) :: THETAC(LTH)

DISCUSSION:

THETA: The current value of theta, made available by NONMEM for the MIX, CONTR and CCONTR routines. THETA is a reserved varible in $MIX abbreviated code.

Location prior to NONMEM 7: rocm0

REFERENCES: Guide VI, section III.L.2, Figure 6

50 MIX: DATA

MEANING: NONMEM read-only global variables

CONTEXT: MIX routine

USAGE:

USE ROCM_REAL, ONLY: DATA=>RDATA

GLOBAL DECLARATION:

USE SIZES, ONLY: NO,DPSIZE
REAL(KIND=DPSIZE) :: RDATA(NO,3)

DISCUSSION:

DATA(k,i): The value of the ith type of data item specified in NM-TRAN’s $CONTR record, appearing on the kth observation record of the individual record. It changes values with each individual record. DATA is a reserved variable in $MIX abbreviated code.

DATA is also used in CONTR (See CCONTR:_Y, Section 50.9, Section 53.11, Section 53.11, Section 53.11)

Location prior to NONMEM 7: rocm1

REFERENCES: Guide IV, section III.B.4

51 MIXNUM_MIXEST_MIXP

MEANING: Variables used with mixture models

CONTEXT: Abbreviated code and user-supplied subroutines

USAGE:

IF (MIXNUM == 1) THEN
 ...
ENDIF
IF (MIXNUM == 2) THEN
 ...
ENDIF
IF (MIXNUM == 3) THEN
 ...
ENDIF

DISCUSSION:

With mixture models, MIXNUM, MIXEST and MIXP are global variables that may be used as right-hand quantities (or in logical conditions) in abbreviated code or user-supplied routines.

In general:

MIXNUM is an input to PRED (or PREDPP) set by NONMEM.
MIXEST is an output (result) or consequence from the estimation set by NONMEM.

MIXNUM

This is the index of the subpopulation for which variables are to be computed.

During ICALL=4, MIXNUM is the index of the sub-population that was randomly selected to simulate the subject’s data. When ICALL=3 and the PASS subroutine used, or when ICALL=5 or 6, MIXNUM is the index of the subpopulation estimated to be that from which the individual’s data most probably arises, and is equal to MIXEST (See below).

MIXEST

When ICALL=3,5,6, and at ICALL=2 when COMACT is not 0, MIXEST is the index of the subpopulation estimated to be that from which the individual’s data most probably arises. Before nm7.3, at all other conditions, the value of MIXEST is not meaningful, such as when ICALL=4 or ICALL=2 and COMACT=0. As of NONMEM 7.3, when ICALL=4, MIXEST will equal MIXNUM, and when ICALL=2 and COMACT=0, MIXEST will be 0 to indicate it has not been assigned a meaningful value.

MIXP

These are the mixture probabilities P(i) computed by subroutine MIX or by the $MIX block of abbreviated code.

In abbreviated code, MIXP may be coded in either of three ways:

MIXP(MIXNUM)
MIXP
MIXP(i)

The first two ways are identical; i.e., when no subscript is coded, NM-TRAN supplies the subscript MIXNUM.

With the third, the index i must not exceed the value of MMX in SIZES (or as set by $SIZES record).

(See Mixture_model:_MIXNUM, Section 53.52) (See Section 53.53) (See Section 57.5, Section 60.38).

REFERENCES: Guide IV, section III.B.4, III.B.6

REFERENCES: Guide IV, section IV.E.1, 4.E.2

REFERENCES: Guide VI, section III.L.2, Figure 6

52 MIXTURE MODEL: MIXNUM, MIXEST

MEANING: NONMEM read-only global variables

CONTEXT: PRED routine

USAGE:

USE ROCM_INT, ONLY: MIXNUM=>MIXCALL,MIXEST=>IMIXEST

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: MIXCALL,IMIXEST

DISCUSSION:

MIXNUM: The number of the subpopulation for which PRED is to compute outputs.
MIXEST: The number of the subpopulation estimated to be that from which the individual’s data most probably arises. Should be used at ICALL = 3 and at ICALL = 2 when COMACT > 0.

Used with mixture models. MIXNUM and MIXEST are reserved variables in all blocks of abbreviated code.

This is a general description. For details, see mixnum. (See Section 53.51) (See Section 53.53, Section 57.5) (See Section 60.38)

Location prior to NONMEM 7: rocm11

REFERENCES: Guide VI, section III.L.2, Figure 6

53 MIXTURE MODEL: MIXP

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE ROCM_REAL, ONLY: MIXP

GLOBAL DECLARATION:

USE SIZES, ONLY: MMX,DPSIZE
REAL(KIND=DPSIZE) :: MIXP(MMX)

DISCUSSION:

Used with mixture models.

MIXP(i): The mixture probability for the ith subpopulation, computed by subroutine MIX.

May be used as right-hand quantities in all abbreviated codes other than $MIX. There the index i must be an integer constant.

This is a general description. For details, see mixnum. (See Section 53.51) (See mixnum_mixest_for_mixture_model) (See Section 57.5, Section 60.38)

Location prior to NONMEM 7: rocm25

REFERENCES: Guide VI, section III.L.2, Figure 6

54 MIXTURE MODEL: MIXPT

MEANING: NONMEM read-only global variables

CONTEXT: PRED routine

USAGE:

USE ROCM_REAL, ONLY: MIXPT=>MIXP_RAW

GLOBAL DECLARATION:

USE SIZES, ONLY: MMX,DPSIZE
REAL(KIND=DPSIZE) :: MIXP_RAW(MMX)

DISCUSSION:

MIXPT: At ICALL=6, (the final estimate of) the mixture probabilities associated with the individual record containing the template data record are stored in MIXPT.

Location prior to NONMEM 7: rocm47

REFERENCES: None.

55 MODEL

MEANING: MODEL subroutine

CONTEXT: User-supplied subroutine; for use with PREDPP

USAGE:

SUBROUTINE MODEL(IDNO,NCM,NPAR,IR,IATT,LINK)

USE PRMOD_CHAR, ONLY: NAME

USE SIZES,        ONLY: DPSIZE,ISIZE

INTEGER(KIND=ISIZE) :: IDNO,NCM,NPAR,IR,IATT,LINK

DIMENSION :: IATT(IR,*),LINK(IR,*)

GLOBAL DECLARATION:

Versions before NONMEM 7.4:

CHARACTER(LEN=8) :: NAME(PC)

Versions after NONMEM 7.4:

USE SIZES,        ONLY: SD

CHARACTER(LEN=SD) :: NAME(PC)

DISCUSSION:

The MODEL subroutine is called by PREDPP only once at the start of a run when a general ADVAN (ADVAN 5, 6, 7, 8, 9, 13, 14, 15, 16, 17, 18) is used. It allows the user to specify aspects of the particular model he wishes to use. When NM-TRAN is used, the $MODEL record supplies this information.

Input argument: None.

Output argument:

IDNO

An identification number for the MODEL routine. The value assigned by MODEL to IDNO is printed on the first PREDPP problem summary page.

NCM

The total number of compartments in the model, excluding the output compartment. Contains 0 when MODEL is called. NCM must be no greater than PC-1.

NPAR

The number of basic PK parameters used in the PK routine. Contains 0 when MODEL is called. NPAR must be no greater than constant PG in file SIZES. With the general non-linear models (ADVAN6, ADVAN8, ADVAN9, ADVAN13, ADVAN14, ADVAN15, ADVAN16, ADVAN17, ADVAN18), NPAR may remain 0.

IATT

Values of compartment attributes. The values of IATT(I,*) refers to the ith compartment.

IATT(I,1)=0 initially off
IATT(I,1)=1 initially on
IATT(I,2)=0 may not be turned on and off
IATT(I,2)=1 may be turned on and off
IATT(I,3)=0 may not receive doses
IATT(I,3)=1 may receive doses
IATT(I,4)=0 not the default observation compartment
IATT(I,4)=1 the default observation compartment
IATT(I,5)=0 not the default dose compartment
IATT(I,5)=1 the default dose compartment

The remainder is used only with ADVAN9, ADVAN15, and ADVAN17:

IATT(I,8)=0 not an equilibrium compartment
IATT(I,8)=1 an equilibrium compartment
IATT(I,9)=0 should not be included in the total drug amount in the system interior
IATT(I,9)=1 should be included in the total drug amount in the system interior

NAME

Labels for the compartments (to be printed on the PREDPP summary page under “FUNCTION”). NAME(I) is the label for compartment i. With versions before NONMEM 7.4, NAME was limited to 8 characters. With NONMEM 74 NAME may be up to SD characters long. SD is defined in SIZES and is set to 30 with NONMEM 7.4.

LINK

Only used with a general linear model (ADVAN5 and ADVAN7).

LINK(I, J)=0: no drug may distribute from compartment i to compartment j.
LINK(I, J)=K: drug distributes from compartment i to compartment j. The rate constant quantifying this first order distribution is computed by PK and stored in the kth row of GG.

When MODEL is called, all elements of LINK are 0.

(See Section 50.41).

An initial steady state may be requested by routine MODEL; (See Initial Steady State: I_SS, Section 53.45) (See i_ss, initial_condition).

REFERENCES: Guide IV, section V.C.4

REFERENCES: Guide VI, section VI.B, Figures 28, 29, 43

REFERENCES: Guide VI, Appendix II

56 MODEL EVENT TIME: MNOW, MPAST, MNEXT

MEANING: PREDPP read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE ROCM_INT, ONLY: MNOW=>MTNOW,MPAST=>MTPAST,MNEXT=>MTNEXT

GLOBAL DECLARATION:

USE SIZES, ONLY: PCT
INTEGER(KIND=ISIZE) :: MTNOW,MTPAST(PCT),MTNEXT(PCT)

DISCUSSION:

These variables are of interest when model event time parameters are defined in PK. (See mtime).

Location prior to NONMEM 7: procma

REFERENCES: None.

57 MODEL EVENT TIME: MTDIFF

MEANING: PREDPP-PK global variables

CONTEXT: PK routine

USAGE:

USE PRMOD_INT, ONLY: MTDIFF

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: MTDIFF

DISCUSSION:

MTDIFF is of interest when model time parameters MTIME are used.

The value of MTDIFF is 0 when PK is called. If PK sets MTDIFF to a value other than 0, e.g., MTDIFF=1, then PREDPP will understand that with that call to PK, the values of one or more of the MTIME(i) have possibly been reset.

It is not necessary to set MTDIFF at a call to PK with the first record of an individual or with a reset record. At such calls, it is assumed that all MTIME(i) are being set (if only to their default value of 0).

Suppose PK has defined a value MTIME(i). PREDPP calls PK prior to the advance to MTIME(i). PK may change MTIME(i) at this call. However, the new value of MTIME(i) is ignored till after the advance. Only then is the new value of MTIME(i) effective.

MTDIFF=0 (the default) can save considerable run time when there are many model time parameters. Note that the results are unpredictable if the times are in fact changed when MTDIFF=0.

(See mtime, Section 60.39).

Location prior to NONMEM 7: prdpk2

REFERENCES: None.

58 MODEL EVENT TIME: MTIME

MEANING: PREDPP-PK global variables

CONTEXT: PK routine

USAGE:

USE PKERR_REAL, ONLY :: MTIME

GLOBAL DECLARATION:

USE SIZES, ONLY: PCT,DPSIZE
REAL(KIND=DPSIZE) :: MTIME(PCT)

DISCUSSION:

Model time parameters MTIME are stored in MTIME if they are defined in $PK abbreviated code or if verbatim code is present in $PK. This makes them also available to the ERROR routine. However, their eta derivatives (if any) are not included. Hence the ERROR routine should not use model time parameters in such a way as to influence the value of Y if those parameters have eta derivatives.

A user-written PK routine need not define these variables unless perhaps the model time parameter values are used in the ERROR routine.

(See mtime, Section 60.39).

Location prior to NONMEM 7: prdpk1

REFERENCES: None.

59 MTIME MNEXT MPAST MNOW MTDIFF

MEANING: Variables related to the model event time feature of PREDPP.

CONTEXT: Abbreviated code, verbatim code, user-supplied routines, NM-TRAN

USAGE:

MTIME(1) = THETA(1)

DISCUSSION:

Model event times are additional PK parameters defined in the PK routine or $PK block. A model event time is not associated with any compartment, but, like an absorption lag time, defines a time to which the system is advanced. When the time is reached, indicator variables are set and a call to PK is made. At this call (and/or subsequent to this call) PK or DES or AES or ERROR can use the indicator variables to change some aspect of the system, e.g., a term in a differential equation, or the rate of an infusion. This feature may be used with any ADVAN routine. Model times are independent of non-event dose times.

The following are reserved variables when used in abbreviated code.

MTIME(i): The i-th model event time. The maximum number of model event times is given by constant PCT in file SIZES (See Section 50.41). MTIME(i) may be less than, equal to, or greater than MTIME(i+1). Any MTIME(i) may be negative or have the value 0 (in which case MPAST(i)=1 always and MNEXT(i)=0 always; see below). If PK defines MTIME(i) and MTIME(i+2) but not MTIME(i+1), then this has the same effect as defining MTIME(i+1)=0. PK may redefine MTIME(i). An ETA may be used in the definition of MTIME(i).
MTDIFF: The value of MTDIFF is 0 when PK is called. If PK sets MTDIFF to a value other than 0, e.g., MTDIFF=1, then PREDPP will understand that with that call to PK, the values of one or more of the MTIME(i) have possibly been reset. It is not necessary to set MTDIFF at a call to PK with the first record of an individual or with a reset record.

The following are the read-only indicator variables. They are not to be set by PK.

MNOW: MNOW=i if MNEXT(i)=1 for some i. MNOW=0 otherwise.
MNEXT(i): MNEXT(i)=1 during the advance from the previous time to MTIME(i). Otherwise, MNEXT(i)=0. The previous time may be an event time, a non-event time, or a model event time.
MPAST(i): MPAST(i)=0 until the call to PK subsequent to the one for which MNEXT(i)=1. At that call MPAST(i)=1. It then retains this value, unless MTIME(i) is redefined, in which case MPAST will be appropriately redefined as another step function.

(See Section 60.39)

(See Section 53.56, Section 53.56, Section 53.56)

(See Section 53.58)

(See Section 53.57)

(See Circadian Example: Examples Using MTIME to Model Periodic Discontinuities in $DES)

REFERENCES: Guide VI, section III.F.9

60 MU_MODEL

MEANING: MU modeling for EM methods

CONTEXT: Abbreviated code

USAGE:

MU_3 = LOG(THETA(3))
V = EXP(MU_3 + ETA(3))

DISCUSSION:

The new methods in NONMEM are most efficiently implemented if the user supplies information on how the THETA parameters are associated arithmetically with the etas and individual parameters, wherever such a relationship holds. Calling the individual parameters phi, the relationship should be

\[\phi_i = \mu_i(\theta) + \eta(i)\]

for each parameter i that has an eta associated with it, and mu_i is a function of THETA. The association of one or more THETA’s with ETA(1) must be identified by a variable called MU_1. Similarly, the association with ETA(2) is MU_2, that of ETA(5) is MU_5, etcetera. This is called “MU Referencing”, or “MU Modelling”.

Providing this information is as straight-forward as introducing the MU_ variables into the $PRED or $PK code by expansion of the code.

For a very simple example, the original code may have the lines

CL = THETA(4) + ETA(2)

This may be rephrased as:

MU_2 = THETA(4)
CL = MU_2 + ETA(2)

Another example would be:

CL = (THETA(1) * AGE**THETA(2)) * EXP(ETA(5))
V = THETA(3) * EXP(ETA(3))

which would now be broken down into two additional lines, inserting the definition of a MU as follows:

MU_5 = LOG(THETA(1)) + THETA(2) * LOG(AGE)
MU_3 = LOG(THETA(3))
CL = EXP(MU_5 + ETA(5))
V = EXP(MU_3 + ETA(3))

Note the arithmetic relationship identified by the last two lines, where MU_5+ETA(5) and MU_3+ETA(3) are expressed. This action does not change the model in any way.

If the model is formulated by the traditional typical value (TV, mean), followed by individual value, then it is straight-forward to add the MU_ references as follows:

TVCL = THETA(1) * AGE**THETA(2)
CL = TVCL * EXP(ETA(5))
TVV = THETA(3)
V = TVV * EXP(ETA(3)
MU_3 = LOG(TVV)
MU_5 = LOG(TVCL)

This also will work because only the MU_x= equations are required in order to take advantage of EM efficiency. It is not required to use the MU_ variables in the expression EXP(MU_5+ETA(5)), since the following are equivalent:

CL = TVCL * EXP(ETA(5)) = EXP(LOG(TVCL) + ETA(5) = EXP(MU_5 + ETA(5))

but it helps as an exercise to determine that the MU_ reference was properly transformed (in this case log transformed) so that it represents an arithmetic association with the eta.

An incorrect usage of MU modeling would be:

MU_1 = LOG(THETA(1))
MU_2 = LOG(THETA(2))
MU_3 = LOG(THETA(3))
CL = EXP(MU_1 + ETA(2))
V = EXP(MU_2 + MU_3 + ETA(1))

In the above example, MU_1 is used as an arithmetic mean to ETA(2), and a composite MU_2 and MU_3 are the arithmetic means to ETA(1), which would not be correct. The association of MU_x+ETA(x) must be strictly adhered to.

Once one or more thetas are modeled to a MU, the theta may not show up in any subsequent lines of code. That is, the only usage of that theta may be in its connection with MU. For example, if

CL = THETA(5) * EXP(ETA(2))

it can be rephrased as

MU_2 = LOG(THETA(5))
CL = EXP(MU_2 + ETA(2))

But later, suppose THETA(5) is used without its association with ETA(2):

...
CLZ = THETA(5) * 2

Then THETA(5) cannot be MU modeled, because it shows up as associated with ETA(2) in one context, but as a fixed effect without association with ETA(2) elsewhere.

However, if

MU_2 = LOG(THETA(5))
CL = EXP(MU_2 + ETA(2))
CLZ = CL * 2

Then this is legitimate, as the individual parameter CL retains the association of THETA(5) with ETA(2), when used to define CLZ. That is, THETA(5) and ETA(2) may not used separately in any other part of the model, except indirectly through CL, in which their association is retained.

Suppose you have:

CL = THETA(5) + THETA(5) * ETA(2)

One should see this as:

CL = THETA(5) * (1 + ETA(2))

So the way to MU model this is:

MU_2 = 1.0
CL = THETA(5) * (MU_2 + ETA(2))

Which would mean that in the end, THETA(5) is not actually MU modeled, since MU_2 does not depend on THETA(5). One would be tempted to model as follows:

MU_2 = THETA(5)
CL = MU_2 + MU_2 * ETA(2)

But this would be incorrect, as MU_2 and ETA(2) may not show up together in the code except as MU_2+ETA(2) or its equivalent. Thus, THETA(5) cannot be MU modeled. In such cases, remodel to the following similar format:

CL = THETA(5) * EXP(ETA(2))

So that THETA(5) may be MU modeled as:

MU_2 = LOG(THETA(5))
CL = EXP(MU_2 + ETA(2))

Sometimes, a particular parameter has a fixed effect with no random effect, such as:

Km = THETA(6)

with the intention that Km is unknown but constant across all subjects. In such cases, the THETA(6) and Km cannot be Mu referenced, and the EM efficiency will not be available in moving this Theta. However, one could assign an ETA to THETA(5), and then fix its OMEGA to a small value, such as 0.0225 =0.15^2 to represent 15% CV, if OMEGA represents proportional error. This often will allow the EM algorithms to efficiently move this parameter, while retaining the original intent that all subjects have similar, although not identical, Km’s. Very often, inter-subject variances to parameters were removed because the FOCE had difficulty estimating a large parametered problem, and so it was an artificial constraint to begin with. EM methods are much more robust, and are adept at handling large, full block OMEGA’s, so you may want to incorporate as many etas as possible when using the EM methods.

You should Mu reference as many of the THETA’s as possible, except those pertaining to residual variance (which should be modeled through SIGMA whenever possible). If you can afford to slightly change the theta/eta relationship a little to make it MU referenced without unduly influencing the model specification or the physiological meaning, then it should be done.

When the arithmetic mean of an ETA is associated with one or more THETA’s in this way, EM methods can more efficiently analyze the problem, by requiring in certain calculations only the evaluation of the MU’s to determine new estimates of THETAs for the next iteration, without having to re-evaluate the predicted value for each observation, which can be computationally expensive, particularly when differential equations are used in the model. For those THETA’s that do not have a relationship with any ETA’s, and therefore cannot be MU referenced (including THETA’s associated with ETAS whose OMEGA value is fixed to 0), computationally expensive gradient evaluations must be made to provide new estimates of them for the next iteration.

There is additional increased efficiency in the evaluation of the problem if the MU models are linear functions with respect to THETA. Recalling one of the previous examples above, we could re-parameterize THETA such that

MU_5 = THETA(1) + THETA(2) * LOG(AGE)
CL = EXP(MU_5 + ETA(5))
MU_3 = THETA(3)
V = EXP(MU_3 + ETA(3))

This changes the values of THETA(1) and THETA(3) such that the re-parameterized THETA(1) and THETA(3) are the logarithm of the original parameterization of THETA(1) and THETA(3). The models are identical, however, in that the same maximum likelihood value will be achieved. The only inconvenience is having to anti-log these THETA’s during post-processing.

The added efficiency obtained by maintaining linear relationships between the MU’s and THETA’s is greatest when using the SAEM method and the MCMC Bayesian method. In the Bayesian method, THETA’s that are linearly modeled with the MU variables have linear relationships with respect to the inter-subject variability, and this allows the Gibbs sampling method to be used, which is much more efficient than the Metropolis-Hastings (M-H) method. By default, NONMEM tests MU-THETA linearity by determining if the second derivative of MU with respect to THETA is nearly or equal to 0. Those THETA parameters with 0 valued second derivatives are Gibbs sampled, while all other THETAS are M-H sampled. In the Gibbs sampling method, THETA values are sampled from a multi-variate normal conditional density given the latest PHI=MU+ETA values for each subject, and the samples are always accepted. In M-H sampling, the sampling density used is only an approximation, so the sampled THETA values must be tested by evaluating the

Some additional rules for MU referencing are as follows:

As much as possible, define the MU’s in the first few lines of $PK or $PRED. Do not define MU_ values in $ERROR. Have all the MU’s particularly defined before any additional verbatim code, such as write statements. NMTRAN produces a MUMODEL2 subroutine based on the PRED or PK subroutine in FSUBS.F90, and this MUMODEL2 subroutine is frequently called with the ICALL=2 settings, more often than PRED or PK. The fewer code lines that MUMODEL2 has to go through to evaluate all the MU_s’ the more efficient.
Whenever possible, have the MU variables defined unconditionally, outside IF…THEN blocks.
Time dependent covariates cannot be part of the MU_ equation. For example
```
MU_3 = THETA(1) * TIME + THETA(2)
```
should not be done. Or, consider
```
MU_3 = THETA(2) / WT
```
Where WT varies with time. This would also not be suitable. However, we could phrase as
```
MU_3 = THETA(2)
CL = WT * (MU_3 + ETA(3))
```
is fine, where MU_3 represents a population mean clearance per unit weight, which is constant with time, and more universal among subjects, whereas CL is the non-wieght normalized clearance, than depends on a person’s weight, which could vary with time as well. The MU variables may vary with inter-occasion, but not with time.
Starting with NONMEM 7.2, NMTRAN’s CHECKMU subroutine attempts to look for errors in MU modeling. If it appears that there may be errors, then there are messages such as
```
(MU_WARNING 13) MU_001: DOES NOT HAVE ADDITIVE ASSOCIATION WITH ETA(001)
```
Such warnings do not affect the outputs from NMTRAN. FSUBS is generated as usual. Sometimes the warnings may be ignored (See “Model parameters as log t-Distributed”, below.) Sometimes warnings may not be generated when they should be. Thus, the user must pay close attention to following the rules.

Option NOCHECKMU of the $ABBR record may be used to prevent NM-TRAN from attempting to check the MU model statements.

Examples show examples of MU modeling for various problem types. Study these examples carefully. When transposing your own code, begin with simple problems and work your way to more complex problems.

At this point one may wonder why bother inserting MU references in your code. MU referencing only needs to be done if you are using one of the new EM or Gibbs sampling methods to improve their efficiency. The EM methods may be performed without MU references, but it will be several fold slower than the FOCE method, and the problem may not even optimize successfully. For simple two compartment models, the new EM methods are slower than FOCE even with the MU references. But, for 3 compartment models, or numerical integration problems, the improvement in speed by the EM methods, properly MU modeled, can be 5-10 fold faster than with FOCE.

Example 6 described at the end of the SIGL section is one example where importance sampling solves this problem in 30 minutes, with R matrix standard error, versus FOCE which takes 2-10 hours or longer, and without even requesting the $COV step. So, for complex PK/PD problems that take a very long time in FOCE, it is well worth putting in MU references and using one of the EM methods, even if you may need to rephrase some of the fixed/random (theta/eta) effects relationships. In addition, FOCE is a linearized optimization method, and is less accurate than the EM and Bayesian methods when data are sparse or when the posterior density for each individual is highly non-normal.

Model parameters as log t-Distributed in the Population

Sometimes one may suspect that PK/PD model parameters are actually log t-distributed among the population, with degrees of freedom NU, instead of the usual log normal distributed.

See INTRODUCTION TO NONMEM 7, MU Referencing

An example of simulation and analysis of such data is given as

..\examples\tdist6_sim.ctl
..\examples\tdist6.ctl:
..\examples\tdist7.ctl

Note that constructions such as

CL = EXP(MU_1 + ETA(1) * SQRT((EXP(CLR) - 1.0) / CLR))

violate the strict MU_x+ETA(x) rule recommended for EM analysis, because the term SQRT((EXP(CLR)-1.0)/CLR) is multiplied by ETA(1). NM-TRAN will generate a number of MU_WARNING messages. Nonetheless for this example, the importance sampling works quite well, and the MU_WARNING messages may be ignored.

REFERENCES: Guide Introduction_7

61 MXSTEP

MEANING: PREDPP-PK global variables

CONTEXT: User-supplied routines

USAGE:

USE PRDATA, ONLY: MXSTEP=>MXSTP0 (ADVAN9)
USE PRDATA, ONLY: MXSTEP=>MXSTP01 (ADVAN13,ADVAN14,ADVAN15,ADVAN16,ADVAN17,AD

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) MXSTP0
INTEGER(KIND=ISIZE) MXSTP01

DISCUSSION:

MXSTEP

The maximum number of integration steps for ADVAN9 and ADVAN13 and ADVAN14 and ADVAN15 and ADVAN16 and ADVAN17 and ADVAN18.

For ADVAN13, ADVAN14, ADVAN15, ADVAN16, ADVAN17, and ADVAN18, the default value of MXSTP01 is set to 10000 in resource\PRDATA.f90
For ADVAN9, the default value of MXSTP0 is set to the largest possible integer value 2147483647 in resource\PRDATA.f90, so MXSTEP can only be used to set a smaller value.

This variable is only a reserved variable for ADVAN9 and ADVAN13 and ADVAN14 and ADVAN15 and ADVAN16 and ADVAN17 and ADVAN18.

REFERENCES: Guide Introduction_7

62 NEW INDIVIDUAL INDICATOR: `NEWIND`

MEANING: PREDPP read-only global variables

CONTEXT: User-supplied PK and ERROR routines

USAGE:

USE PROCM_INT, ONLY: NEWIND=>PNEWIF

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: PNEWIF

DISCUSSION:

NEWIND: NEWIND is of interest only when ICALL=2, 4, 5, or 6. It is the same as the NEWIND argument passed by NONMEM to PREDPP (with the first data record of the current event record). Values are:

NEWIND=0: First event record of the data set.
NEWIND=1: First event record of the data set, THETA value does not differ from value at last call with this record, and PRED is nonrecursive (See Section 53.93), or, NEWIND=1: First event record of a subsequent individual record.
NEWIND=2: Subsequent event record of an individual record.

Location prior to NONMEM 7: procm1.

REFERENCES: Guide VI, section III.I

63 NINDR INDR1 INDR2

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE ROCM_INT, ONLY: NINDR=>NINDOBS,INDR1=>IDXOBSF,INDR2=>IDXOBSL

GLOBAL DECLARATION:

REAL(KIND=ISIZE):: NINDOBS,IDXOBSF,IDXOBSL

DISCUSSION:

NINDR: The number of individual records in the data set containing an observation record.
INDR1: The index of the first individual record in the data set containing an observation record.
INDR2: The index of the last individual record in the data set containing an observation record.

These variables may be used as right-hand quantities in $PRED, $PK, $ERROR, $INFN and $MIX abbreviated code.

Location prior to NONMEM 7: rocm46.

REFERENCES: None.

64 NON-ACTIVE ETA LIST FOR `PRED`

MEANING: NONMEM read-only global variables

CONTEXT: PRED routine

USAGE:

USE NMPRD_INT, ONLY NAETA,LVOUT

GLOBAL DECLARATION:

USE SIZES, ONLY: LVR
INTEGER(KIND=ISIZE) :: NAETA,LVOUT(LVR)

DISCUSSION:

NAETA: The number of positions in LVOUT that are set to 1.
LVOUT: When LVOUT(i)=1, NONMEM is ignoring partial derivatives with respect to eta(i) with the current call to PRED.

Location prior to NONMEM 7: rocm15.

REFERENCES: None.

65 NONMEM MODULES

MEANING: Global variables in NONMEM

CONTEXT: User-supplied routines

DISCUSSION:

FORTRAN modules are used to communicate values between various components of the NONMEM system. They supplement the subroutine arguments.

NONMEM-PRED modules

These modules contain values that are (for the most part) communicated from PRED to NONMEM. Prior to NONMEM 7 these values were COMMON blocks. Following is a list of the MODULE, the (old) COMMON, and a description of the variables.

NMPRD_INT (NMPRD1): PRED return code and user message count (IERPRD, NETEXT).
NMPRD_CHAR (NMPRD2): PRED user message (ETEXT).
NMPRD_INT (NMPRD3): “Copying pass” flag and SAVE region size for NMPRD4 (COMACT, COMSAV).
NMPRD4P (NMPRD4): PRED-defined items for tables and scatterplots.
NMPRD_REAL (NMPRD5): Correlation matrix for ε’s.
NMPRD_INT (NMPRD6): Return code from routine SIMEPS.
NMPRD_REAL (NMPRD7): Simulated etas for tables and scatterplots.
NMPRD_REAL (NMPRD8): PRED’s “recursive” flag.
NMPRD_REAL (NMPRD9): Data record at ICALL 0, 1 and 3.
NMPR_INT (NMPR10): Control information for PRED repetition feature.
NMPR_INT (NMPR11): Flags to override effect of NEW option on $SIMULATION record.
NMPR_REAL (NMPR12): Conditional limits on observation.
NMPR_REAL (NMPR13): Lower limits defining interval datum, and their derivatives.
NMPR_REAL (NMPR14): Upper limits defining interval datum, and their derivatives.
NMPR_INT (NMPR15): Skip control variable.
NMPR_REAL (NMPR16): Parameter values produced during Simulation Step.
NMPR_INT (NMPR17): Flag indicating character of PRED variable F.

NONMEM read-only modules

These modules contain read-only values that are communicated from NONMEM to PRED and other user-supplied routines.

ROCM_REAL (ROCM0): Current theta (THETA).
ROCM_REAL (ROCM1): DV, data items in current L1 record.
ROCM_INT (ROCM1C): Size of current L1 record (prior to NONMEN 7, this was combined with ROCM1).
ROCM_INT (ROCM2): Number of L2 records and length of L2 record.
ROCM_REAL (ROCM3): Predictions and derivatives with current L1 record.
ROCM_REAL (ROCM4): Selected data from an individual record.
ROCM_INT (ROCM4): Selected data from an individual record.
ROCM_REAL (ROCM5): Predictions and derivatives with current L2 record.
ROCM_REAL (ROCM6): Initial/final theta, omega, sigma.
ROCM_REAL (ROCM7): Standard errors of estimates of theta, omega, sigma.
ROCM_REAL (ROCM8): Final value of the objective function.
ROCM_INT (ROCM9): Return codes from Estimation and Covariance Steps.
ROCM_INT (ROCM10): Simulation: no. of replications (total and current).
ROCM_INT (ROCM11): Mixture: index of subpopulation (current and most probable).
ROCM_INT (ROCM12): Second and first derivative flags for PRED.
ROCM_INT (ROCM13): Simulation: Final pass flag for PRED and CONTR.
NMPRD_INT (ROCM14): Problem and subproblem counters.
NMPRD_INT (ROCM15): List of inactive etas.
ROCM_REAL (ROCM16): The number of significant digits in the vector of final estimates.
ROCM_INT (ROCM17): New level 2 record flag.
ROCM_REAL (ROCM18): Nonparametric estimates: height and heights of cumulative marginals.
ROCM_REAL (ROCM22): Current value of omega.
ROCM_REAL (ROCM25): Mixing probabilities.
ROCM_REAL (ROCM28): Superproblem printing indicator.
NMPRD_INT (ROCM29): Population vs. single-subject data flag.
ROCM_REAL (ROCM31): Template record at ICALL=6.
ROCM_INT (ROCM32): Number of the individual record and of the data record.
ROCM_INT (ROCM34): NEWIND at ICALL 0, 1 and 3.
ROCM_INT (ROCM35): Numbers of thetas, etas and epsilons in the problem.
ROCM_REAL (ROCM36): Individual’s posterior variance-covariance matrix. No help entry.
ROCM_INT (ROCM37): Indicator that Estimation Step is omitted and obj. func. is being evaluated for first time. No help entry.
ROCM_REAL (ROCM38): Conditional limits for observations in individual record. No help entry.
ROCM_REAL (ROCM39): Conditional limits for observation. No help entry.
ROCM_REAL (ROCM40): Lower Limits defining interval datum, and their derivatives in individual record. No help entry.
ROCM_REAL (ROCM41): Upper Limits defining interval datum, and their derivatives in individual record. No help entry.
ROCM_REAL (ROCM42): Lower Limits defining interval datum, and their derivatives. No help entry.
ROCM_REAL (ROCM43): Upper Limits defining interval datum, and their derivatives. No help entry.
ROCM_REAL (ROCM44): Probability that observation is within (outside) limits.
ROCM_REAL (ROCM45): Probability that category occurs.
ROCM_INT (ROCM46): Number of individual records with observations, and indices of first and last such record.
ROCM_REAL (ROCM47): Mixture probabilities with individual record containing template record.
ROCM_INT (ROCM48): Length of individual record.
ROCM_REAL (ROCM49): Prediction, residual, and weighted residual values for all methods, as well as normalized probability distribution error.
ROCM_INT (ROCM50): ID data item for the individual contributions to the objective function.
ROCM_REAL (ROCM50): Individual contributions to the objective function.

Except as noted, each has its own entry in the Help document. Some modules are not fully documented. The interested user may be able to obtain more information by studying the appropriate sections of NONMEM code and previous examples that may be available from advanced users.

(See Section 53.85).

REFERENCES: Guide IV, section IV.E; Guide VI, section III.E.4, III.I, Figures 5, 6

66 NONPARAMETRIC DENSITY: DEN_, CDEN_

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE ROCM_REAL, ONLY: DEN_=>DEN_NP(1),CDEN_=>DEN_NP(2:LVR+1)

GLOBAL DECLARATION:

USE SIZES, ONLY: LVR,DPSIZE
REAL(KIND=DPSIZE) :: DEN_NP(LVR+1)

DISCUSSION:

DEN_: The nonparametric density.
CDEN_(1): The marginal cumulative value for the first eta.
CDEN_(2): The marginal cumulative value for the second eta. etc.

Values are computed by NONMEM when the Nonparametric step is performed and marginal cumulatives are requested (with NM-TRAN: $NONPARAMETRIC MARGINALS).

Values are available during the pass with COMACT=2 and (if PASS is called) at ICALL=3.

These variables may be used as right-hand quantities in abbreviated code blocks $PK, $ERROR, $INFN and $PRED.

Location prior to NONMEM 7: rocm18.

REFERENCES: None.

67 NPD, NPDE, NPDE_MODE, DV_LOQ, CDF_L, DV_LAQ, CDF_LA

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

USAGE:

USE NMPRD_INT, ONLY: NPDE_MODE
USE NMPRD_REAL, ONLY: DV_LOQ

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: NPDE_MODE
REAL(KIND=DPSIZE) :: DV_LOQ

DISCUSSION:

NONMEM 7 can compute the following:

NPDE: Monte-Carlo generated normalized probability distribution error.
NPD: The correlated (or non-decorrelated) NPDE value.

These are calculated during the Table Step, when NPD or NPDE is listed in $TABLE or $SCATTER.

NONMEM sets NPDE_MODE=1 when it is computing them. Otherwise, NPDE_MODE=0.

EXAMPLE:

To incorporate LOQ (Limit of Quantification) data into NPDE assessments [4], use the following method (as an example). See INTRODUCTION TO NONMEM 7, Reference [4]. Here, TYPE and LOQ are user-defined in previous code, or data item.

$ERROR
SD = THETA(5)
IPRED = LOG(F)
DUM = (LOQ - IPRED) / SD
CUMD = PHI(DUM)
IF (TYPE == 1 .OR. NPDE_MODE == 1) THEN
 F_FLAG = 0
 Y = IPRED + SD * ERR(1)
ENDIF
IF (TYPE == 2 .AND. NPDE_MODE == 0) THEN
 F_FLAG = 1
 Y = CUMD
 MDVRES = 1
ENDIF
IF(TYPE == 2) DV_LOQ = LOQ
....
$TABLE NPD NPDE

By default, DV_LOQ is set to -1.0d-300 by the NONMEM routine that calls PREDPP/PRED. If the user’s ERROR/PRED sets DV_LOQ to some other value and NPDE_MODE=1, then the NPDE is being evaluated during that time, and this censored value is to be treated as if it is a non-censored datum with value of LOQ (DV_LOQ=LOQ), in accordance with [4], utilizing a standard F_FLAG=0 definition for Y. Note that during estimation of the objective function (when NPDE_MODE=0), NPDE is not being evaluated, and censored values should be treated using F_FLAG=1, and Y must be defined as the integral of the normal density from -inf to LOQ.

New in nm74, for use with NPD, the user may supply the cumulative distribution function using the reserved variable CDF_L.

New in nm743, you can specify an above quantifiable limit with the reserved parameter DV_LAQ as well. The CDF reserved variable associated with above quantitation level DV_LAQ is CDF_LA.

The DV_LOQ/CDF_L and DV_LAQ/CDF_LA reserved variables may be also used for evaluating NPD diagnostics for categorical data.

See INTRODUCTION TO NONMEM 7, MDVRES=0.

REFERENCES: Guide Introduction_7

68 OBJECTIVE FUNCTION VALUE

MEANING: NONMEM read-only global variables

CONTEXT: PRED routine

USAGE:

USE ROCM_REAL, ONLY: OBJECT

GLOBAL DECLARATION:

USE SIZES, ONLY: DPSIZE
REAL(KIND=DPSIZE) :: OBJECT

DISCUSSION:

OBJECT: The final value of the objective function.

This value should only be used at ICALL = 3 (finalization block).

May be used as a right-hand quantity in abbreviated code.

Location prior to NONMEM 7: rocm8.

REFERENCES: None.

69 OBJECTIVE FUNCTION VALUE INDIVIDUAL

MEANING: NONMEM read-only global variables

CONTEXT: PRED routine

USAGE:

USE ROCM_INT, ONLY: IIDX=>IDVALX
USE ROCM_REAL, ONLY: CNTID=>OFV_IND

GLOBAL DECLARATION:

USE SIZES, ONLY: MAXIDS,DPSIZE
INTEGER(KIND=ISIZE) :: IDVALX(MAXIDS)
REAL(KIND=DPSIZE) :: OFV_IND(MAXIDS)

DISCUSSION:

NOTE: With NONMEM 7, the additional output file root.phi contains the same information. (See additional_output_file).

These variables contain values of the ID data item and individual contributions to the objective function. The values are in data-set order.

IIDX: Values of the ID data item.
CNTID: Values of the individual contribution to the objective function for the corresponding values of IIDX.

E.g., IIDX(n) is the ID data item for the nth. individual record, and CNTID(n) is the contribution to the objective function for the nth. individual record.

These values should only be displayed at ICALL = 3 (finalization block).

With NONMEM VI 1.0, they can only be displayed using verbatim code.

With NONMEM VI 2.0 and later releases, they can be used on the right and displayed using abbreviated code in $PRED, $PK, $ERROR and $INFN blocks (See Individual objective function example). (See write).

They may also be displayed in a table, using

`$ABBR` COMRES = 2

and code such as the following in the $ERROR or $PK block:

IF (COMACT == 1) THEN
 COM(1) = IIDX(NIREC)
 COM(2) = CNTID(NIREC)
ENDIF

The following, for example, will produce a separate table for the values:

`$TABLE` IID = COM(1) CNT = COM(2) FILE = comvals NOAPPEND NOPRINT FIRSTONLY

NOTE: With earlier versions than NONMEM 7.3, verbatim code is needed:

" COM(1)=IIDX(NIREC)
" COM(2)=CNTID(NIREC)

Location prior to NONMEM 7: rocm50.

REFERENCES: None.

70 PARAMETER DIMENSIONS

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE NMPRD_INT, ONLY: NTHES_=>NWTHT,NETAS_=>NWETA, NEPSS_=>NWEPS

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: NWTHT,NWETA,NWEPS

DISCUSSION:

NTHES_: The dimension of theta. If the dimension is 0, NTHES_=1.
NETAS_: The dimension of omega. If the dimension is 0, NETAS_=1.
NEPSS_: The dimension of sigma. If the dimension is 0, NEPSS_=1.

Location prior to NONMEM 7: rocm35.

REFERENCES: None.

71 PARAMETER VALUES: INITIAL AND FINAL

MEANING: NONMEM read-only global variables

CONTEXT: PRED routine

USAGE:

USE ROCM_REAL, ONLY: THETAF,OMEGAF,`SIGMA`,THETAFR

GLOBAL DECLARATION:

USE SIZES, ONLY: LTH,LVR ,DPSIZE
REAL(KIND=DPSIZE) :: THETAF(LTH),OMEGAF(LVR,LVR), &
                                      SIGMAF(LVR,LVR),THETAFR(LTH)

DISCUSSION:

THETAF: THETAF(i) = zero, initial, or final value of theta(i), according to the current value of ICALL.
THETAFR: THETAFR(i) = zero, initial, or final value of reported thetar(i), according to the current value of ICALL. If record $THETAR is not used, THETAF and THETAFR are equal. If record $THETAR is used, then THETAF is the internal theta as used in $PK/$PRED, and THETAFR is the theta reported in the report file.
OMEGAF: OMEGAF(i,j) = zero, initial, or final value of omega(i,j), according to the current value of ICALL.
SIGMAF: SIGMAF(i,j) = zero, initial, or final value of sigmaf(i,j), according to the current value of ICALL.

At ICALL = 0, these are zero values.

At ICALL = 1, these are initial values.

If NONMEM will be computing the initial value of theta(i), at ICALL=1 the initial value THETAF(i) is set to some point between the lower and upper bounds.

If NONMEM will be computing the initial value of a diagonal block of OMEGA (SIGMA), at ICALL=1 the initial value of the block is set to the identity matrix.

At ICALL = 3, these are final values.

At ICALL = 2, the values of these variables should not be used unless the value of COMACT is 1 or 2, in which case these are final values. (See Section 53.13, Section 53.13)

Location prior to NONMEM 7: rocm6.

REFERENCES: None.

72 PARAMETERS OMEGA SIGMA: CURRENT

MEANING: NONMEM read-only global variables

CONTEXT: PRED routine

USAGE:

USE ROCM_REAL, ONLY: `OMEGA`=>VARNF

GLOBAL DECLARATION:

USE SIZES, ONLY: LVR,DPSIZE
REAL(KIND=DPSIZE) :: VARNF(LVR,LVR)

DISCUSSION:

OMEGA: The current value of OMEGA being used.

The current value of SIGMA is also located in this array as follows:

`SIGMA`(I,J)=`OMEGA`(NETAS_+I,NETAS_+J)

NETAS_ is described in Parameter dimensions. (See Section 53.70).

At run and problem initialization and at problem finalization use the variables OMEGAF and SIGMAF. (See Section 53.71).

Should not be used if an initial estimate is being computed.

When an initial estimate is being computed, the value is just that found at problem initialization (when ICALL=1).

EXAMPLE:

Compute individual weighted residuals using a slope-intercept residual error model:

`$ERROR`
Y = F + EPS(1) + F * EPS(2)
IF (COMACT >= 1) THEN
 STD = SQRT(`SIGMA`(1) + F**2 * `SIGMA`(2))
 IWRES = (DV - F) / STD
ENDIF

Location prior to NONMEM 7: rocm22.

REFERENCES: None.

73 PARTIAL DERIVATIVE INDICATORS

MEANING: NONMEM read-only global variables

CONTEXT: PRED routine

USAGE:

USE NMPRD_INT, ONLY: MFIRST=>IFRSTDER,MSEC=>ISECDER,IFIRSTEM

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: IFRSTDER,ISECDER,IFIRSTEM

DISCUSSION:

MSEC: MSEC=1 when NONMEM is expecting second-partial eta-derivatives with the current call to PRED.

MSEC=0 when NONMEM is ignoring second-partial eta-derivatives with the current call to PRED.

Second-partial eta-derivatives are never expected unless the Laplacian method is used.

MFIRST: MFIRST=1 when NONMEM is expecting first-partial eta-derivatives with the current call to PRED.

MFIRST=0 when NONMEM is ignoring first-partial eta-derivatives with the current call to PRED. This variable is used only by PREDPP, not by generated FSUBS.

Location of MFIRST and MSEC prior to NONMEM 7: rocm12.

IFIRSTEM: With NONMEM 7.2 and higher, first-partial eta-derivatives are computed by generated code in FSUBS for classical NONMEM methods, but not for IMP, SAEM, and BAYES methods. This improves the speed at which the problem is evaluated. However, on occasion such derivatives are needed, for example, when steady state values are to be calculated, or when stochastic differential equations are to be evaluated. In such cases, insert as the first line in each block of abbreviated code ($PK, $ERROR, $DES, $AES, $PRED) the following line of code:

FIRSTEM=1

First derivatives will be evaluated for the new methods as well.

Note that FIRSTEM is a local variable. In FSUBS, FIRSTEM is copied from IFIRSTEM in MODULE NMPRD_INT prior to being used:

FIRSTEM = IFIRSTEM
...
IF (FIRSTEM == 1) THEN
 block of first derivative code
ENDIF

The statement FIRSTEM=1 is inserted in generated code prior to the first test of FIRSTEM. Thus, the local variable FIRSTEM is changed by the user, not the global variable IFIRSTEM.

In order to implement this feature, NM-TRAN rearranges the order of statements in FSUBS. Statements that compute first-partial eta-derivatives are collected together into blocks of first derivative code to be executed only with FIRSTEM is 1. Option NOFASTDER of the $ABBREVIATED record prevents NM-TRAN from doing this and restores the order of statements in FSUBS to what it was in previous versions. (See Section 50.1)

REFERENCES: Guide VI, section III.E.4, IV.B.2

74 PASS NEW L2 RECORD: NEWL2

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE NMPRD_INT, ONLY: NEWL2

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: NEWL2

DISCUSSION:

NEWL2: NEWL2 = 1 if the data record is the first of an L2 record.

NEWL2 = 2 otherwise.

If there is no L2 data item, each data record is a different L2 record.

NEWL2 also changes value in conjunction with calls to PASS.

NEWL2 may be used as a right-hand quantity in $PRED and $ERROR blocks, and in an $INFN block in conjunction with PASS.

Location prior to NONMEM 7: rocm17.

REFERENCES: None.

75 PASS `NEWIND`: NWIND

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE NMPRD_INT, ONLY: NWIND

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: NWIND

DISCUSSION:

NWIND: The NEWIND value at ICALL 0, 1 and 3. NWIND changes value in conjunction with calls to PASS. (See Section 53.79, newind).

Location prior to NONMEM 7: rocm34.

REFERENCES: Guide I, section C.3.5.2

76 PASS: PASSRC

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

USAGE:

USE NMPRD_REAL, ONLY: PASSRC

GLOBAL DECLARATION:

USE SIZES, ONLY: VSIZE,DPSIZE
REAL(KIND=DPSIZE) :: PASSRC(VSIZE)

DISCUSSION:

PASSRC: PASSRC contains the data record at ICALL values 0, 1 and 3. PASSRC changes in conjunction with calls to PASS, at which time transgeneration is permitted.

Location prior to NONMEM 7: nmprd9.

REFERENCES: None.

77 PK

MEANING: PK subroutine

CONTEXT: User-supplied subroutine; for use with PREDPP

USAGE:

Versions before NONMEM 7.2:

SUBROUTINE PK(`ICALL`,IDEF,`THETA`,IREV,EVTREC,NVNT,`INDXS`,IRGG,GG,NETAS)
USE SIZES,     ONLY: DPSIZE,ISIZE,LVR
REAL(KIND=DPSIZE) :: EVTREC
INTEGER(KIND=ISIZE) :: `ICALL`,IDEF,IREV,NVNT,`INDXS`,IRGG,NETAS
DIMENSION :: IDEF(7,*),`THETA`(*),EVTREC(IREV,*),`INDXS`(*)
DIMENSION :: GG(IRGG,LVR+1,*)

With NONMEM 7.2 and higher:

SUBROUTINE PK(`ICALL`,IDEF,`THETA`,IREV,EVTREC,NVNT,`INDXS`,IRGG,GG,NETAS)
USE SIZES,     ONLY: DPSIZE,ISIZE
USE PRDIMS,    ONLY: GPKD
IMPLICIT REAL(KIND=DPSIZE) (A-Z)
REAL(KIND=DPSIZE) :: EVTREC
INTEGER(KIND=ISIZE) :: `ICALL`,IDEF,IREV,NVNT,`INDXS`,IRGG,NETAS
DIMENSION :: IDEF(7,*),`THETA`(*),EVTREC(IREV,*),`INDXS`(*)
DIMENSION :: GG(IRGG,GPKD+1,*)

DISCUSSION:

The PK subroutine is called by PREDPP to obtain values for basic and additional pharmacokinetic parameters. Basic PK parameters are typically the rate constants (“microconstants”) 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.

Input argument:

ICALL: ICALL=1: PK has been called for initialization at the beginning of a NONMEM problem; one such call per problem. EVTREC contains the first event record. THETA contains the initial estimates. PK must return values in IDEF, which inform PREDPP what tasks it will perform at later calls. It may also set GG (k,1,1) to 1, indicating that the kth PK parameter will be modeled as a log (a feature which cannot be specified using abbreviated code).

ICALL=2: PK has been called to obtain parameter values; multiple calls occur. PK should call GETETA to obtain ETA values for the individual. PK should compute all relevant portions of GG.

ICALL=4: PK has been called during the Simulation Step; multiple calls occur. PK should call SIMETA to obtain simulated ETA values for the individual. PK should compute individual-specific parameters for column 1 of GG.

ICALL=5: PK has been called during the computation of expectations; multiple calls occur. Such calls occur when the marginal (MRG_) data item is defined in the data set and has non-zero values for some records. If the MRG_ data item has the value 1 or 2, the values of PK-defined items contribute to the expectations computed for these items.

ICALL=6: PK has been called during the computation of raw data averages; Such calls occur when the raw-data data item (RAW_) is defined in the data set and has non-zero values for some records.

THETA: The NONMEM THETA vector.
EVTREC: The PREDPP event record.
INDXS: The values specified in the $INDEX record of the NM-TRAN control stream. (This is the NONMEM Index array starting at position 12, the first position beyond those positions used by PREDPP itself).
NETAS: The number of population etas in the problem.

Output argument:

IDEF: PK should store values in IDEF only when ICALL=1. Values may be stored in the following elements:

IDEF(1,1)=-9 (required)
IDEF(1,2) is the call limiting element (compare $PK’s CALLFL). Values are:
- -2: call with every event record and at additional and lagged dose times.
- -1: call with every event record (default)
- 0: call with first event record and new TIME values
- 1: call once per individual record

Compartment initialization may be performed by routine PK; (See Compartment Initialization: A_0) (See sCompartment Initialization: A_0FLG).

An initial steady state may be requested by routine PK; (See Initial Steady State: I_SS, Section 53.45) (See i_ss, initial_condition).

The value in IDEF(1,3) describes whether PK performs compartment initialization, i.e., whether or not PK initializes elements of the initial state vector A_0(n). Values are:

-1: PK may initialize A_0.
0: PK does not initialize A_0.
1: PK does initialize A_0.

The default used by PREDPP is IDEF(1,3)=-1. However, when compartment initialization is not implemented, then if IDEF(1,3) is set to 0, PREDPP can avoid some time-consuming processing. Indeed, when $PK abbreviated or verbatim code is supplied, and there is no reference to compartment initialization amounts A_0(n) in either the abbreviated or verbatim code, then NM-TRAN sets IDEF(1,3)=0.

Compartment amounts may be used by routine PK; (See Section 53.106).

The value in IDEF(1,4) describes whether PK uses derivatives of compartment amounts (e.g. compartment amounts themselves are used as random variables in arithmetic statements in PK). Values are:

-1: PK may use derivatives of compartment amounts.
0: PK does not use derivatives of compartment amounts.
1: PK uses derivatives of compartment amounts.

The default used by PREDPP is IDEF(1,4)=-1. However, when derivatives of compartment amounts are not used, then if IDEF(1,4) is set to 0, PREDPP can avoid some time-consuming processing. Indeed, when $PK abbreviated or verbatim code is supplied, and there is no reference to A(n) (as a random variable in an arithmetic statement) in the abbreviated code (or to derivatives of A(n) in the verbatim code), then NM-TRAN sets IDEF(1,4)=0.

Remaining elements contain row numbers in GG:

IDEF(2,1): row number of F0 (output fraction)
IDEF(2,2): row number of XSCALE (Time Scale)
IDEF(2,3): row number of lowest-numbered MTIME
IDEF(2,4): row number of highest-numbered MTIME
IDEF(3,n): row number of Sn (Scale for comp. n) (thru n+1 output)
IDEF(4,n): row number of Fn (bioavailability fraction for comp. n)
IDEF(5,n): row number of Rn (modeled rate for comp. n)
IDEF(6,n): row number of Dn (modeled duration for comp. n)
IDEF(7,n): row number of ALAGn (absorption lag for comp. n)

GG: The array of PK parameters and their eta derivatives. The maximum number of rows in GG is given by IRGG, which is the same as constant PG found in file SIZES. (See Section 50.41).

At ICALL = 2:

GG(k,1,1) contains the value of the kth parameter.
GG(k,i+1,1) contains its derivative with respect to the ith eta.
GG(k,i+1,j+1) contains its second derivative with respect to the ith eta and the jth eta (lower-triangular; j=1, …, i). (Second derivatives are only needed with estimation by the Laplacian method.)

At ICALL = 4:

GG(k,1,1) contains the individual-specific value of the kth parameter. Other columns of GG need not be computed.

Also see variables in NONMEM modules, NONMEM-PRED modules, and PREDPP modules. (See Section 53.111)

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

78 POPULATION SINGLE-SUBJECT INDICATOR

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE NMPRD_INT, ONLY: IPS

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: IPS

DISCUSSION:

IPS: IPS = 1 when the data are population data.

IPS = 2 when the data are single-subject data.

Location prior to NONMEM 7: rocm29.

REFERENCES: Guide I, section B.1; Guide IV, section II.C.4

79 PRED

MEANING: PRED subroutine

CONTEXT: User-supplied routine; required with NONMEM

USAGE:

Versions before NONMEM 7.2:

SUBROUTINE `PRED` (`ICALL`,`NEWIND`,`THETA`,`DATREC`,`INDXS`,F,G,H)
USE SIZES,       ONLY: DPSIZE,ISIZE,LVR
REAL(KIND=DPSIZE) :: `DATREC`
INTEGER(KIND=ISIZE) :: `ICALL`,`NEWIND`,`INDXS`
DIMENSION :: `THETA`(*),`DATREC`(*),`INDXS`(*),G(LVR,*),H(LVR,*)

With NONMEM 7.2 and higher:

SUBROUTINE `PRED` (`ICALL`,`NEWIND`,`THETA`,`DATREC`,`INDXS`,F,G,H)
USE SIZES, ONLY: DPSIZE,ISIZE
USE PRDIMS,ONLY: GPRD,HPRD,GERD,HERD,GPKD
IMPLICIT REAL(KIND=DPSIZE) (A-Z)
REAL(KIND=DPSIZE) :: `DATREC`
INTEGER(KIND=ISIZE) :: `ICALL`,`NEWIND`,`INDXS`
REAL(KIND=DPSIZE) :: G(GPRD,*),H(HPRD,*)
DIMENSION :: `THETA`(*),`DATREC`(*),`INDXS`(*)

DISCUSSION:

The PRED subroutine is called by NONMEM to obtain modeled values. (PREDPP is a PRED subroutine that is distributed with NONMEM.)

Input argument:

ICALL: ICALL=-1: the routine has been called for the PRED_IGNORE_DATA feature of NONMEM 7.5. One call per data record, at the start of the run. These calls occur only if abbreviated code uses variables PRED_IGNORE_DATA or PRED_IGNORE_DATA_TEST, or if the PRED_IGNORE_DATA option of $DATA is used. Otherwise, there are no calls to PRED with ICALL=-1.

ICALL=0: PRED has been called for initialization purposes at the beginning of the NONMEM run; one such call per run. DATREC contains the first data record. THETA contains the initial estimates. PRED need not compute F, G, or H.

ICALL=1: PRED has been called for initialization purposes at the beginning of a NONMEM problem; one such call per problem. Otherwise, identical to ICALL=0.

ICALL=2: For the data record contained in DATREC, PRED has been called for the purpose of computing F, the value of the prediction, and/or the values of other PRED-defined items, appropriate for the record. PRED should compute F, and also G and H as appropriate. THETA contains the values to be used to compute F. With conditional estimation, to obtain ETA values, PRED should call GETETA.

ICALL=3: PRED has been called for finalization purposes at the end of a NONMEM problem; one such call per (sub)problem. DATREC contains the first data record. THETA contains the final estimates. Otherwise, identical to ICALL=0.

ICALL=4: For the data record contained in DATREC, PRED has been called during the Simulation Step for the purpose of computing a value of the dependent variable and, possibly, values of independent variables, appropriate for the record. PRED should compute F (the value of the dependent variable). THETA contains the initial estimates, which are the values to be used to compute F. PRED should call SIMETA (and SIMEPS) to obtain simulated values of ETA (and EPS).

ICALL=5: For the data record contained in DATREC, PRED has been called for the purpose of computing the expectation of the PRED item and possibly, the expectations of other PRED-defined items, appropriate for the record. Such a call occurs when the marginal data item (MRG_) is defined in the data set and has a non-zero value for the data record in question. If the MRG_ data item on the record has the value 1 or 2, the value returned by PRED in F contributes to the expectation of the PRED item. Similarly, the values returned in other PRED-defined items contribute to expectations of these items. THETA contains the final estimates. The expectations in question are over possible values of ETA, and to obtain ETA values, PRED should call GETETA.

ICALL=6: PRED has been called for the purpose of computing the raw data average of the DV data items and, possibly, the raw data averages of PRED-defined items. Such a call occurs when the raw-data data item (RAW_) is defined in the data set and has a non-zero value for a template data record (See template). The value of the DV data item in the data record contained in DATREC will be included in the raw data average of the DV data items. However, when the raw data average corresponding to the label DV in a table or scatterplot is to be different from the raw data average of the DV items themselves, PRED may recompute the value of DV. PRED may return a value of 1 in F to omit the DV item in the data record from the average.

NEWIND

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.

THETA: The NONMEM THETA vector.
DATREC: The current data record.
INDXS: The values specified in the $INDEX record of the NM-TRAN control stream.

Output argument:

F: When ICALL=2, the prediction associated with the data record. With odd-type data, the likelihood of the observation in the record, but if there is no observation, F is ignored.

When ICALL=4, the value of the simulated observation associated with the data record. Alternatively, F can be ignored, and the DV item in the data record can be directly set to the value of the simulated observation. With odd-type data, F is ignored; PRED should directly set the DV item to the value of the simulated observation.

G: An array of derivatives of F with respect to etas. Values should be set when ICALL=2.

G(i,1) is the partial derivative of F with respect to eta(i).

When the data are population, G(i,j+1) is the second partial derivative of F with respect to eta(i), eta(j) (lower-triangular; j=1,…, i).

Second derivatives are needed only when the Laplacian method is used to estimate parameters.

H: An array of partial derivatives of F with respect to epsilons. When the data are population, values should be set when ICALL=2.

H(i,1) is the derivative of F with respect to eps(i).

H(i,j+1) is the partial derivative of H(i,1) with respect to eta(j).

These mixed second derivatives are needed only when the INTERACTION option is used to estimate parameters. (See Section 50.15).

Also see variables in NONMEM modules, NONMEM-PRED modules, and PREDPP modules. (See Section 53.111)

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

80 PRED ERROR MESSAGE

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

USAGE:

USE NMPRD_CHAR, ONLY :: ETEXT

GLOBAL DECLARATION:

CHARACTER(LEN=132) :: ETEXT(3)

DISCUSSION:

ETEXT: The user message which appears as part of the PRED error message. When PRED returns to NONMEM with IERPRD>0, PRED may store here one to three lines of text explaining the error, for printing. The number of lines of text to be printed must be stored in NETEXT. (See Section 53.81)

When abbreviated code is used, the EXIT statement causes appropriate text to be stored in ETEXT.

Location prior to NONMEM 7: nmprd2.

REFERENCES: Guide VI, section III.K.2, IV.F; Guide IV, section IV.G

81 PRED EXIT CODE

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

With versions of NONMEM before 7.4.2:

USAGE:

USE NMPRD_INT, ONLY: IERPRD,NETEXT

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: IERPRD,NETEXT

With versions of NONMEM starting with 7.4.2:

USAGE:

USE NMPRD_INT, ONLY: IERPRD,IERPRDU,NETEXT

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: IERPRD,IERPRDU,NETEXT

DISCUSSION:

Values are stored by PRED for use with NONMEM.

IERPRD: The PRED error return code; also called the PRED exit code. Is set to 0 before PRED is called.

IERPRD=0: Normal return
IERPRD=1: PRED is unable to compute. If possible, NONMEM should attempt recovery.
IERPRD=2: PRED is unable to compute. NONMEM should abort the run.

NETEXT: NETEXT=0 to 3: the number of lines of text of an error message stored by PRED in ETEXT. (See nmprd2). (See Section 53.80).

Values may be stored in IERPRD two ways.

PREDPP may store error messages such as PK PARAMETER FOR KA IS NON-POSITIVE in ETEXT and set IERPRD=1 and K=1. (In effect, EXIT 1 1).

In abbreviated code, whether or not PREDPP is used, the statement EXIT n k causes n to be stored in IERPRD. The value of k is part of the error message in ETEXT, which is reported in the NONMEM output report and in file PRDERR.

With NONMEM 7.4.2, there is a new variable, IERPRDU. Both n and k are stored in IERPRDU. k must be between 0 and 999. The value stored is n*10000+k. E.g., EXIT 1 500 is stored in IERPRDU as 10500.

With NONMEM 7.5 and later, values of k between 1000 and 9999 are permitted. E.g., EXIT 1 2000 is stored in IERPRDU as 12000.

PREDPP will not set these values; only the EXIT statement in abbreviated code can do this. IERPRDU is ignored if it is not the Simulation Step. For NONMEM 7.5 use of the error code during simulation, (See Section 53.96) and look for “Simulation Error Forgiveness”.

Location prior to NONMEM 7: nmprd1.

REFERENCES: Guide V, section 12.4.15; Guide VI, section III.K.2, IV.F; Guide IV, section IV.G; Guide Introduction_7

82 PRED_IGNORE_DATA BLOCK (NM75)

MEANING: Abbreviated code for ignoring (dropping) data records

CONTEXT: $PRED, $PK, $INFN abbreviated code

SAMPLE:

`$INFN`

IF(PRED_IGNORE_DATA_TEST==1) THEN
 PRED_IGNORE_DATA = 0
 IF(AGE>35.0) PRED_IGNORE_DATA = 1
 IF(ID>10 .AND. ID<18 .OR. ID>60 .AND. ID<70) PRED_IGNORE_DATA = 1
 RETURN ;Assures no additional computation code in `INFN` is executed
ENDIF

USAGE:

SUBROUTINE `INFN` (`ICALL`,`THETA`,`DATREC`,`INDXS`,`NEWIND`)
USE NMPRD_INT, ONLY: PRED_IGNORE_DATA,PRED_IGNORE_DATA_TEST

DISCUSSION:

The IGNORE=(list) and ACCEPT=(list) options of $DATA provide a limited means of filtering the input data set, which is performed by NMTRAN. To provide more elaborate filtering for excluding data, PRED can request that NONMEM filter out additional data records at the beginning of the run.

This is done by setting the reserved variable PRED_IGNORE_DATA to a non-zero value within $INFN, $PK, or $PRED, for each record to be ignored.

It may be useful to package PRED_IGNORE_DATA statements within

IF(PRED_IGNORE_DATA_TEST==1) THEN
 ...
 RETURN
ENDIF

structures to avoid unnecessary code execution.

If the PRED_IGNORE_DATA_TEST or PRED_IGNORE_DATA variables appear in abbreviated code, or the option

`$DATA` ... PRED_IGNORE_DATA

is used in the NM-TRAN control stream, then a PRED_IGNORE_DATA pass through the NONMEM data file with PRED_IGNORE_DATA_TEST=1 and ICALL=-1 occurs. Otherwise it does not. Therefore, existing code such as IF (ICALL<=1) THEN ...ENDIF does not need to be changed.

The following variables have properly defined values:

`ICALL`
Data record items in `DATREC`
`NEWIND`,NEWL2
NPROB,`IPROB`, S1NUM, S2NUM,
S1NIT,S2NIT, S1IT, S2IT

No other variables are properly defined when PRED_IGNORE_DATA_TEST=1. For example, the following should not be used:

`THETA`, `OMEGA`, `SIGMA`, NREP, `IREP`

ETA may be used but will be 0 there are no random variables in a pred_ignore_data block.

Typically the NONMEM file that is input to the pred_ignore_data block is FDATA. FDATA is unaffected by the pred_ignore_data block. However, with NONMEM 7.5 there is a new file, FDATA.csv, and records excluded by PRED_IGNORE_DATA will not be present in FDATA.csv.

In a pred_ignore_data block, the data record has been read by NONMEM and all data record items have numeric values. The (non-Fortran) operators .EQN. and .NEN. that can be used with the $DATA IGNORE and ACCEPT options are not needed and cannot be used in a pred_ignore_data block.

Any other functions of $INFN, such as DATA item modification (i.e., transgeneration of the data), RANDOM calls, etc. should be made with ICALL==1 or ICALL==0 IF blocks, as before.

It is possible to restrict PRED_IGNORE_DATA actions to a particular problem number:

IF(`IPROB`==2 .AND. PRED_IGNORE_DATA_TEST==1) THEN
 PRED_IGNORE_DATA = 0
 IF(AGE>35.0) PRED_IGNORE_DATA = 1
 IF(ID>10 .AND. ID<18 .OR. ID>60 .AND. ID<70) PRED_IGNORE_DATA = 1
 RETURN
ENDIF

RETURN statements may be used.

EXIT statements may be used. They act like a RETURN but are otherwise ignored.

REFERENCES: Guide Introduction_7

83 PRED_RES_WRES

MEANING: PRED, RES, WRES

CONTEXT: NONMEM output

DISCUSSION:

NONMEM tables usually include special items: prediction, residual, and weighted residual, which are generated by NONMEM. The default labels for these items are PRED, RES, and WRES, respectively. Synonyms may be specified on the $TABLE record for one or more of these labels. With the NOAPPEND option on this record, the three items are not included in a table unless explicitly listed on the $TABLE record. With the use of the user-routine SPTWO, the values of the RES and WRES items can be defined differently from the values described below. (See Section 57.7).

These items may also be displayed in scatterplots. Synonyms may be specified on the $SCATTERPLOT record as well; synonyms specified on either the $TABLE or $SCATTERPLOT record also apply to the other record.

PRED: Prediction items are the predictions computed by the PRED subroutine. For population data, prediction items are always population predictions, i.e., they are computed at the mean value of eta (0).
RES: The residual is defined as DV - PRED; that is, the observed value minus the prediction item.
WRES: The weighted residuals for an individual are formed by transforming the individual’s residuals so that under the model, assuming the true values of the parameters are given by the estimates of those parameters, all weighted residuals have mean 0, unit variance and are uncorrelated. For population data, the “weights” are computed at eta = 0.

For odd-type data, the prediction items are likelihoods (for population data, using the estimated values of the parameters, and computed at eta = 0). These may not be of much interest. The RES and WRES items are 0.

With a mixture model, each individual is classified into one of the subpopulations of the mixture according to a computation based on the individual’s data and on the final parameter estimates. For a data record from the individual record, the prediction, residual, and weighted residual items in the corresponding row of a table (or point on a scatterplot) are based on the submodel defining the subpopulation into which the individual is classified.

If the Marginal data item (MRG_) is 1 or 2 for a given data record, then PRED is an expected prediction, rather than the prediction at the mean value of eta. When the Raw-data data item (RAW_) is 1, then DV is a raw-data average and RES is the difference between the PRED item and this average. (See Section 55.3).

REFERENCES: Guide I, section C.3.5.3, C.3.5.4; Guide IV, section III.B.16, III.B.17; Guide V, section 9.5, 10.7, 11.4.4.2

84 `PRED`-DEFINED VARIABLES

MEANING: NONMEM-PRED global variables

CONTEXT: User-supplied routines

USAGE:

USE NMPRD4, ONLY: COM=>VRBL

GLOBAL DECLARATION:

MODULE NMPRD4
USE SIZES, ONLY: DPSIZE
IMPLICIT NONE
SAVE

 REAL(KIND=DPSIZE), ALLOCATABLE, TARGET :: VRBL(:)
END MODULE

DISCUSSION:

NMPRD4 is a module for PRED-defined variables (including PK-defined and ERROR-defined variables). It contains an array VRBL. (COM is suggested above as an alternate to the name VRBL to be consistent with generated code, but this is optional.) The VRBL array is allocated dynamically by NONMEM. The default size is given by constant LNP4 in resource/sizes.f90, but this can be changed using the $SIZES record.

Variables are stored in NMPRD4 for communication with other blocks of abbreviated code or with user-written codes, or so that NONMEM has access to these variables for display in tables or scatterplots. (See Section 50.46, $scatter). Values are stored by PRED and by subroutines of PREDPP. A SAVE region of NMPRD4 may be designated; (See Section 53.13, Section 53.13).

When abbreviated code is used, by default NM-TRAN lists all PRED-defined variables in the module, as well as certain NM-TRAN-defined variables which give the values of partial derivatives. Comment lines in the generated code (file FSUBS) identify these variables. This makes the listed variables globally accessible to all blocks of abbreviated code, which may not be desirable. (An exception is made for initialization-finalization variables; these are PRED-defined variables that are first defined within a block that tests for ICALL 0, 1, 3. Such variables are stored locally and will not be changed by NONMEM at ICALL 2 or 4.) (See Section 53.44)

Variables from a given block of abbreviated code can be excluded from the module by including the following pseudo-statement in that block:

COMRES=-1

Variables from all blocks of abbreviated code can be excluded from the module by including the identical option (COMRES=-1) on the $ABBREVIATED record.

Variables from NMPRD4 can be used in a user-written subroutine. If the user-written subroutine contains the USE NMPRD4 statement as shown above, the variables have the names COM(1), COM(2), etc. E.g., X=COM(1)/COM(1). It is possible to give the variables the same (non-subscripted) names that they had in $PRED, $PK or $ERROR. Suppose variables CL and V are used in $PK, and the following is present in the generated PK routine:

CL=>COM(00001); V=>COM(00002)

In the user-written subroutine, after the last declaration, include:

POINTER :: CL,V

Prior to the first executable statement, include:

CL=>COM(1); V=>COM(2)

Now the code is X=CL/V.

Code generated by NM-TRAN is somewhat more complex, but achieves the same result.

REFERENCES: Guide III, section V.3.3; Guide IV, section III.B.7, III.B.16, III.B.17, IV.H, V.C.5-9; Guide VI, section III.J, III.L.2, IV.E, IV.G.4 Figures 5, 14

85 PREDPP MODULES

MEANING: Global variables in PREDPP

CONTEXT: User-supplied routines

DISCUSSION:

These modules contain values that are (for the most part) communicated from PRED to its subroutines. Prior to NONMEM 7 these values were COMMON blocks. Following is a list of the MODULE, the (old) COMMON, and a description of the variables. (See Section 53.65).

PREDPP read-only modules contain values that are communicated from PREDPP to various user-subroutines PK, ERROR, DES and AES.

PROCM_INT (PROCM1): NEWIND, for PK and ERROR.
PROCM_REAL (PROCM2): Non-event dose time and derivatives, for PK.
PROCM_REAL (PROCM3): Initiating dose record (at non-event dose time), for PK.
PROCM_REAL (PROCM4): Compartment amounts and derivatives, for PK and ERROR.
PROCM_INT (PROCM5): Number and map of active etas, for PK and ERROR (and TRANS).
PROCM_REAL (PROCM6): Theta vector from NONMEM, for DES and AES.
PROCM_REAL (PROCM7): EVTREC from NONMEM, for DES and AES.
PROCM_CHAR (PROCM8): Format statements, for all routines.
PROCM_REAL (PROCM9): Time at which the state-vector (in PROCM4) was last computed, for PK.
PROCM_INT (PROCMA): Indicator variables associated with model event times, for all routines.
PROCM_INT (PROCMB): Flag indicating final call to DES or AES after advance to event or non-event time, for DES and AES.
PROCM_INT (PROCMC): Flag indicating compartment initialization call to PK, for PK.

The following are special modules containing values that are communicated from user routines to PREDPP.

PRCOM_INT (PRCOMG): Override default settings in ADVAN6, ADVAN8, ADVAN9, ADVAN13, and SS6.
PRCOM_LOG (PRCOMU): Restore pre-1990 behavior of bio-availability fraction.
PRCM2_REAL (PRCOMW): Fudge factor for error tests in ADVAN7/SS7.

These modules contain values that are communicated from subroutines to PREDPP.

PKERR_REAL (PRDPK1): Communicate model event time parameters computed by PK to the ERROR routine.
PRMOD_INT (PRDPK2): Flag indicating possible change in model event time parameters.
PRMOD_REAL (PRDPK3): Compartment initialization values from PK.
PRMOD_INT (PRDPK4): Values of ISSMOD and I_SS (“Initial Steady-State”) flags.
PROCM_INT (PRDDE1): Initialization values that are communicated from subroutine DES and AES to PREDPP.
PRINFN (PRINFN): Contains values of INFN-defined variables which are communicated to other PREDPP user-routines.

Each has its own entry in the Help document.

REFERENCES: Guide VI, section III.I, IV.D, Figure 14

86 PRIOR SIMULATION: ICMAX

MEANING: NONMEM-PRED global variables

CONTEXT: PRIOR routine

USAGE:

USE NMPR_INT, ONLY: ICMAX=>IMAXSIM

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: IMAXSIM

DISCUSSION:

This variable allows the user to control the behavior of the NWPRI and TNPRI NONMEM utility routines. It is relevant during simulation when PRIOR sets ISS to a non-zero value. By default, NWPRI and TNPRI attempt at most 100 times to obtain a sample. After that number of attempts, they terminate with the message

MAXIMUM ATTEMPTS TO OBTAIN SAMPLE EXCEEDED

ICMAX: If a value is set in ICMAX, this overrides the default of 100. E.g., in a PRIOR subroutine:

USE NMPR_INT, ONLY: ICMAX=>IMAXSIM
   ... other code ...
ICMAX=500

Location prior to NONMEM 7: nmpr50.

REFERENCES: None.

87 PRIOR SIMULATION: PARAMETERS

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

USAGE:

USE NMPR_REAL, ONLY: THSIMP=>THET_P,OMSIMP=>OMEG_P,SGSIMP=>SIGM_P,THSIMPR

GLOBAL DECLARATION:

USE SIZES, ONLY: LTH,LVR,DPSIZE
REAL(KIND=DPSIZE) :: THET_P(LTH),OMEG_P(LVR,LVR),SIGM_P(LVR,LVR)

DISCUSSION:

Values of THETA, OMEGA and SIGMA that are produced during a Simulation Step using the user-supplied routine PRIOR must be stored in these variables. If one of the NONMEM utility routines NWPRI or TNPRI is used by PRIOR to produce THETA, OMEGA, and SIGMA values, these values will automatically be stored in THET_P, OMEG_P, SIGM_P. If $THETAR record is not used, THSIMPR contains the same values as THSIMP (THET_P). If $THETAR record, THSIMP contains the internal theta values, and THSIMPR contains the reported values (THSIMP values transformed by equations of the $THETAR record). The entire THETA, OMEGA and SIGMA arrays are stored by NPWRI and TNPRI, not just the the inital sub-vectors (prior-affected parts). (See Section 59.12, Section 59.21).

These variables may be used as right-hand quantities in $PK, $ERROR, $INFN and $PRED blocks. After being set during the Simulation Step, they remain available during problem finalization (i.e., ICALL=3).

Location prior to NONMEM 7: nmpr16.

REFERENCES: None.

88 PROBABILITY DENSITY FUNCTIONS

MEANING: Functions that may be used in abbreviated code.

CONTEXT: Fortran coded function

A series of built in probability density functions are available with NONMEM 7.4.2. For a given probability density there is also a cumulative distribution function (densitycdf), and random number generating function (density_rng).

They are described in INTRODUCTION TO NONMEM 7.4.2 Section I.26.

The density and densityCDF functions have arguments that are compatible with the FUNC system, in which function provides derivatives (XD), and second derivatives (XDD) (See I.65. Expanded Syntax and Capacity for User-Defined Functions (FUNCA) (NM74)). Thus, even random (eta associated) variables may serve as arguments to the parameters of the density functions. The source code of these densities are in ..\source\DISTRIB.f90, DISTRIBCDF.f90, and DISTRIBRNG.f90. Note that multi-variate densities do not have a corresponding CDF routine.

Examples of their use are in the ..\examples\densities directory.

Here are the list of densities, which are modeled after the format from the Stan manual:

BERNOULLI
BERNOULLILOGIT
BINOMIAL
BINOMIALLOGIT
BETABINOMIAL
HYPERGEOMETRIC
CATEGORICAL
CATEGORICALLOGIT
ORDEREDLOGISTIC
NEGBINOMIAL
NEGBINOMIAL2
NEGBINOMIAL2LOG
POISSON
POISSONLOG
MULTINOMIAL
NORMAL
EXPMODNORMAL
SKEWNORMAL
STUDENTT
DOUBLEEXPONENTIAL
LOGISTIC
GUMBEL
LOGNORMAL
CHISQUARE
INVCHISQUARE
SCALEDINVCHISQUARE
EXPONENTIAL
GAMMA
INVGAMMA
WEIBULL
FRECHET
RAYLEIGH
PARETO
PARETO2
BETA
DIRICHLET
VON MISES

REFERENCES: none

89 PROBLEM ITERATION COUNTERS

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE NMPRD_INT, ONLY: NPROB,IPROB,S1NUM=>IDXSUP(1),S2NUM=>IDXSUP(2), &
                                      S1NIT=>NITR_SUP(1),S2NIT=>NITR_SUP(2), &
                                      S1IT=>NITSUP(1),S2IT=>NITSUP(2)

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: NPROB,IPROB,IDXSUP(2),NITR_SUP(2),NITSUP(2)

DISCUSSION:

NPROB: The number of problems in the run.
IPROB: The number of the current problem.

IPROB is 1 unless there are multiple problems (e.g., multiple $PROBLEM records in the NM-TRAN control stream).

S1NUM: The number of the active first-level superproblem. S1NUM is 0 if there is no active first-level superproblem.
S2NUM: The number of the active second-level superproblem. S2NUM is 0 if there is no active second-level superproblem.
S1NIT: The number of iterations for the active first-level superproblem. S1NIT is 0 if there is no active first-level superproblem.
S2NIT: The number of iterations for the active second-level superproblem. S2NIT is 0 if there is no active second-level superproblem.
S1IT: The number of the current iteration of the active first-level superproblem. S1IT is 0 if there is no active first-level superproblem.
S2IT: The number of the current iteration of the active second-level superproblem. S2IT is 0 if there is no active second-level superproblem.

These variables may be used as right-hand quantities in abbreviated code for initialization/finalization blocks. (See Section 50.44).

Location prior to NONMEM 7: rocm14.

REFERENCES: None.

90 PROTECT FUNCTIONS

MEANING: PROTECT functions

CONTEXT: Source code

USAGE:

X=..
XLOG10=PLOG10(X)

DISCUSSION:

As of 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. In addition, there are first derivative (such as PLOGD1), and second derivative (such as PLOGD2) companion routines available which NMTRAN uses for computing analytical derivatives. The source code of these routines are available in ..\source\PROTECT.f90. If you wish to modify their behavior, then copy PROTECT.f90 to your run directory as (say) myprotect.f90, modify it, then refer to this modified code with $SUBROUTINES OTHER=myprotect.f90 (The OTHER option is not needed if the P functions are coded explicitly or implicitly via $ABBR PROTECT.)

The following protective code routines are available:

For all routines, if X=not a number, X is converted to machine precision value, which is about 1.0E-15, before performing an operation on it. If X>INFNTY (where INFNTY is approximately 1.0E+154), then X is converted to INFNTY before an operation is performed on it.

PLOG(x): returns LOG of x. If x<SMALLZ, where SMALLZ is approximately 2.8E-103, then LOG(SMALLZ) is returned.
PLOG10(x): returns LOG10 of x. If x<SMALLZ, where SMALLZ is approximately 2.8E-103, then LOG10(SMALLZ) is returned.
PSQRT(x): returns SQRT of x. If x=0.0d+00, then 0 is returned.
PEXP(x): returns EXP of x. If x>40.0, then PEXP(100.0) is returned (avoids overflow).
PDZ(x): returns 1/x. Protects against divide by zero. If abs(x)<SMALLZ, then 1/SMALLZ is returned.
PZR(x): returns x. Protects against zero. If abs(x)<SMALLZ, then SMALLZ is returned.
PNP(x): returns x. Protects against non-positive. If X<SMALLZ, then SMALLZ is returned.
PHE(x): returns x. Protects against high exponent. If X>100, then 100 is returned. Thus PEXP(x)=EXP(PHE(x)).
PNG(x): returns x. Protects against negative. If X<0.0, then 0.0 is returned.
PTAN(x): returns tan(x). Protects against returning infinity on inputs near pi/2.
PATAN(x): returns atan(x). Protects against large inputs.
PACOS(x), PASIN(x): returns acos(x), asin(x), respectively. If |X| is between 1.0 and 1+10**(-08), then x is submitted as 1 or -1. So, “dirty ones” are cleaned up, but values clearly beyond 1 are allowed to trip up the function, so the user is aware of the logical error in the code, and fix the issue.

Instead of replacing various operations with protected code operations by hand, you can ask NMTRAN to automatically convert your code to protected code with the following statement:

`$ABBR` PROTECT

NMTRAN will automatically replace all LOG (or DLOG) with PLOG, EXP (or DEXP) with PEXP, SQRT (or DSQRT) with PSQRT, / operations with *PDZ(), and B**E operations with PEXP(E*PLOG(B)), and so on.

Note that the any P function name that is used explicitly or implicitly via $ABBR PROTECT may not be used for a user-defined variable name.

When you use $ABBR PROTECT, you will find a considerable improvement in estimation stability, regardless of estimation method used.

REFERENCES: Guide Introduction_7

91 RANDOM MODELS

MEANING: Models for random variables

CONTEXT: Abbreviated code

DISCUSSION:

The following are examples of commonly used models using random variables. Models for CL in terms of TVCL (“typical value of clearance”) and ETA are examples of models expressing population inter-individual variability. Models for Y involving F (“prediction based on the pharmacokinetic parameters”) and ERR are examples of models for intra-individual (“residual”) variability. They are used with both population or single-subject data, in which case ERR stands for EPS or ETA, respectively.

Additive models

CL = TVCL + ETA(1)
Y = F + ERR(1)

Proportional (CCV; Constant Coefficient of Variation) models

CL = TVCL * (1 + ETA(1))
Y = F * (1 + ERR(1))

An equivalent way of coding the proportional model is:

CL = TVCL + TVCL * ETA(1)
Y = F + F * ERR(1)

Exponential models

CL = TVCL * EXP(ETA(1))
Y = F * EXP(ERR(1))

During estimation by the first-order method, the exponential model and proportional models give identical results, i.e., NONMEM cannot distinguish between them. During estimation by a conditional estimation method, the exponential and proportional models for inter-individual variability give different results. During simulation, the two models give different results, in both the inter- and intra-individual cases.

Power Function model

Y = F + F**P * ERR(1)

The Power Function model has both the additive and the CCV error models as special cases, and smoothly interpolates between them in other cases.

Combined Additive and Proportional model (slope-intercept model)

Y = F * (1 + ERR(1)) + ERR(2)

Here is an alternative parameterization for the same model when there is no covariance between ERR(1) and ERR(2). Any theta may be used.

W = (1 + `THETA`(5) * `THETA`(5) * F * F)**.5
Y = F + W * ERR(1)

REFERENCES: Guide V, section 3, 4.1, 7.5, 8.3 REFERENCES: Guide V, section 8 REFERENCES: Guide VII, section I, III

92 RECORD COUNTERS: NIREC, NDREC

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE ROCM_INT, ONLY: NIREC=>NINDREC,NDREC=>NDATINDR

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: NINDREC,NDATINDR

DISCUSSION:

NIREC: The number of the individual record at the current call.
NDREC: The number of the data record within the individual record at the current call.

NIREC and NDREC also change value in conjunction with calls to PASS, a NONMEM utility routine. NIREC and NDREC may be used as right-hand quantities in $PRED, $PK, and $ERROR blocks, and in a $INFN block in conjunction with PASS. NM-TRAN automatically provides the necessary USE statement in the generated subroutines. See also additional_record_counters for other variables of interest such as FIRSTREC. Location prior to NONMEM 7: rocm32

REFERENCES: None.

93 RECURSIVE `PRED` INDICATOR

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

USAGE:

USE NMPRD_INT, ONLY: I_REC=>IRECRSIV

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: IRECRSIV

DISCUSSION:

A PRED routine may be recursive, i.e., for single-subject data, with a given data record, the PRED computation depends on the values of variables that PRED computes with any of the previous records. PREDPP is such a routine. By default, PRED is taken to be nonrecursive. At ICALL=0 or 1, PRED can declare itself to be recursive, by including the variable I_REC and setting it to 1. The setting of I_REC can be changed from problem to problem, but regardless of the setting, with a given problem the setting is always taken to be 0 if the data for that problem are population data. If I_REC is set to 1 and the repetition feature is not used, the SPECIAL option need not appear on the $COVARIANCE record; the special computation is automatically used. PREDPP sets I_REC to 1 at ICALL=1. I_REC can be set explicitly in abbreviated code. With recursive $PRED abbreviated code and with single-subject data, if I_REC is not set to a value in $PRED, then NM-TRAN causes I_REC to be set to 1. Location prior to NONMEM 7: nmprd8

REFERENCES: None.

94 REPETITION VARIABLES

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

USAGE:

USE NMPR_INT, ONLY: RPTI=>NRPT_IN,RPTO=>NRPT_OUT, &
                                    RPTON=>NRPT_ON,PRDFL=>IUSEPRD

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: NRPT_IN,NRPT_OUT,NRPT_ON,IUSEPRD

DISCUSSION:

These variables provide the information controlling the Repetition feature of NONMEM.

RPTO: RPTO is the “repetition output value”. With each data record, it may be set by PRED, and it conveys information to NONMEM. RPTO may be used as a left-hand quantity in $PRED, $PK and $ERROR blocks.

RPTO=0 If RPTO is set to 0, this produces no effect.

RPTO=n (where n is between 1 and 5) The current record is thus marked as a “repetition base with value n”, i.e. as the first of a series of contiguous records of the current individual record (with single-subject data, contiguous records of the data set) which will be repeated. See the repeat data item (See RPT_).

RPTO=-n (where n is between 1 and 5) The current record thus becomes a “repetition initiator with value n”, i.e. before the next record is passed to PRED all preceding records of the individual record (with single-subject data, all records of the data set), starting with the last such record marked as a repetition base with value n, and up to and including the current record, will be once again passed to PRED (will be “repeated”). The value n is put onto the top of a stack - the “repetition stack”.

The series of records from base to initiator is called the “repetition series for n”. The series may be repeated any number of times (See RPTON). After all repetitions are complete, the value n is removed from the repetition stack.

While the series is being repeated, RPTO may be set again with any record R of the series. If the (unsigned) repetition output value is a value already on the repetition stack, this value is ignored. Otherwise, the output value is not ignored, and it may be set so as to mark R as a repetition base or as a repetition initiator. In the latter case the current value on the top of the stack (m) is pushed down to the next lower position, the value n is put onto the top of the stack, and a new repetition series is initiated. After the new series has been fully repeated, the value n is removed from the stack, the value m is again put onto the top of the stack, and repetition of the series for m is continued with the record following R.

RPTO=-1 This value is a special value that may be used as the repetition output value with a given record. If a previous record has been marked as a repetition base with value 1, then the record in question becomes a repetition initiator with value 1 in the usual way. But if no previous record has been marked as a repetition base, then it is assumed that the first record of the individual record (with single-subject data, the first record of the data set) is a repetition base with value 1. That is, before the next record is passed to PRED all preceding records of the individual record (with single-subject data, all records of the data set), starting with the first such record and up to and including the current record, will be once again passed to PRED (will be “repeated”). The value 1 is put onto the top of the repetition stack.

In addition, for the repetition feature to work, it must be enabled at the outset. This will be done if the repeat data item appears in the data set, or if RPTO is set to a nonzero value at ICALL=0 or ICALL=1.

RPTON: With each data record, RPTON may be set by PRED, and it conveys information to NONMEM. When the repetition output value is nonnegative, RPTON is ignored. Otherwise, RPTON may be set to an integer that gives the number of times the repetition series initiated by the data record is to be repeated. With the value 0, the series is repeated once. RPTON may be used as a left-hand quantity in $PRED, $PK and $ERROR blocks.
RPTI: RPTI is the “repetition input value”. With each data record, it is set by NONMEM, and it conveys information to PRED. RPTI may be used as a right-hand quantity in $PRED, $PK, $ERROR, $DES, and $AES blocks.

RPTI=0 The record being passed is not “being repeated”.

RPTI!=0 The record being passed to PRED is “being repeated”. The nonzero value is the length of the repetition stack (See above).

By default, with each pass through an individual record (with single-subject data, with each pass through the data set), and with any data record that is being passed for the first time and is other than a repetition initiator, the output from PRED is used by NONMEM. If the record is a repetition initiator, NONMEM uses the output from PRED only when the repetition output value n has appeared on the repetition stack for the first time (as a result of RPTO being set to -n with this record) and when the record is being passed for the last time before the output value is subsequently removed from the stack. Otherwise, NONMEM ignores all output from PRED, except for the values set for these variables.

For example, in the case where a record is a repetition initiator, as is a subsequent record, where both records set RPTO to -1, and where both records set RPTON to 0, the first record is passed (at least) four times, and NONMEM uses the output from the first record when it is passed for the second time.

PRDFL: PRDFL is the “PRED output control flag”. With each data record, it may be set by PRED, and it conveys information to NONMEM. PRDFL may be used as a left-hand quantity in $PRED, $PK and $ERROR blocks.

The PRED output control flag is used with very advanced applications with the repetition feature. With it, some of the default behaviour for when NONMEM pays attention to PRED output (See above) - may be overridden.

PRDFL!=1 This signals that the output from PRED with a passed record (except for the values of the repetition variables) is to be ignored by NONMEM.

PRDFL=1 This signals that the output from PRED with a passed record is to be used by NONMEM.

With the PRED output control flag, PRED specifies when it is that NONMEM is to use PRED’s output. However, just as with the default behavior, where during a pass through the data, NONMEM uses the output from a given data record once and once only, with each data record, PRDFL must be set to 1 once and once only, either when the record is passed initially or when it is repeated. Moreover, as with the default behavior, PRDFL can be set to 1 with a given record only after PRDFL has been set to 1 with the previous data record of the individual record (for single-subject data, with the previous data record of the data set).

In addition, for the PRED output control flag to work, it must be enabled at the outset, i.e., PRDFL must be set to 1 at ICALL=0 or ICALL=1. It may be enabled only when the repetition feature has also been enabled.

Location prior to NONMEM 7: nmpr10

(See repeti1, repeti2)

Help file repeti1 discusses the following files in the examples directory:

repeat1.ctl
repeat1s.ctl
repeat1t.ctl
repeatf.ctl

REFERENCES: None.

95 SIGNIFICANT DIGITS FROM EST. STEP

MEANING: NONMEM read-only global variables

CONTEXT: PRED routine

USAGE:

USE ROCM_REAL, ONLY `NSIG`=>SIGD,SIG=>DIFA

GLOBAL DECLARATION:

USE SIZES, ONLY: LPAR,DPSIZE
REAL(KIND=DPSIZE) :: SIGD,DIFA(LPAR)

DISCUSSION:

SIG(i): When the minimization in the Estimation Step terminates due to rounding errors, but the number of significant digits that is achieved is reported, the ith value in SIG gives the number of significant digits for the ith UCP element.
NSIG: NSIG gives the minimum of the values found in the vector SIG

The NSIG and SIG values should only be used with ICALL = 3. Location prior to NONMEM 7: rocm16

REFERENCES: None.

96 SIMULATION BLOCK

MEANING: Abbreviated code for simulation

CONTEXT: Abbreviated code

SAMPLE:

`$PK`

IF (`ICALL` == 4) CL = `THETA`(1) + ETA(1)

DISCUSSION:

A “simulation block” is a block of abbreviated code that is only executed when ICALL=4 (during simulation). Such blocks may be present in $PK, $ERROR, and $PRED, and may be implemented by means of generated FORTRAN subroutines. E.g.,

IF (`ICALL` == 4) THEN
 ... simulation block ...

ENDIF

Special rules apply to such blocks.

No eta derivatives are computed in a simulation block.
Transgeneration is permitted. NM-TRAN allows a data item label to appear on the left of an assignment statement. NM-TRAN generates assignment statements changing first the data item in the event or data record, and then the local variable having that label. E.g., suppose WT is listed in $INPUT:

IF (`ICALL` == 4) WT = 70 + 70 * ETA(3)

The generated code is:

IF(`ICALL` == 4.D0)THEN
 EVTREC(NVNT,8) = 70.D0+70.D0 * ETA(03)
 WT = EVTREC(NVNT,08)
ENDIF

NONMEM and PREDPP reserved data items should not be modified during simulation. Transgeneration is permitted with simulation with subproblems. 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.

Calls to certain NONMEM routines are permitted:

CALL SIMETA(ETA)
CALL SIMEPS(EPS)
CALL RANDOM(n,R)

where n is an integer 1-10. If CALL RANDOM is present, R becomes a reserved variable used for the random number.

Note that NM-TRAN provides the necessary calls to SIMETA and SIMEPS in generated routines. Explicit calls are used in abbreviated code only to obtain different values of ETA and EPS.

A RETURN statement may be used. If in $ERROR or $PRED, and the RETURN occurs in a simulation block, then Y may be assigned a value prior to the return. If so, then F is set (F=Y); otherwise F is not set.
Loops are permitted. The syntax is as follows.

DO WHILE (condition)
 .. statements ..

END DO

Here are some examples. For a truncated normal distribution that only requires testing the eta value directly, this code can be used:

`$PK`

...
DO WHILE (ETA(1) > 5)
 CALL SIMETA(ETA)
ENDDO

Another example:

IF (`ICALL` == 4 .AND. `NEWIND` /= 2) THEN

 DO WHILE (ETA(1) > .5 .OR. ETA(1) < -.5)
 CALL SIMETA(ETA)

 ENDDO
ENDIF
IF (`ICALL` == 4) WT = 70 + 70 * ETA(1)

(With these two examples, the first random seed of the $SIMULATION record must have the NEW option. Note also that, because of the previous automatic call to SIMETA, ETA(1) requires no initialization, but that R in the next example does.)

IF (`ICALL` == 4 .AND. `NEWIND` /= 2) THEN
 R = 1
 DO WHILE (R > .5 .OR. R < -.5)
 CALL RANDOM(2,R)
 ENDDO

ENDIF
IF (`ICALL` == 4) WT = 70 + 70 * R

This example illustrates how a categorical variable with equal-likely probabilities can be generated from a random number R, uniformly distributed between 0 and 1. In this example, the categorical variable BIN takes values 1 through 5.

IF (`ICALL` == 4) THEN
 CALL RANDOM(2,R)
 BIN = INT(R * 5) + 1

ENDIF

The number 5 can be replaced with any other positive integer n to obtain an n-valued categorical variable. Here INT is the function that transforms a nonnegative number x into the greatest integer not exceeding x. The effect of this simulation code is to perform the transformation:

BIN=1 if R < .2
BIN=2 if R < .4 and R >= .2
BIN=3 if R < .6 and R >= .4
BIN=4 if R < .8 and R >= .6
BIN=5 if R < 1 and R >= .8

The “EXIT n k” statement may be used. The value of n may be 0, 1 or 2. The value of k is referred to as the PRED EXIT CODE. If it is desired that the simulation be immediately terminated, then use an EXIT 2 code:

IF(`ICALL`==4.and.IPRED<0.1 .and. TIME>20.0) EXIT 2

With versions of NONMEM prior to 7.2, the “EXIT 1” statement in the Simulation step also caused NONMEM to abort. As of NONMEM 7.2, if an error occurs in PREDPP during simulation such as

PK PARAMETER FOR KA IS NON-POSITIVE

or a user-implemented EXIT 1 is issued during simulation, then PRED will be called with a new ETA and EPS. This feature is referred to as Simulation Error Forgiveness. NONMEM describes this as PRED SIMULATION REDO in the NONMEM report file. It writes to the NONMEM report file a description of the data record and THETA and ETA values, for example

`PRED` SIMULATION REDO `PRED` EXIT CODE = 1 INDIVIDUAL NO.                                   1

ID= 1.00000000000000E+00 (WITHIN-INDIVIDUAL) DATA REC NO. 1

`THETA`=

3.00E+00 8.00E-02 4.00E-02

ETA=

4.66E-01 2.91E-03 9.95E-01

MESSAGE ISSUED FROM SIMULATION STEP

If ten such errors occur in the same subject, then it is supposed that the cause of the simulation error is not due to an occasional bad random sample, but is caused by a systematic error in the control stream file. The simulation step is terminated with the message

`PRED` ERROR OCCURRED TOO OFTEN ON SIMULATION

instead of a message

SIMULATION STEP PERFORMED

With NONMEM 7.5, the PRED EXIT CODE k may be in the range 1000-9999. For example,

IF(`ICALL`==4.and.IPRED<0.01 .and. TIME>20.0) EXIT 1 2300

This can only occur with user’s EXIT code; PREDPP will not generate this kind of EXIT. NONMEM will try PRED SIMULATION REDO up to 10000 times. The message “PRED SIMULATION REDO” itself is written to PRDERR up to 30 times. After that, the following message is written to PRDERR:

 SUBSEQUENT `PRED` SIMULATION REDO ERROR MESSSAGES SUPPRESSED

NONMEM continues trying new ETA and EPS. Be careful that the condition does not occur too often (causing wasteful computation). After 10000 tries, the simulation is terminated as a protection against an infinite loop. The following message is written to PRDERR:

 TOO MANY CONSECUTIVE `PRED` ERRORS (>10000) OCCURRED ON SIMULATION

(See Section 53.81). (See Section 50.1). (See INTRODUCTION TO NONMEM 7, Simulation Error Forgiveness (NM72)). (See INTRODUCTION TO NONMEM 7, Extensions to Simulation Error Forgiveness (NM75)).

REFERENCES: Guide IV, section III.B.13, IV.I REFERENCES: Guide V, section 12.4.8 REFERENCES: Guide VI, section III.E.2, IV.B.2

97 SIMULATION: ETA, EPS

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

USAGE:

USE NMPRD_REAL, ONLY: ETA,EPS

GLOBAL DECLARATION:

USE SIZES, ONLY: LVR,DPSIZE
REAL(KIND=DPSIZE) :: ETA(LVR),EPS(LVR)

DISCUSSION:

When the ONLYSIMULATION option on the $SIMULATION record is used, the displayed eta values are those that PRED stores in ETA during the Simulation Step (i.e., at ICALL=4).

In generated subroutines, eta values are automatically stored in ETA, and thus automatically, the simulated etas are displayable.

When using the PRED repetition feature, epsilon values generated in PRED for simulation purposes (with or without the use of the ONLYSIMULATION option) should be stored in EPS. Then when records are repeated, these same epsilons values will be available in EPS as input. In particular, with every repeated record, the values that were stored in EPS the last time the record was passed, are made available as input to PRED.

In generated subroutines, epsilon values are automatically stored in EPS, and thus automatically, the simulated epsilons are available as input with repeated records.

When using the repetition feature with single-subject data, eta values generated in PRED for simulation purposes should be stored in ETA. What happens in this case is analogous to what happens in the case of population data with epsilon values.

In generated subroutines, eta values are automatically stored in ETA, and thus automatically, the simulated etas are available as input with repeated records.

Location prior to NONMEM 7: nmprd7

REFERENCES: None.

98 SIMULATION: IETAOL IEPSOL

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

USAGE:

USE NMPR_INT, ONLY: IETAOL,IEPSOL

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: IETAOL,IEPSOL

DISCUSSION:

Values are stored by PRED for use with SIMETA and SIMEPS. They allow the effect of the NEW option on the $SIMULATION record to be overridden, which may be useful when the PRED repetition feature is used. They also allow calls to SIMETA and SIMEPS to be ignored. This may be useful when e.g. a simulation was undertaken with user code where SIMEPS is called with every data record (as happens automatically with NM-TRAN generated codes), and the exact same simulation is now to be repeated, but with a data set obtained from the earlier one by the addition of new nonobservation records (with which SIMEPS output is not needed). If calls to SIMEPS with the new records are not ignored, SIMEPS output will be generated with all the records, and in particular, SIMEPS output will be generated with the original records, which will differ from what it was earlier, thus resulting in the simulation of a different set of observations.

IETAOL: IETAOL=-1: Next call to SIMETA will be ignored

IETAOL=0: Next call to SIMETA will behave as usual.

IETAOL=1: Next call to SIMETA will behave as though NEW had not been specified. If SIMETA has been called previously with the individual record, SIMETA will produce the previous eta values.

IEPSOL: IEPSOL=-1: Next call to SIMEPS will be ignored.

IEPSOL=0: Next call to SIMEPS will behave as usual.

IEPSOL=1: Next call to SIMEPS will behave as though NEW had not been specified. If SIMEPS has been called previously with the level-two record, SIMEPS will produce the previous epsilon values.

Values must be stored before PRED calls SIMETA (SIMEPS). NM-TRAN generated or Library code has a call to SIMETA (SIMEPS) in its second section (See Guide IV). If this call is to be affected, values must be stored using verbatim code in the FIRST block. Location prior to NONMEM 7: nmpr11.for

REFERENCES: None.

99 SIMULATION: NREP, `IREP`

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE ROCM_INT, ONLY: NREP,IREP=>NCREP

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: NREP,NCREP

DISCUSSION:

NREP: The number of replications in the Simulation Step, given by the NSUBS option of the $SIMULATION record.
IREP: The number of the current replication.

These variables may be used as right-hand quantities in abbreviated code for initialization/finalization blocks. Location prior to NONMEM 7: rocm10

REFERENCES: None.

100 SIMULATION: SIMEPS ERROR CODE

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

USAGE:

USE NMPRD_INT, ONLY: IERSQ

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: IERSQ

DISCUSSION:

Value is stored by SIMEPS for use with PRED and ERROR. Is relevant when correlations are stored in CORRL2. Is set to 0 before SIMEPS is called. (See Section 53.23).

IERSQ: The SIMEPS error return code.

IERSQ=0: Normal return
IERSQ=1: Correlation matrix obtained using the correlations stored in CORRL2 is not positive definite.

PRED may attempt corrective action; if it does so successfully, it should reset IERSQ to 0.

(With versions of NONMEM through 7.2, C was used rather than CORRL2.) With NONMEM 7.3 (and all earlier versions), the value of IERSQ is not checked in generated code. Location prior to NONMEM 7: nmprd6

REFERENCES: None.

101 SIZE OF INDIVIDUAL RECORD

MEANING: NONMEM read-only globoal variable

CONTEXT: PRED routine

USAGE:

USE ROCM_INT, ONLY: LIREC=>NDATPASS

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: NDATPASS

DISCUSSION:

LIREC is The number of data records contained in the individual record at the current call to PRED. LIREC also changes value appropriately in conjunction with calls to PASS. LIREC may be used as a right-hand quantity in $PRED, $PK, and $ERROR blocks, and in a $INFN block in conjunction with PASS. Location prior to NONMEM 7: rocm48

REFERENCES: None.

102 SIZES FSIZES PRSIZES

MEANING: MODULE for NONMEM and its components.

CONTEXT: Source code

DISCUSSION:

File SIZES is supplied on the NONMEM distribution media and is copied to the resources directory. It contains FORTRAN PARAMETER statements giving the default values of symbolic parameters used in source code. Constants from SIZES may be incorporated into the source code by means of the FORTRAN USE statement. Some of these constants describe array sizes.

With NONMEM 7.2 and higher, there are several changes vs. previous releases.

There is only one version of SIZES (i.e., there is no longer a SIZES_reg or SIZES_big).

Many NONMEM and NM-TRAN arrays are allocated dynamically at run time.

NM-TRAN creates a subroutine FSIZESR for NONMEM. FSIZESR contains values for some parameters (e.g., LVR) that are exactly what is needed for the current problem, and contains 0’s for parameters that NM-TRAN cannot assess. Default values for parameters that are 0 in FSIZESR are obtained by NONMEM from the file SIZES.f90.

Note that file FSIZES is a convenient reference for users to view, but is not used. SUBROUTINE FSIZESR in FSUBS is what is actually used during the NONMEM run.

NM-TRAN creates a file prsizes.f90 for PREDPP. PREDPP arrays are allocated statically but may be re-compiled at run time using parameters defined in prsizes.f90. Some constants in prsizes are assessed for the current problem; others are copied from default values in SIZES.f90.

The user may override many of the parameter values in FSIZES and prsizes with the $SIZES record. Any value specified by $SIZES will override both the default in SIZES.f90 and the value that NM-TRAN would have specified. (See Section 50.41) As of NONMEM 7.3, NMTRAN determines the maximum number of observation records (MDV=0) that occur in any subject, among all data files used in the entire control stream file. If this value is greater than the NO value listed in SIZES.f90, it will set NO to this larger size. Thus, users no longer have to be conscientious of sizing the NO parameter. However, there is no guarantee that NMTRAN will correctly assess NO for the entire scope of the control stream file for all types of problems. Should this occur, NONMEM may issue an error, and the user will need to set the NO value with a $SIZES record.

Constants that may be changed with $SIZES record:

LTH LVR LVR2 LPAR MMX MAXIDS NO PD MAXOMEG MAXPTHETA

Consants that are also in prsizes:

PC PCT PIR PD PAL MAXFCN

Constants that may not be changed using $SIZES record

LSTEXT MAXXNAME MAXVRESWRES MAXVRESN MXNAME DIMQ PPR PW
SD SCO SDF MAX_EXTRA

The following is the descriptive comment and value of each parameter in the version of SIZES that is supplied on the NONMEM 7 distribution medium. More information including descriptions of the buffers may be found in the INTRODUCTION TO NONMEM 7.

NLUSER=100: Maximum number of logical I/O units user may use.
LTH=100: MAX. NO. OF THETA’S. Dynamically sized, or set by user via $SIZES record
LVR=30: MAX. NO. OF ETA’S + EPS’S. Dynamically sized, or set by user via $SIZES record
LVR2=20: MAX. NO. OF ETA’S PERMITTED WHEN LAPLACIAN METHOD IS USED. Value may be over-ridden by user via $SIZES record Value may be over-ridden by user via $SIZES record
NO=250: MAX NO. OF OBSERVATION RECORDS / INDIVIDUAL RECORD
MMX=10: MAX NO. OF MIXTURE SUBPOPULATIONS. Dynamically sized, or set by user via $SIZES record
LNP4=4000: SIZE OF COMMON NMPRD4. Value may be over-ridden by user via $SIZES record
LSUPP=4050: MAX. NO. OF POINTS OF SUPPORT WITH NONPARAMETRIC ESTIMATE. Value may be over-ridden by user via $SIZES record
LIM7=2: SIZE OF BUFFER 7. DO NOT GO LOWER THAN 2. Value may be over-ridden by user via $SIZES record
LWS3=9000: SIZE OF WORKING SPACE 3 AT LEAST AS LARGE AS: NS*NOETAS**2, WHERE NS IS THE NO. OF DIRECTIONS USED WITH THE STIELTJES METHOD, AND NOETAS IS THE NUMBER OF ETA’S. Value may be over-ridden by user via $SIZES record
MAXIDS=10000: MAX. NO. OF INDIVIDUALS IN DATA SET. Dynamically sized, or set by user via $SIZES record
LIM1=10000: SIZE OF BUFFER 1. Value may be over-ridden by user via $SIZES record
LIM2=100000: SIZE OF BUFFER 2. Value may be over-ridden by user via $SIZES record
LIM3=10000: SIZE OF BUFFER 3. DO NOT GO LOWER THAN 2. Value may be over-ridden by user via $SIZES record
LIM4=1000: SIZE OF BUFFER 4: LIM4=NUMBER OF SUBJECTS. Value may be over-ridden by user via $SIZES record
LIM5=200: SIZE OF BUFFER 5. Value may be over-ridden by user via $SIZES record
LIM6=400: SIZE OF BUFFER 6. Value may be over-ridden by user via $SIZES record
LIM8=200: SIZE OF BUFFER 8. Value may be over-ridden by user via $SIZES record
LIM10=100000: SIZE OF BUFFER 10. Value may be over-ridden by user via $SIZES record
LIM11=25: SIZE OF BUFFER 11. Value may be over-ridden by user via $SIZES record
LIM13=1000: SIZE OF BUFFER 13: LIM13=NUMBER OF SUBJECTS. Value may be over-ridden by user via $SIZES record
LIM15=1000: SIZE OF BUFFER 15: LIM15=NUMBER OF SUBJECTS. Value may be over-ridden by user via $SIZES record
LIM16=400: SIZE OF BUFFER 16. Value may be over-ridden by user via $SIZES record
LSTEXT=70000: AT LEAST (MAXOMEG*(MAXOMEG+1)/2+MAXPHETA+5)*NUMTEXT. LSTEXT is maximun number of characters to a single line of the raw output file specified by $EST FILE=. where NUMTEXT is number of characters needed to represent a number and its delimiter. For example, FORMAT=,1PE12.5 takes up NUMTEXT=13 characters.
LSFORM=2048: LSFORM is the character length of FORMAT TFORMATL,RFORMATL, pertaining to the full length of LFORMAT, RFORMAT for the $TABLE record.
MAXRECID=200: Maximum number of records in any individual record. For use by PREDPP. Value may be over-ridden by user via $SIZES record
PC=30: MAX. NO. OF COMPARTMENTS MAXIMUM IS 99. Value may be over-ridden by user via $SIZES record
PCT=30: MAX. NO. OF MODEL EVENT TIMES. Value may be over-ridden by user via $SIZES record
MAXNRDS=PC: MAXNRDS: MAX. NO. OF DELAY COMPARTMENTS FOR ADVAN16, ADVAN17, and ADVAN18. YOU MAY WANT TO MAKE IT LOWER THAN PC AND SAVE MEMORY Value may be over-ridden by user via $SIZES record
PAST_SIZE=4000: RESOLUTION (NUMBER OF DETAILED POINTS) FOR DELAY COMPARTMENTS STORAGE FOR ADVAN16 AND ADVAN17. Value may be over-ridden by user via $SIZES record
PCT_BIG=10000: MAX. NO. OF MODEL EVENT TIMES THAT NMTRAN CAN PROCESS. PG: SIZE OF GG; MAX. NO. OF BASIC+ADDITIONAL PK PARAMS. (MAXIMUM IS PCT+99)
PIR=700: SIZE OF COMPACT DA/DP/DT ARRAYS. Value may be over-ridden by user via $SIZES record
PD=50: CHANGED TO INCREASE DATA ITEMS PER DATA RECORD FROM 20 TO 50 IT IS ALSO SIZE OF VDATREC DATA ARRAY. THIS IS DONE TO SEPARATE VDATREC AND VRESWRES VARIABLES/ Dynamically sized, or set by user via $SIZES record.
MAXIC=90: MAXIC: MAXIMUM NUMBER OF ACTIVE INFUSIONS FOR PREDPP. Value may be over-ridden by user via $SIZES record
PDT=500: MAXIMUM NUMBER OF TABLE ITEMS/PRED-DEFINED ITEMS. Value may be over-ridden by user via $SIZES record
PAL=50: NO. OF ADDITIONAL AND LAGGED DOSES. Value may be over-ridden by user via $SIZES record
MAXFCN=1000000: MAX. NO. OF CALLS IN GENERAL NON-LINEAR MODELS IMAX IN MODULE PRCOM_INT OVERRIDES. Value may be over-ridden by user via $SIZES record
STIELTJ_SIZE=101: The next four are for internal use, pertaining to various additional weighted residual diagnostics
MAXXNAME=40: 102.1 MAXVRESWRES=39
MAXVRESN=9: 102.2 MXNAME=40
DIMTMP=500: RELATED TO THE NUMBER OF USER-DEFINED VARIABLES. Value may be over-ridden by user via $SIZES record
DIMCNS=500: RELATED TO THE TOTAL NUMBER OF CONSTANTS. Value may be over-ridden by user via $SIZES record
DIMNEW=1000: RELATED TO THE TOTAL NUMBER OF INTERMEDIATE VARIABLES. Value may be over-ridden by user via $SIZES record
DIMQ=99999: ARRAY SIZE FOR LOGICAL CONDITIONS
FL=49: LOGICAL UNIT NUMBER FOR FLIB
DIMVRB=1000: MAX. NO. OF LINES OF VERBATIM CODE
PL=10: MAXIMUM DEPTH OF NESTED IF STATEMENTS
NFUNCX=100: MAXIMUM NUMBER OF USER FUNCTIONS.
NVECX=100: MAXIMUM NUMBER OF USER VECTORS.
MAXOTHER=1000: Maximum number of filenames listed on $SUBROUTINE OTHER=filename
SD=30: LENGTH OF DATA LABEL
FSD=67000: LENGTH OF CONTROL STREAM FILE STRING (ALSO, MULTIPLE LINES CONCATENATED WITH & MAY NOT EXCEED FSD)
FSD1=67001: LENGTH OF CONTROL STREAM FILE STRING
SCO=30: STRING LENGTH OF NUMBER IN $THETA, $OMEGA, $SGIGMA RECORDS.
SDF=24: LENGTH OF DATA ITEM
NFSIZES=50: NUMBER OF ITEMS LISTED IN FSIZES FILE
NPRSIZES=14: NUMBER OF PREDPP ITEMS IN PRSIZES.F90

CONSTANTS FOR Monte Carlo, EM methods

MAX_EXTRA=20: Numer of $EST statements allowed per problem
NPOPMIXMAX=10: Now dynamically sized to MAXIMUM NUMBER OF SUB-POPULATIONS FOR MIXTURE MODELS MMX. Or, set by user via $SIZES record
MAXOMEG=70: Now dynamically sizes to LVR, OR MAXIMUM OMEGA DIMENSION ETAS. Or, set by user via $SIZES record (but should be left alone)
MAXPTHETA=90: Now dynamically sized to LTH, MAXIMUM NUMBER OF THETA, PLUS LOWER TRIANGLE OF SIGMA. THUS, IF NUMBER OF THETAS IS N, AND DIMENSION OF SIGMAS IS M, THEN NEED MAXPTHETA=N + M*(M+1)/2. OR, may be set by user via $SIZES record (but should be left alone).
MAXITER=210: Maximum number of previous iterations to incorporate into Monte Carlo convergence tests Effective CITER is <=MAXITER
ISAMPLEMAX=10: FOR SAEM METHOD, EFFECTIVE ISAMPLE<=ISAMPLEMAX
MAXSIDS=100: MAXIMUM NUMER OF SUPER ID ITEMS IN DATA SET
MAXSIDL=0: MAXIMUM LEVEL OF SUPER IDS. MAXSIDL=0 MEANS NO SUPER IDS. Default 0, until $LEVEL is used, in which case it will be dynamically sized.
MAXFTEXT=100: Maximum of PRDERR message lines
PNM_MAXNODES=100: MAXIMUM NUMBER OF PARALLELIZATION NODES
PNM_BUFFER_SIZE=100000: INTERNAL BUFFER SIZE, FOR EFFICIENT PACKAGING AND SENDING BETWEEN PROCESSES

REFERENCES: Guide III, section V.3.0 REFERENCES: Guide Introduction_7

103 SKIP

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

USAGE:

USE NMPR_INT, ONLY SKIP_=>SKIP

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: SKIP

DISCUSSION:

The SKIP_ variable controls premature termination of a problem (with subproblems), superproblem or superproblem iteration. It may be set as follows during (sub)problem-finalization.

SKIP_=1: With a subproblem: terminate the entire problem and proceed to the next problem, if this exists.
SKIP_=2: With a problem during an iteration of a second-level superproblem A nested within a first-level superproblem B: terminate the iteration and proceed to the next iteration, if this exists, and if this does not exist, to the following (second-level super)problem of B, if this exists, and if this does not exist, to the next iteration of B.
SKIP_=3: With a problem during an iteration of a second-level superproblem A nested within a first-level superproblem B: terminate the entire superproblem A and proceed to the following (second-level super)problem of B, if this exists, and if this does not exist, to the next iteration of B.
SKIP_=4: With a problem during an iteration of a first-level superproblem: terminate the iteration and proceed to the next iteration, if this exists, and if this does not exist, to the following (first-level super)problem, if this exists.
SKIP_=5: With a problem during an iteration of a first-level superproblem: terminate the entire superproblem and proceed to the following (first-level super)problem, if this exists.

With NM-TRAN, in a finalization block of abbreviated code one may set SKIP_ and/or use the following phrases:

END PROBLEM                                   (same as SKIP_=1)
END SECOND-LEVEL SUPERPROBLEM                 (same as SKIP_=3)
END FIRST-LEVEL SUPERPROBLEM                  (same as SKIP_=5)
END SECOND-LEVEL SUPERPROBLEM ITERATION       (same as SKIP_=2)
END FIRST-LEVEL SUPERPROBLEM ITERATION        (same as SKIP_=4)

E.g. The following are all equivalent:

SKIP_=2

IF (...) THEN
 END SECOND - LEVEL SUPERPROBLEM ITERATION
ENDIF

IF (...) THEN
 ENDSECONDLEVELSUPERPROBLEMITERATION
ENDIF

Location prior to NONMEM 7: nmpr15

REFERENCES: None.

104 STANDARD ERRORS

MEANING: NONMEM read-only global variables

CONTEXT: PRED routine

USAGE:

USE ROCM_REAL, ONLY: SETHET=>SETH,SEOMEG=>SEOM,SESIGM=>SESIG,
       SETHETR=>SETHR

GLOBAL DECLARATION:

USE SIZES, ONLY: LTH,LVR,DPSIZE
REAL(KIND=DPSIZES) :: SETH(LTH),SEOM(LVR,LVR),SESIG(LVR,LVR)

DISCUSSION:

SETHET: SETHET(i) = the standard error of the estimate of theta(i).
SETHETR: SETHETR(i) = the standard error of the estimate of reported theta(i). If record $THETAR is not used, SETHET and SETHETR are equal. If record $THETAR is used, then SETHET is the standard error of the internal theta as used in $PK/$PRED, and SETHETR is the standard error of the theta reported in the report file.
SEOMEG: SEOMEG(i,j) = the standard error of the estimate of omega(i,j).
SESIGM: SESIGM(i,j) = the standard error of the estimate of sigma(i,j).

These values should only be used with ICALL = 3. Location prior to NONMEM 7: rocm7

REFERENCES: Guide I, section C.3.5.2 REFERENCES: Guide V, section 5.4.2.1

105 STATE VECTOR TIME: TSTATE

MEANING: PREDPP read-only global variables

CONTEXT: User-supplied PK and ERROR routine

USAGE:

USE PROCM_REAL, ONLY: TSTATE

GLOBAL DECLARATION:

USE SIZES, ONLY: DPSIZE
REAL(KIND=DPSIZE) :: TSTATE

DISCUSSION:

TSTATE: TSTATE = the time at which the state-vector (See Section 53.106) was last computed. It is the previous event time (i.e. the time on the previous event record passed to PK), 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 TSTATE is the latest such time.

NM-TRAN includes this global variable in the PK and ERROR routines when $PK or $ERROR abbreviated code includes references to variables A(n) or when verbatim code is present. Location prior to NONMEM 7: procm9

REFERENCES: None.

106 STATE VECTOR: A

MEANING: PREDPP read-only global variables

CONTEXT: User-supplied PK and ERROR routines

USAGE:

USE PROCM_REAL, ONLY A=>AMNT,DAETA,D2AETA

GLOBAL DECLARATION:

USE SIZES, ONLY: PC,LVR,DPSIZE
REAL(KIND=DPSIZE) :: AMNT(PC),DAETA(PC,LVR),D2AETA(PC,LVR,LVR)

DISCUSSION:

A: A is the state vector of compartment amounts. A(n) = the amount in compartment n.
DAETA: DAETA(n,i) = the derivative of A(n) wrt eta(i).
D2AETA: D2AETA(n,i,j) = the second derivative of A(n) wrt eta(i), eta(j) (lower-triangular; j=1, …, i).

The A(n) can be used as right-hand quantities in $ERROR and $PK abbreviated code. These amounts are the latest ones computed. With $ERROR, the A(n) are computed at the event time on the event record passed to ERROR. With $PK, the A(n) are computed at the event time on the previous event record, or possibly at a later time. This time - the latest time at which the amounts are computed - is given in the variable TSTATE, which may also be used in $PK abbreviated code. (See Section 53.105).

Location prior to NONMEM 7: procm4

REFERENCES: Guide VI, section IV.D, Figure 14

107 STOP TIME, ITASK (NM75)

MEANING: PREDPP-PK global variables

CONTEXT: User-supplied routines

USAGE:

USE PRLS01_REAL, ONLY: STOP_TIME
USE PRLS01_INT, ONLY: ITASK_=>ITASK

GLOBAL DECLARATION:

USE SIZES, ONLY: DPSIZE
REAL (KIND=DPSIZE) STOP_TIME
USE SIZES, ONLY: ISIZE
INTEGER(KIND=ISIZE) ITASK_

DISCUSSION:

These reserved variables are used to avoid overshoot in ADVAN9, ADVAN13, ADVAN14, and ADVAN15. These LSODA based routines use an algorithm for integration that overshoots the integration interval during calls to DES, but still accurately evaluates at the end of the integration interval when all calculations are completed. However, you may wish to capture a maximal or minimal value during $DES, and the overshoot should be turned off for this purpose. This is readily done by setting ITASK_=4 in $PK or $ERROR. E.g.,

$PK ITASK_ = 4

ITASK_ may take values between 1 and 5.

For other values of ITASK_ and a discussion of these variables, See INTRODUCTION TO NONMEM 7, “ITASK_ and STOP_TIME: Avoiding overshoot in ADVAN9, ADVAN13, ADVAN14, and ADVAN15”

You may also specify a STOP_TIME (Tcrit) past which it should not integrate, if it is different from the end of the normal integration interval:

IF(TIME==4.0) STOP_TIME = 5.0

To set back to default (end of normal integration interval),

STOP_TIME=-1.0d+300

REFERENCES: Guide Introduction_7

108 SUPER PROBLEM PRINT CONTROL

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE NMPRD_INT, ONLY IPRNV

GLOBAL DECLARATION:

INTEGER(KIND=ISIZE) :: IPRNV(2)

DISCUSSION:

IPRNV(i)

0 indicates no printing of NONMEM input information with iterations 2, 3, etc. of active ith level superproblem.

1 indicates printing of NONMEM input information with iterations 2, 3, etc. of active ith level superproblem.

Status with 2nd level superproblem takes precedence. (See Section 50.44). Location prior to NONMEM 7: rocm28

REFERENCES: None.

109 TOL

MEANING: TOL subroutine

CONTEXT: User-supplied subroutine; for use with PREDPP

USAGE:

Versions before NONMEM 7.4:

SUBROUTINE TOL(NRD)

USE SIZES, ONLY: ISIZE

INTEGER(KIND=ISIZE) :: NRD

DIMENSION :: NRD(*)

With NONMEM 7.4:

SUBROUTINE TOL(NRD,ANRD,NRDC,ANRDC)

USE SIZES, ONLY: ISIZE

INTEGER(KIND=ISIZE) :: NRD(0:*), ANRD(0:*), NRDC(0:*), ANRDC(0:*)

Optional declarations with NONMEM 7.4:

USE NMPRD_INT, ONLY: IPROB
USE NM_BAYES_INT, ONLY: NM_STEP,BASE_STEP,EST_STEP,COV_STEP, &
 TABLE_STEP,SIML_STEP,INE_STEP, NONP_STEP

DISCUSSION:

The TOL subroutine is called by PREDPP when ADVAN 6, 8, 9, 10, 13, 14, 15, 16, 17, or 18 is used. It is also called when SS6 or SS9 is used. With NONMEM 7.4, there are multiple calls during the run, for each NONMEM step. With earlier version, TOL is called only once at the start of a run.

OPTIONS:

Output argument:

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 (ADVAN 14 and 15 only allow different absolute tolerances for each compartment). 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, 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, and 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, and 15, 16, 17, and 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.

When NM-TRAN is used, this information may be supplied by either the TOL option of the $SUBROUTINES record or the $TOL record.

Finally, you may supply a TOL routine that assigns values of NRD and ANRD specifically for the initial (base) setting and each NONMEM step (estimation, covariance, simulation, table/scatter step, simulation, initial parameters estimate, nonparametric). For example, create a toluser.f90 file,

SUBROUTINE TOL(NRD,ANRD,NRDC,ANRDC)
USE NMPRD_INT, ONLY: IPROB
USE NM_BAYES_INT, ONLY: NM_STEP,BASE_STEP,EST_STEP,COV_STEP, &
 TABLE_STEP,SIML_STEP,INE_STEP, NONP_STEP
IMPLICIT NONE
INTEGER :: NRD(0:*), ANRD(0:*), NRDC(0:*), ANRDC(0:*)
IF(NM_STEP==EST_STEP) THEN
NRD(1)=6
ANRD(1)=10
ELSE IF (NM_STEP==COV_STEP) THEN
NRD(1)=7
ANRD(1)=8
ELSE IF (NM_STEP==TABLE_STEP) THEN
NRD(1)=8
ANRD(1)=7
ELSE
NRD(1)=9
ANRD(1)=12
ENDIF
IF(IPROB>1) THEN
NRD(1)=NRD(1)+1
ANRD(1)=ANRD(1)+1
ENDIF
RETURN
END

and incorporate using $SUBR, e.g.,

$SUBROUTINES ADVAN13 TRANS1 TOL = toluser.f90

REFERENCES: Guide IV, section V.C.4

REFERENCES: Guide VI, section VI.D, Figure 41

REFERENCES: Guide VI, Appendix II

110 TRANS (SUBROUTINE)

MEANING: TRANS subroutine

CONTEXT: User-supplied subroutine; for use with PREDPP

USAGE:

SUBROUTINE TRANS (ITRANS,IRGG,GG,NETAS)
USE SIZES, ONLY: ISIZE,DPSIZE,LVR
INTEGER(KIND=ISIZE) :: IRGG,NPETAS,ITRANS
REAL(KIND=DPSIZE) :: GG(IRGG,LVR+1,LVR+1)

DISCUSSION:

The TRANS subroutine translates (or transforms) the values for a set of basic PK parameters modeled in PK to a set of values for the internal parameters required by the ADVAN. The PREDPP Library has a number of TRANS subroutines, representing different possible parameterizations in PK, from which the user may choose. If a suitable translator is not found in the Library, the user may write his own.

OPTIONS:

Input/Output argument:

ITRANS: ITRANS=1: TRANS has been called for initialization at the beginning of a NONMEM problem; one such call per problem. ITRANS must be reset by TRANS to a number in the range 1-8999. This number appears on NONMEM output, allowing the user to identify the TRANS routine being used.

ITRANS=2: On input the GG array has stored in it the values computed by PK (except that were any PK parameter modeled in its logarithm form in PK, PREDPP would have already exponentiated its typical/subject-specific value and multiplied its eta derivatives by its exponentiated typical/subject-specific value). On output the GG array should have stored in it the values that would be computed by PK were the internal parameters of the ADVAN modeled directly in PK (and none in their logarithmic form).

ITRANS=4: TRANS has been called during the Simulation Step. Only the first column of the GG array need be computed as with ITRANS=2. Other columns need not be computed.

GG: The array of PK parameters and their eta derivatives. The array is described elsewhere; (See Section 53.77).

Input argument:

NETAS: The number of population etas in the problem.

Certain variables are available in modules. Their use is optional.

Variables in read/write modules:

IERPRD NETEXT ETEXT
(See Section 53.81).
(See Section 53.80).

Variables in read-only commons:

NOETAS, SECOND
(See Section 53.73).

When SECOND is true, PREDPP requires second-partial derivatives of etas.

REFERENCES: Guide VI, section III.M

111 VARIABLES IN MODULES

MEANING: Variables in Modules

CONTEXT: Abbreviated code

DISCUSSION:

Variables in certain FORTRAN modules may be used in abbreviated code. With NONMEM 7.2 and higher, either upper or lower case may be used.

Variables in modules whose names start ROCM or PROCM may be used only on the right. Variables in modules whose names start NMPR or PRDPK may always be used on the right and may sometimes be used on the left. Names of modules are reserved and may not be used in any block of abbreviated code.

Provided is a list of blocks of abbreviated code and the modules and variables that may be used. Second is a list of modules, the variables in the modules, and the blocks of abbreviated code in which these variables may be used.

$AES
NMPRD_INT:  COMACT,COMSAV
NMPRD_INT:  NPROB,IPROB
NMPRD_INT:  S1IT,S1NIT,S1NUM,S2IT,S2NIT,S2NUM
NMPRD_INT:  NTHES_,NETAS_,NEPSS_
NMPR_INT:   RPTI,RPTO,RPTON,PRDFL
PKERR_REAL: MTIME
PRMOD_INT:  ICALL,IDEFD,IDEFA
PRMOD_INT:  MTDIFF
PROCM_INT:  ISFINL
PROCM_INT:  MNOW,MPAST,MNEXT
PROCM_INT:  NVNT
PROCM_REAL: DOSREC
PROCM_REAL: DOSTIM
PROCM_REAL: EVTREC
PROCM_REAL: THETA
ROCM_INT:   MIXNUM,MIXEST
ROCM_INT:   NIREC,NDREC
ROCM_INT:   NREP,IREP
ROCM_REAL:  MIXP

$DES
NMPRD_INT:  COMACT,COMSAV
NMPRD_INT:  MSEC,MFIRST,IFIRSTEM
NMPRD_INT:  NPROB,IPROB
NMPRD_INT:  S1IT,S1NIT,S1NUM,S2IT,S2NIT,S2NUM
NMPRD_INT:  NTHES_,NETAS_,NEPSS_
NMPR_INT:   RPTI,RPTO,RPTON,PRDFL
PKERR_REAL: MTIME
PRMOD_INT:  ICALL,IDEFD,IDEFA
PRMOD_INT:  MTDIFF
PROCM_INT:  ISFINL
PROCM_INT:  MNOW,MPAST,MNEXT
PROCM_INT:  NVNT
PROCM_REAL: DOSREC
PROCM_REAL: DOSTIM
PROCM_REAL: EVTREC
PROCM_REAL: THETA
ROCM_INT:   MIXNUM,MIXEST
ROCM_INT:   NIREC,NDREC
ROCM_INT:   NREP,IREP
ROCM_REAL:  MIXP

$ERROR
CMNM1_INT:  NIND_7
NMPRD_INT:  COMACT,COMSAV
NMPRD_INT:  MSEC,MFIRST,IFIRSTEM
NMPRD_INT:  NEWL2
NMPRD_INT:  NPROB,IPROB
NMPRD_INT:  S1IT,S1NIT,S1NUM,S2IT,S2NIT,S2NUM
NMPRD_INT:  NTHES_,NETAS_,NEPSS_
NMPRD_INT:  MDVRES
NMPRD_INT:  NPDE_MODE
NMPRD_INT:  ETASXI
NMPRD_INT:  NOFIRSTDERCODE
NMPRD_REAL: CORRL2
NMPRD_REAL: ETA,EPS
NMPR_INT:   F_FLAG
NMPR_INT:   RPTI,RPTO,RPTON,PRDFL
NMPR_REAL:  CTLO
NMPR_REAL:  CTUP
NMPR_REAL:  YLO,YUP
NMPR_REAL:  THSIMP,OMSIMP,SGSIMP,THSIMPR
PKERR_REAL: MTIME
PRMOD_INT:  MTDIFF
PROCM_INT:  MNOW,MPAST,MNEXT
PROCM_INT:  NEWIND
PROCM_REAL: A
ROCM_INT:   LIREC
ROCM_INT:   MIXNUM,MIXEST
ROCM_INT:   NINDR,INDR1,INDR2
ROCM_INT:   NIREC,NDREC
ROCM_INT:   NREP,IREP
ROCM_REAL:  CNTID
ROCM_REAL:  CDEN_,DEN_
ROCM_REAL:  IIDX
ROCM_REAL:  MIXP
ROCM_REAL:  OMEGA
ROCM_REAL:  PR_CT
ROCM_REAL:  PR_Y
ROCM_REAL:  TEMPLT

$INFN
CMNM1_INT:  NIND_7
NMPRD_INT:  NEWL2
NMPRD_INT:  NPROB,IPROB
NMPRD_INT:  S1IT,S1NIT,S1NUM,S2IT,S2NIT,S2NUM
NMPRD_INT:  NWIND
NMPRD_INT:  PRED_IGNORE_DATA,PRED_IGNORE_DATA_TEST
NMPRD_REAL: CORRL2
NMPRD_REAL: ETA,EPS
NMPRD_REAL: PASSRC
NMPR_INT:   F_FLAG
NMPR_INT:   RPTI,RPTO,RPTON,PRDFL
NMPR_INT:   SKIP_
NMPR_REAL:  THSIMP,OMSIMP,SGSIMP,THSIMPR
PRMOD_INT:  I_SS,ISSMOD
ROCM_INT:   IERE,IERC
ROCM_INT:   LIREC
ROCM_INT:   MIXNUM,MIXEST
ROCM_INT:   NINDR,INDR1,INDR2
ROCM_INT:   NIREC,NDREC
ROCM_INT:   NREP,IREP
ROCM_REAL:  CDEN_,DEN_
ROCM_REAL:  CNTID
ROCM_REAL:  IIDX
ROCM_REAL:  MIXP
ROCM_REAL:  OBJECT
ROCM_REAL:  PR_CT
ROCM_REAL:  PR_Y
ROCM_REAL:  SETHET,SEOMEG,SESIGM,SETHETR
ROCM_REAL:  THETAF,OMEGAF,SIGMAF,THETAFR
ROCM_REAL:  PRED_,RES_,WRES_,NPRED_,NRES_,NWRES_
ROCM_REAL:  CPRED_,CRES_,CWRES_,PREDI_,RESI_,WRESI_,
ROCM_REAL:  CPREDI_,CRESI_,CWRESI_,EPRED_,ERES_,EWRES_
ROCM_REAL:  NPDE_,ECWRES_

$MIX
NMPRD_INT: NPROB,IPROB
NMPRD_INT: S1IT,S1NIT,S1NUM,S2IT,S2NIT,S2NUM
NMPRD_INT: NTHES_,NETAS_,NEPSS_
ROCM_INT:  NINDR,INDR1,INDR2
ROCM_INT:  NIREC,NDREC
ROCM_INT:  NREP,IREP
ROCM_INT:  TEMPLT
ROCM_REAL: THETA,DATA

$PK
CMNM1_INT:  NIND_7
NMPRD_INT:  COMACT,COMSAV
NMPRD_INT:  MSEC,MFIRST,IFIRSTEM
NMPRD_INT:  NPROB,IPROB
NMPRD_INT:  S1IT,S1NIT,S1NUM,S2IT,S2NIT,S2NUM
NMPRD_INT:  NTHES_,NETAS_,NEPSS_
NMPRD_INT:  MDVRES
NMPRD_INT:  NPDE_MODE
NMPRD_INT:  ETASXI
NMPRD_INT:  NOFIRSTDERCODE
NMPRD_REAL: CORRL2
NMPRD_REAL: ETA,EPS
NMPR_INT:   RPTI,RPTO,RPTON,PRDFL
NMPR_REAL:  THSIMP,OMSIMP,SGSIMP,THSIMPR
PKERR_REAL: MTIME
PRMOD_INT:  I_SS,ISSMOD
PRMOD_INT:  MTDIFF
PRMOD_REAL: A_0
PROCM_INT:  A_0FLG
PROCM_INT:  MNOW,MPAST,MNEXT
PROCM_INT:  NEWIND
PROCM_REAL: A
PROCM_REAL: DOSREC
PROCM_REAL: DOSTIM
PROCM_REAL: TSTATE
ROCM_INT:   LIREC
ROCM_INT:   MIXNUM,MIXEST
ROCM_INT:   NINDR,INDR1,INDR2
ROCM_INT:   NIREC,NDREC
ROCM_INT:   NREP,IREP
ROCM_REAL:  CNTID
ROCM_REAL:  CDEN_,DEN_
ROCM_REAL:  IIDX
ROCM_REAL:  MIXP
ROCM_REAL:  OMEGA
ROCM_REAL:  PR_CT
ROCM_REAL:  PR_Y

$PRED
CMNM1_INT:  NIND_7
NMPRD_INT:  COMACT,COMSAV
NMPRD_INT:  I_REC
NMPRD_INT:  MSEC,MFIRST,IFIRSTEM
NMPRD_INT:  NEWL2
NMPRD_INT:  NPROB,IPROB
NMPRD_INT:  S1IT,S1NIT,S1NUM,S2IT,S2NIT,S2NUM
NMPRD_INT:  NTHES_,NETAS_,NEPSS_
NMPRD_INT:  MDVRES
NMPRD_INT:  NPDE_MODE
NMPRD_INT:  ETASXI
NMPRD_INT:  NOFIRSTDERCODE
NMPRD_INT:  PRED_IGNORE_DATA,PRED_IGNORE_DATA_TEST
NMPRD_REAL: CORRL2
NMPRD_REAL: ETA,EPS
NMPR_INT:   F_FLAG
NMPR_INT:   RPTI,RPTO,RPTON,PRDFL
NMPR_INT:   SKIP_
NMPR_REAL:  CTLO
NMPR_REAL:  CTUP
NMPR_REAL:  THSIMP,OMSIMP,SGSIMP,THSIMPR
NMPR_REAL:  YLO,YUP
ROCM_INT:   IERE,IERC
ROCM_INT:   LIREC
ROCM_INT:   MIXNUM,MIXEST
ROCM_INT:   NINDR,INDR1,INDR2
ROCM_INT:   NIREC,NDREC
ROCM_INT:   NREP,IREP
ROCM_REAL:  CNTID
ROCM_REAL:  CDEN_,DEN_
ROCM_REAL:  IIDX
ROCM_REAL:  MIXP
ROCM_REAL:  OBJECT
ROCM_REAL:  OMEGA
ROCM_REAL:  PR_CT
ROCM_REAL:  PR_Y
ROCM_REAL:  SETHET,SEOMEG,SESIGM,SETHETR
ROCM_REAL:  TEMPLT
ROCM_REAL:  THETAF,OMEGAF,SIGMAF,THETAFR
ROCM_REAL:  PRED_,RES_,WRES_,NPRED_,NRES_,NWRES_
ROCM_REAL:  CPRED_,CRES_,CWRES_,PREDI_,RESI_,WRESI_,
ROCM_REAL:  CPREDI_,CRESI_,CWRESI_,EPRED_,ERES_,EWRES_
ROCM_REAL:  NPDE_,ECWRES_

MODULES: VARIABLES
         BLOCKS

CMNM1_INT: NIND_7
           $ERROR $PK $PRED $INFN

NMPRD_INT: COMACT,COMSAV
           $DES $AES $ERROR $PK $PRED

NMPRD_INT: I_REC
           $PRED

NMPRD_INT: MSEC,MFIRST,IFIRSTEM
           $DES $ERROR $PK $PRED

NMPRD_INT: NEWL2
           $ERROR $PRED $INFN

NMPRD_INT: NPROB,IPROB
           $DES $AES $ERROR $MIX $PK $PRED $INFN

NMPRD_INT: NTHES_,NETAS_,NEPSS_
           $DES $AES $ERROR $MIX $PK $PRED

NMPRD_INT: NWIND
           $INFN

NMPRD_INT: S1IT,S1NIT,S1NUM,S2IT,S2NIT,S2NUM
           $DES $AES $ERROR $MIX $PK $PRED $INFN

NMPRD_REAL: CORRL2
            $ERROR $PK $PRED $INFN

NMPRD_REAL: ETA,EPS
            $ERROR $PK $PRED $INFN

NMPRD_REAL: PASSRC
            $INFN

NMPR_INT: F_FLAG
          $ERROR $PRED $INFN

NMPR_INT: RPTI,RPTO,RPTON,PRDFL
          $DES $AES $ERROR $PK $PRED $INFN

NMPR_INT: SKIP_
          $PRED $INFN

NMPR_REAL: CTLO
           $ERROR $PRED $ERROR $PRED

NMPR_REAL: THSIMP,OMSIMP,SGSIMP,THSIMPR
           $PK $PRED $INFN

NMPR_REAL: YLO,YUP
           $ERROR $PRED

NMPR_REAL: THSIMP,OMSIMP,SGSIMP,THSIMPR
           $ERROR

PKERR_REAL: MTIME
            $DES $AES $ERROR $PK

PRMOD_INT: ICALL,IDEFD,IDEFA
           $DES $AES

PRMOD_INT: I_SS,ISSMOD
           $PK $INFN

PRMOD_INT: MTDIFF
           $DES $AES $ERROR $PK

PRMOD_REAL: A_0
            $PK

PROCM_INT: A_0FLG
           $PK

PROCM_INT: ISFINL
           $DES $AES

PROCM_INT: MNOW,MPAST,MNEXT
           $DES $AES $ERROR $PK

PROCM_INT: NEWIND
           $ERROR $PK

PROCM_INT: NVNT
           $DES $AES

PROCM_REAL: A
            $ERROR $PK

PROCM_REAL: DOSREC
            $DES $AES $PK

PROCM_REAL: DOSTIM
            $DES $AES $PK

PROCM_REAL: EVTREC
            $DES $AES

PROCM_REAL: THETA
            $DES $AES

PROCM_REAL: TSTATE
            $PK

ROCM_INT: IERE,IERC
          $PRED $INFN

ROCM_INT: LIREC
          $ERROR $PK $PRED $INFN

ROCM_INT: MIXNUM,MIXEST
          $DES $AES $ERROR $PK $PRED $INFN

ROCM_REAL: NINDR,INDR1,INDR2
           $ERROR $MIX $PK $PRED $INFN

ROCM_REAL: NIREC,NDREC
           $DES $AES $ERROR $MIX $PK $PRED $INFN

ROCM_REAL: NREP,IREP
           $DES $AES $ERROR $MIX $PK $PRED $INFN

ROCM_REAL: CDEN_,DEN_
           $ERROR $PK $PRED $INFN

ROCM_REAL: CNTID
           $ERROR $PK $PRED $INFN

ROCM_REAL: CPREDI_,CRESI_,CWRESI_,EPRED_,ERES_,EWRES_
           $PRED $INFN

ROCM_REAL: CPRED_,CRES_,CWRES_,PREDI_,RESI_,WRESI_
           $PRED $INFN

ROCM_REAL: IIDX
           $ERROR $PK $PRED $INFN

ROCM_REAL: MIXP
           $DES $AES $ERROR $PK $PRED $INFN

ROCM_REAL: NPDE_,ECWRES_
           $PRED $INFN

ROCM_REAL: OBJECT
           $PRED $INFN

ROCM_REAL: OMEGA
           $ERROR $PK $PRED

ROCM_REAL: PRED_,RES_,WRES_,NPRED_,NRES_,NWRES_
           $PRED $INFN

ROCM_REAL: PR_CT
           $ERROR $PK $PRED $INFN

ROCM_REAL: PR_Y
           $ERROR $PK $PRED $INFN

ROCM_REAL: SETHET,SEOMEG,SESIGM,SETHETR
           $PRED $INFN

ROCM_REAL: TEMPLT
           $ERROR $MIX $PRED

ROCM_REAL: THETA,DATA
           $MIX $PRED $INFN

NOTE: NONMEM RESERVED VARIABLES

There are many other variables that are generally internal to NONMEM, and often are not needed by users except occasionally, which are not explicitly recognized by NMTRAN.

Examples are

ITER_REPORT, BAYES_EXTRA_REQUEST, BAYES_EXTRA

in module NMBAYES_INT.

Such variables can be used in abbreviated code if they are listed in include files whose names start with NONMEM_RESERVED. See NONMEM_RESERVED_GENERAL in directory ..\util. It needs to be copied from util to the present run directory so that NM-TRAN has access to it. (See Section 53.1). (See Section 60.12).

REFERENCES: Guide Introduction_7

112 VERBATIM CODE

MEANING: FORTRAN statements

CONTEXT: Abbreviated code

USAGE:

" verbatim line

DISCUSSION:

Verbatim code is FORTRAN code within a block of abbreviated code that is to be copied by NM-TRAN to the generated FORTRAN subroutine. It is not itself regarded as abbreviated code. Such code is marked by having the character " as the first non-blank character. The " is dropped and the characters to the right are copied as-is to columns 1-72 of the generated subroutine. Lines of verbatim code can include any FORTRAN statements: comment, declaration (e.g., INTEGER, COMMON, USE), I/O, CALL, assignment, continuation, DO, GOTO, etc.). Lower-case characters can be used freely, if the FORTRAN compiler permits them.

NM-TRAN does make some modifications to verbatim code, as follows:

OPTIONS:

Placement of code: The verbatim code is adjusted as necessary to conform to FORTRAN column conventions. Alphabetic text that follows the initial ", or that follows a statement number, is moved to column 7, as required by FORTRAN, except for:
Comment lines: 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 !. Example:

"! this is a comment

Continuation lines: Fortran 77 continuation lines (non-blank in position 6) are not permitted with NONMEM 7. Instead, the line to be continued should end with character &. Example:

" X=A &
" +D/E

Replacement Rule: In $PK, $ERROR, $DES, $AES, $INFN, and $PRED, in a line of abbreviated code labels of items in the data record are replaced by direct references to the data record itself (either DATREC or EVTREC, as appropriate). Thus, for example, if such a label occurs as the left-hand side of an assignment statement, then without this rule, when the statement is executed, the value of a local variable having the label is modified, whereas with the rule, an item in the data record is modified.

The character @, immediately before a label, can be used as an “escape” to prevent the label from being replaced. If the character @ immediately follows the initial ", none of the labels occuring in the line are replaced.

Labels occurring in common statements or as subroutine arguments are never replaced.

Low-value Character: Tab characters (and other characters that are smaller than blank in the computer’s collating sequence, such as carriage return ^M) are permitted 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. This permits DOS-type line endings ^M.

By default, all verbatim code goes in the main section of code and is called MAIN verbatim code. (The main section follows declarations and initial executable code inserted by NM-TRAN.) Within the main section, verbatim and abbreviated code may be freely mixed. Each line of verbatim code is positioned in the generated code after all code generated from the preceding line of abbreviated code. The user may explicitly specify a different location as follows.

FIRST verbatim code: Verbatim lines which must be positioned immediately after the declarations which are part of the normal subroutine header, and prior to the FIRST executable statement of the subroutine, must precede the first line of abbreviated code and must start with the line "FIRST.
MAIN verbatim code: FIRST verbatim code is normally terminated by the first line of abbreviated code. If there is both FIRST and MAIN verbatim code, and/or the main section is to start with verbatim code, the line "MAIN may be used to separate the FIRST and MAIN verbatim code.
LAST verbatim code: Verbatim lines which are to immediately precede the RETURN statement from the generated subroutine must follow the last line of abbreviated code and must be preceded by the line "LAST.

Example:

`$ERROR`
Y = F * (1 + ERR(1))
"LAST
" PRINT *,HH(1,1)

This displays values after they have been assigned, immediately prior to the return.

If any lines of verbatim code are present in a block of abbreviated code, NM-TRAN generates USE statements appropriate to the kind of abbreviated code and allows variables undefined in abbreviated code to be used as right-hand quantities in abbreviated code.

Verbatim code is meant for use by expert users of NONMEM who are able to understand the generated FORTRAN subroutine and check that the verbatim code has the desired effect.

REFERENCES: Guide IV, section IV.I

113 WRITE FORMATS

MEANING: PREDPP read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE PROCM_CHAR, ONLY: FMT

GLOBAL DECLARATION:

CHARACTER*80 FMT(3)

DISCUSSION:

OPTIONS:

FMT(1): A suitable format statement for WRITE statements when the full omega array is written.
FMT(2): A suitable format statement for WRITE statements when the full sigma array is written.
FMT(3): A suitable format statement for WRITE statements when the full theta array is written.

Location prior to NONMEM 7: procm8

REFERENCES: None.

114 WRITE PRINT

MEANING: FORTRAN statements

CONTEXT: Abbreviated code

SAMPLE:

WRITE (50,*) 99,ID,CL,`THETA`(1),ETA(1)

IF (`ICALL`.EQ.3) THEN
    WRITE (55,2) BIAS

ENDIF

DISCUSSION:

Certain forms of FORTRAN WRITE, PRINT, OPEN, CLOSE, and REWIND statements may be used anywhere in $PRED, $INFN, $PK, $ERROR, $DES, $AES, $AESINITIAL blocks.

PRINT list ...
PRINT *,list ...
WRITE (unit,format) list ...
WRITE (*,format) list ...
WRITE (unit,*) list ...
WRITE (*,*) list ...
OPEN(unit)
OPEN(unit,FILE=filename)
CLOSE(unit)
REWIND(unit)

Single or double quotes around the filename are optional. However, if the filename 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, filename may not contain embedded spaces, and may contain at most 71 characters.

OPTIONS:

unit: 6, n or *.

6 indicates the unit connected to the NONMEM output file.
n indicates the number of an alternative unit (40<n<2000).
* indicates a FORTRAN system-dependent output (with most systems, this is equivalent to using unit 6, but see the FORTRAN documentation). With OPEN, CLOSE and REWIND, the unit may not be 6 or *.

format: *, 1, 2, 991, or 992.

* indicates list-directed output. (FORTRAN library routines will select a format appropriate for the current run-time value of the quantity when displayed.)
1 or 991 requests the built-in format specification:

991 FORMAT (35F14.4)

2 or 992 requests the built-in format specification:

992 FORMAT (35E15.7)

(Format specification numbers 991 and 992 are used in generated code to avoid conflict with statement numbers arising from DO WHILE statements. The one digit versions are perhaps easier to remember.)

(No integer format specification is provided because constants are stored as floating point variables in generated and library routines.)

list: A list of one or more right-hand quantities, i.e., variables or constants that may appear on the right in abbreviated code. May not include expressions or names of abbreviated functions. When subscripts are appropriate, these must be integer constants, declared integer variables, or expressions involving such constants and variables.

With a PRINT statement, a list may also include character constants. A character constant is delimited by single or double quotes (' or "). As with any Fortran character constant, a pair of adjacent delimiters within the constant represents a single character. E.g., PRINT *,'A isn''t B' will appear in the output as:

A isn't B

In an initialization or finalization block, a list may include elements of the OMEGA and SIGMA arrays. In a finalization block, a list may include elements of the standard error arrays (SETHET, SETHETR, SEOMEG and SESIGM).

Any array whose elements may be listed individually in a WRITE or PRINT statement may also be written in its entirety, by listing it without any subscripts. Specifically, one or more of the following may be included in a list:

`THETA` THETAFR SETHET SETHETR
THSIMP ETA THSIMPR
`OMEGA`(BLOCK) `OMEGA`(DIAG) SEOMEG(BLOCK) SEOMEG(DIAG)
OMSIMP(BLOCK) OMSIMP(DIAG)
`SIGMA`(BLOCK) `SIGMA`(DIAG) SESIGM(BLOCK) SESIGM(DIAG)
SGSIMP(BLOCK) SGSIMP(DIAG)
IIDX CNTID IIDX,CNTID

Note that IIDX and CNTID are arrays in a module; (See Section 53.69). When "IIDX" or "CNTID" is listed, then only that array is written. When "IIDX,CNTID" is specified, then pairs of values are written, one pair per line, one pair for each individual record.

The option BLOCK requests that the entire array be written in full symmetric form. The option DIAG requests that only the diagonal elements be written. DIAG may also be coded DIAGONAL. Arrays of possibly different sizes (e.g., OMEGA and SIGMA) may not be listed together in the same WRITE statement. If a WRITE statement requests that an entire array be written, then the only other items that may be listed with the statement are other entire arrays.

When entire arrays are written, the format specification with a WRITE statement must be *. With either a WRITE or PRINT statement, an appropriate format is created by the NONMEM system. With these formats, elements of the standard error arrays that do not exist have the value 1E10 and are printed as 0.1000000E+11. (Such elements appear in NONMEM output as dots (.........).) If the covariance step fails or is not requested, all elements of the standard error arrays are 0 and are printed as 0.0000000E+00.

Example: To write the omega matrix and its standard errors in symmetric form code the following. (Only as many elements will be written as are appropriate for the dimension of omega in the problem.)

IF (`ICALL`.EQ.3) WRITE (99,*) `OMEGA`(BLOCK),SEOMEG(BLOCK)

A list may also include a vector element or the entire vector (by listing the vector without a subscript).

The OPEN, CLOSE, and REWIND statements are part of the FORTRAN language. For details (i.e., the relationship of external files to units), see the Language Reference Manual and the Users Guide for your compiler.

REFERENCES: None.

115 YLO YUP

MEANING: NONMEM-PRED global variables

CONTEXT: PRED routine

USAGE:

USE NMPR_REAL, ONLY: YLO,YUP

GLOBAL DECLARATION:

USE SIZES, ONLY: DPSIZE
REAL(KIND=DPSIZE) :: YLO,YUP

DISCUSSION:

If an observation is assumed to be normally distributed, with mean and variance specified for NONMEM as usual, then the likelihood for the observation is conditioned on the observation being in (or outside) an interval defined by the values YLO and YUP. If YLO is less than YUP, then the likelihood of the observation is conditioned on the observation being in the interval with lower bound YLO and upper bound YUP. If YLO is greater than YUP, then the likelihood of the observation is conditioned on the observation being outside the interval with lower bound YUP and upper bound YLO. These values may be set with the data record containing the observation. They may be set in $PRED and $ERROR abbreviated codes. If YLO or YUP is not set, it is assumed to be minus infinity or plus infinity, respectively. When YLO or YUP is set, the Laplacian estimation method must be used.

PR_Y is the estimated probability that an observation will fall within (or outside) the interval.

(See pr_y, Section 53.116).

Location prior to NONMEM 7: nmpr12

REFERENCES: None.

116 YLO YUP PROBABILITY: PR_Y

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied routines

USAGE:

USE ROCM_REAL, ONLY: PR_Y

GLOBAL DECLARATION:

USE SIZES, ONLY: DPSIZE
REAL(KIND=DPSIZE) :: PR_Y

DISCUSSION:

When with a given data record, either of the limits YLO or YUP are set so that during the analysis an interval is defined in which (or outside of which) an observation is conditioned to exist, then during a copying pass (and during ICALL=5 and 6), PR_Y is the estimated probability that an observation will fall within (or outside) the interval.

(See Section 53.115). (See Section 53.22, expectation). (See data average).

For the purpose of computing this probability, an actual observation need not exist in the record. If the mean and variance of the intra-individual model for a potential observation are specified, and if the limits YLO or YUP are set, a value of PR_Y will be computed, whether the record has MDV=0 or MDV=1. If neither YLO nor YUP are set, the value PR_Y will be 1.

PR_Y may be used as a right-hand quantity in abbreviated code for $PRED, $PK, $ERROR, and $INFN blocks.

Location prior to NONMEM 7: rocm44

REFERENCES: None.

1 ABBREVIATED CODE

2 ABBREVIATED FUNCTION

3 ACTIVE ETA LIST FOR PREDPP

4 ADDITIONAL_RECORD_COUNTERS

5 ADVAN7: FACTOR

6 AES

7 BIOAVAILABILITY BEHAVIOR

8 CALLFL

9 CALLING PROTOCOL PHRASE

10 CCONTR: F, G, H

11 CCONTR: Y, DATA, N1, N2, DIM

12 COM COMACT COMSAV COMRES

13 COMACT, COMSAV

14 COMPARTMENT INITIALIZATION BLOCK

15 COMPARTMENT INITIALIZATION: A_0

16 COMPARTMENT INITIALIZATION: A_0FLG

17 COMPARTMENT UPDATE BLOCK (NM75)

18 CONTR: F, G, H

19 CONTR: III, DIM

20 CONTR: KCALL

21 CONTR: Y DATA NOBS

22 COPYING BLOCK

23 CORRELATION ACROSS L2 RECORDS

24 CSVALIGN

25 CTLO

26 CTLO CTUP PROBABILITY: PR_CT

27 CTUP

28 DES

29 DES AES: ICALL, IDEFD, IDEFA

30 DES AES: ISFINL

31 DES AES: THETA

32 DIFF EQ SOLVER SETTINGS

33 DOSE RECORD: DOSREC

34 DOSE TIME NON-EVENT: DOSTIM

35 DOWHILE BLOCK

36 ERROR

37 ESTIM COVAR ERROR CODES

38 ETASXI

39 EVENT RECORD: EVTREC

40 EXPECTATION BLOCK

41 F_FLAG

42 ICALL

43 INDICATOR VARIABLES

44 INFN-DEFINED VARIABLES

45 INITIAL STEADY STATE: I SS, ISSMOD

46 INITIALIZATION-FINALIZATION BLOCK

47 MDVRES

48 MIX CONTR: TEMPLT

49 MIX CONTR: THETA

50 MIX: DATA

51 MIXNUM_MIXEST_MIXP

52 MIXTURE MODEL: MIXNUM, MIXEST

53 MIXTURE MODEL: MIXP

54 MIXTURE MODEL: MIXPT

55 MODEL

56 MODEL EVENT TIME: MNOW, MPAST, MNEXT

57 MODEL EVENT TIME: MTDIFF

58 MODEL EVENT TIME: MTIME

59 MTIME MNEXT MPAST MNOW MTDIFF

60 MU_MODEL

61 MXSTEP

62 NEW INDIVIDUAL INDICATOR: NEWIND

63 NINDR INDR1 INDR2

64 NON-ACTIVE ETA LIST FOR PRED

65 NONMEM MODULES

66 NONPARAMETRIC DENSITY: DEN_, CDEN_

67 NPD, NPDE, NPDE_MODE, DV_LOQ, CDF_L, DV_LAQ, CDF_LA

68 OBJECTIVE FUNCTION VALUE

69 OBJECTIVE FUNCTION VALUE INDIVIDUAL

70 PARAMETER DIMENSIONS

71 PARAMETER VALUES: INITIAL AND FINAL

72 PARAMETERS OMEGA SIGMA: CURRENT

73 PARTIAL DERIVATIVE INDICATORS

74 PASS NEW L2 RECORD: NEWL2

75 PASS NEWIND: NWIND

76 PASS: PASSRC

77 PK

78 POPULATION SINGLE-SUBJECT INDICATOR

79 PRED

80 PRED ERROR MESSAGE

42 `ICALL`

44 `INFN`-DEFINED VARIABLES

62 NEW INDIVIDUAL INDICATOR: `NEWIND`

64 NON-ACTIVE ETA LIST FOR `PRED`

75 PASS `NEWIND`: NWIND

84 `PRED`-DEFINED VARIABLES

93 RECURSIVE `PRED` INDICATOR

99 SIMULATION: NREP, `IREP`