131  Fortran / PRED State Variables

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

131.1 PASTZERO (NM75)

MEANING: PREDPP-PK global variables

CONTEXT: User-supplied routines

USAGE:

USE PRDDESLVU, ONLY: PASTZERO

GLOBAL DECLARATION:

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

DISCUSSION:

This variable is reserved with ADVAN18, for use with Delay Differential Equations. Sometimes you may wish to have the equations transition from the past to the present other than at time T=0. In this case, set PASTZERO to a non-zero (including negative) value. For example,

$DES PASTZERO=-10.0

REFERENCES: Guide Introduction_7

131.2 PASTZERO (NM75)

MEANING: PREDPP-PK global variables

CONTEXT: User-supplied routines

USAGE:

USE PRRADAR5U, ONLY: PASTZERO

GLOBAL DECLARATION:

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

DISCUSSION:

This variable is reserved with ADVAN16 and ADVAN17, for use with Delay Differential Equations. Sometimes you may wish to have the equations transition from the past to the present other than at time T=0. In this case, set PASTZERO to a non-zero (including negative) value. For example,

$DES PASTZERO=-10.0

REFERENCES: Guide Introduction_7

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

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 $abbreviated). 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 eta 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 funcions should be used instead in the PK routine, and model event time (MTIME) parameters be used to set flags for DES. (See Model Time examples) (See Cirdadian example) 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 SIZES).

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

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 - in the same way as any previously defined variable - 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 Repetition Variables); SKIP_ (but only in a finalization block) - with superproblems or subproblems (See SKIP).

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., and .OR.. The arthmetic operators may be coded as ==, /=, <=, >=, <, and >, 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. Special rules apply. For more detail, see SPECIAL STATEMENTS (below), and help entries for these records.

A condition may also test certain variables defined in modules (See Variables_in_modules, NONMEM_modules, PREDPP_modules).

Abbreviated code in a particular THEN or ELSE clause may not contain multiple definitions of the same random variable. The code below is invalid: IF (condition) THEN X=…an expression involving a random variable X= …. ENDIF

Random variables cannot be defined within nested conditionals, i.e., within a conditional structure beginning with an IF and containing another IF. 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. Consider two cases in which the following statements are the only ones defining TVK and K, respectively: IF (WT.GT.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.GT.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.GT.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. The first example works with a single bolus dose and the second example works with single or multiple bolus doses. Similar code can be used in $PK and $ERROR.

K=THETA(1)*EXP(ETA(1))
IF (TIME.EQ.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.EQ.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 Simulation block). (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 write print).

SPECIAL STATEMENTS

Optional. Each of these special statements is permitted in special blocks of abbreviated code. (See Initialization-Finalization block, Simulation block). (See Expectation block, 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. If present, R becomes a reserved variable with type REAL, and may not be used outside the block(s).

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).GT.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 Initialization-Finalization block).

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

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 AZ, 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 $abbreviated). (See abbreviated function).

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 pseudostatement 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 pseudoassignment 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 inter-nal use by NM-TRAN: Names of modules and of variables in the modules (See Variables_in_modules). 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 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 non-mem_reserved file, and remembers the variables declared in there as acceptable to use.

A list of useful variables and their meanings are listed in .._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 ..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 inter-est.

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

131.4 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 abbreviated code). 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 Partial Derivative Indicators). 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 $ABBREVIATED).
(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

131.5 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 variables in modules) In particular, (See DES AES: ICALL,IDEFD,IDEFA)

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

131.6 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:

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
or
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+FERR(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

131.7 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 pseudostatement 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

or 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

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

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 copying_block). 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 COMACT,COMSAV)

(See PRED-Defined Variables) (See abbreviated, abbreviated_code, displayed_values).

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

131.9 COMPARTMENT INITIALIZATION BLOCK

MEANING: Abbreviated code for compartment initialization

CONTEXT:

$PK abbreviated code

SAMPLE:

$PK
IF (A_0FLG.EQ.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.

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

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

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

4) An IF statement testing ICALL and A_0FLG together is not permit-

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

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

6) User-defined variables may be defined in compartment initializa-

tion blocks, but not reserved variables such as basic or additional PK parameters.

EXAMPLES OF USAGE:

The following two fragments of code yield identical results:

1. Explicit compartment initialization block:

IF (A_0FLG.EQ.1) THEN
 A_0(1)=THETA(1)*(1+ETA(1))
ENDIF

2. Implicit compartment initialization block:

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

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

IF (A_0FLG.EQ.1) THEN

IF (X.EQ.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))

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

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

Instead, use:

IF (ICALL.EQ.4) THEN

IF (A_0FLG.EQ.1) A_0(1)=THETA(1)*(1+ETA(1))
ENDIF

or simply

IF (ICALL.EQ.4) THEN

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

or even more simply

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

(See Compartment Initialization: A_0) (See Compartment Initialization: A_0FLG) (See pk).

REFERENCES: None

131.10 COMPARTMENT UPDATE BLOCK (NM75)

MEANING: Abbreviated code for compartment update

CONTEXT:

$PK abbreviated code

SAMPLE:

$PK
IF (A_UFLG.EQ.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 (.._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

131.11 COPYING BLOCK

MEANING: Abbreviated code especially for copying pass

CONTEXT:

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

SAMPLE:

IF (COMACT.EQ.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 comsav). 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.EQ.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 COMACT,COMSAV)

(See PRED-Defined Variables). (See abbreviated).

REFERENCES: None

131.12 DATA_AVERAGE BLOCK

MEANING: Abbreviated code for computation of raw-data-averages

CONTEXT: Abbreviated code

SAMPLE:

 $ERROR
IF (ICALL.EQ.6) THEN

… data average block … ENDIF

DISCUSSION:

A data average block is a block of abbreviated code that is only executed when ICALL=6. This value of ICALL occurs when the raw-data-average (RAW_) data item is defined in the data set and has a non-zero value for some records. Data average blocks are not required when the raw-data-average data item is present, but they allow the user additional functionality. Such blocks may be present in $PRED and $ERROR. If for a given observation record matching a template record, a data average block sets the DV variable to a value different from the one in the record, this value is the one included in the average.

In this example, the displayed DV value for each template record is the proportion of DV items greater than 10 on those records matching the template record.

Y=...
TRDV=DV

IF (ICALL.EQ.6) THEN

DV=0
IF (TRDV.GT.10) DV=1
ENDIF

PRED may return a value of 1 in F, indicating that the DV item in the record is not to be included in the average. Continuing the above example, suppose that the DV variable is set to a value only when it exceeds 2, so that the average is the proportion of observations exceeding 10 among those that exceed 2. The code is as follows. See note 2 below on the returned value of F.

Y=...
TRDV=DV

IF (ICALL.EQ.6) THEN

IF (TRDV.LE.2) Y=1
DV=0
IF (TRDV.GT.10) DV=1
ENDIF

When ICALL=6, PRED and ERROR are called with successive records as usual. However, with each observation record, all output from these routines other than a value set for the DV data item and values set for PRED-defined (ERROR-defined) items V used in a table or scatterplot and located in the SAVE region (See save_region (and the F value, in so far as it is or is not 1) is ignored. In the same way that an average is formed for the DV, averages are formed for the elements of V. Upon entry into PRED or ERROR with a given record, the value of the DV item is the one on the record, and the values for V are the values that will be used in a table and/or scatterplot. If PRED or ERROR changes one of these values, the new value is the one used in the average. If a value is not changed, the unchanged value is used in the average. (For a nonobservation record, the output from that record is completely ignored.)

The following series of examples concern taking averages of PRED-defined items. They involve a mixture model, where, under each of the subpopulations, there is a parameter PA whose value depends on an eta. There is a template record.

Example A.

Suppose first that PA does not depend on (interindividually-varying) covariate values. Suppose moreover, that during copying passes, with each individual record a value of the quantity Q=P1PA1+P2PA2+P3*PA3 has been computed and stored in the SAVE region. Here, the P’s are the mixture probabilities, and the PA’s are conditional estimates of PA under the different models for the different subpopulations. Due to the presence of the template record, at ICALL=6, the average of Q across the eta estimates (from individuals with the same covariate values as are contained in the template record) will be computed - without any need for a data average block. More precisely, at ICALL=6 a pass through the data set occurs, during which a value of Q is obtained with each of the observation records that match the template record. However, the average of the Q values is an average of withinindividual averages, and since Q does not vary within an individual record, the within-individual average computed for that record is the same value of Q as is obtained with each of the observation records of the individual record (matching the template record). The resulting average of the Q values is an estimate of the expected value of PA over the subpopulations and the randomly-varying PA’s.

Example B.

Suppose that PA depends on a covariate X E.g. PA=THETA(1)*X**THETA(2)*EXP(ETA(1)), and that one is interested in an estimate of the expected value of PA for X=x. Suppose also that the value for X in the template record is x. Once again, suppose that during copying passes, with each individual record a value of Q has been computed and stored in the SAVE region - using whatever value of X appears in the individual record. At ICALL=6, if and only if the observation records within an individual record have the value X=x and match the template record with respect to the other relevant data items, will the within-individual average be included in the average Q. Moreover, these observation records are the very ones whose value for Q is of interest.

Example C.

However, under a well-specifed model, ETA(1) should be independent of X, and so one might want to use an average of Q across the eta estimates from all individuals (with observation records). Then one might (i) during copying passes, for each individual record compute Q using the specific value X=x - regardless of what value of X appears in the individual record, and (ii) include the record

$OMIT X

to prevent the values of X from affecting the match with the template record.

Example D.

The strategy in example C fails if it is necessary to match on X for the purpose of forming averages other than the average Q, and it is at least awkward if one is interested in the expected value of PA for a variety of values of X. Here is an alternative strategy.

$ABB COMRES=4 COMSAV=4
$ERROR

… Y=…

IF (COMACT.EQ.2) THEN

IF (MIXNUM.EQ.1) COM(1)=ETA(1)
IF (MIXNUM.EQ.2) COM(2)=ETA(2)
IF (MIXNUM.EQ.3) COM(3)=ETA(3)
ENDIF

IF (ICALL.EQ.6) THEN

PA1=THETA(1)*TEMPLT(X)**THETA(2)*EXP(COM(1))
PA2=THETA(1)*TEMPLT(X)**THETA(2)*EXP(COM(2))
PA3=THETA(1)*TEMPLT(X)**THETA(2)*EXP(COM(3))
COM(4)=MIXP(1)*PA1+MIXP(2)*PA2+MIXP(3)*PA3
ENDIF

$TABLE COM(1) COM(2) COM(3) NOPRINT FILE=junk $TABLE ID … COM(4) …

During the copying passes, the values of the eta estimates are stored (in items COM(1), COM(2) and COM(3) of the SAVE region) rather than the value of Q. The first table record appears because unless the items COM(1), COM(2), and COM(3) are displayed, at ICALL=6 their values are 0. TEMPLT(X) refers generically to the value of X on the template record (see Special Rule 4 below); so there can be numerous template records with different values of X.

Example E.

Examples A-C are not explicit about how the mixture probabilities are computed. They might be obtained via MIXP, in which case during the copying passes (similar to what happens at ICALL=6 with example D), with a given individual record, they are the probabilities pertaining to that record. As long as the mixture probabilities do not depend on interindividual-varying covariates, the mixture probabilities are the same no matter what individual record it is to which they pertain. But if the probabilities depend on interindividual-varying covariates, and especially if one wants to estimate the expected value of Q for numerous different sets of values for these covariates, then one might use:

$ERROR

include nonmem_reserved_general Y=…

IF (COMACT.EQ.2) THEN

IF (MIXNUM.EQ.1) COM(1)=ETA(1)
IF (MIXNUM.EQ.2) COM(2)=ETA(2)
IF (MIXNUM.EQ.3) COM(3)=ETA(3)
ENDIF

IF (ICALL.EQ.6) THEN

PA1=THETA(1)*TEMPLT(X)**THETA(2)*EXP(COM(1))
PA2=THETA(1)*TEMPLT(X)**THETA(2)*EXP(COM(2))
PA3=THETA(1)*TEMPLT(X)**THETA(2)*EXP(COM(3))
COM(4)=MIXPT(1)*PA1+MIXPT(2)*PA2+MIXPT(3)*PA3
ENDIF

The mixture probabilities found in MIXPT pertain to the individual record containing the template record (see Special Rule 7 below). Because they have been computed using the covariate values in that record, they are commensurate with the way PA has been computed for the different subpopulations. With versions prior to NONMEM 7.3, the probabilities in MIXPT must be referenced via verbatim code (note the double quotes).

$ERROR
" USE ROCM_REAL MIXPT=>MIXP_RAW

… ” COM(4)=MIXPT(1)PA1+MIXPT(2)PA2+MIXPT(3)*PA3

Special rules apply to data average blocks and passes through the data with ICALL=6.

1. No eta derivatives are computed in a data average block.

2. A RETURN statement may be used in a data average block. If Y=

: appears (i.e. Y is assigned a value) in a data average block before the RETURN (not necessarily in the same block containing the RETURN), then F is set to Y (F=Y); otherwise F is set to to 0 (F=0). If there is no RETURN statement in a data average block, then as usual, F is set to the value of Y assigned by the time PRED (ERROR) exits.

3. Loops are permitted in a data average block. The syntax is as

: follows.

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

4. During calls with ICALL=6, the template data record is found in

: NONMEM global variable TEMPLT. Items in the template data record may be referred to in abbreviated code of the data average block by position or by label, e.g., TEMPLT(1) or TEMPLT(ID).

5. During calls with ICALL=6, the repetition feature may not be

: used.

6. If a mixture model is used, then during calls with ICALL=6, both

: MIXNUM and MIXEST are the index of the subpopulation into which the individual (whose data record is being passed) has been classified.

7. If a mixture model is being used, then during calls with ICALL=6,

: (the final estimates of) the mixture probabilities associated with the individual record containing the template record are found in NONMEM global variable MIXPT. Code that uses these probabilities must be verbatim code.

(See raw_). (See MIX CONTR: TEMPLT) (See Mixture model: MIXPT).

REFERENCES: None

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

Input argument:

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

P(n) The value of the nth PK parameter.

T Time. T takes values continuously over an integration interval.

Output argument:

DADT(n)

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)

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)

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)

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 variables in modules) In particular, (See DES AES: ICALL,IDEFD,IDEFA)

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

131.14 DOWHILE BLOCK

MEANING: Coding technique

CONTEXT: Abbreviated code

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: (1) It is declared as such, e.g. $ABBR DECLARE DOWHILE ILOOP (2) It is given a value in the statement immediately before DOWHILE (3) 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 abbreviated code).

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
DO WHILE(ILOOP<=IMAX)
IF (ILOOP == 1) THEN
SUM=0                  ; initialization within the loop

ELSE ; else statement 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.

EXAMPLE:

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

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

Input argument:

ICALL

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; multi-ple 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 rawdata (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

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 INDXS array starting at position 12, the first position beyond those positions used by PREDPP itself.)

Output argument:

IDEF

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.

Input/Output argument:

F 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 $estimation).

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

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

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

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

131.17 EXPECTATION BLOCK

MEANING: Abbreviated code for computation of expectations

CONTEXT: Abbreviated code

SAMPLE:

$ERROR
IF (ICALL.EQ.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.EQ.5) THEN

Y=0
IF (F.GT.10) Y=1
RETURN
ENDIF

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

1. No eta derivatives are computed in an expectation block.

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

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

4. Loops are permitted in an expectation block. The syntax is as

: follows.

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

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

131.18 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 begin-

ning of the NONMEM run; one such call per run.

ICALL=1: the routine has been called for initialization at the  begin-

ning 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; mul-

tiple calls occur, as with ICALL=2.

ICALL=5: the routine has been called when expectations are being  com-

puted; 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; Guide IV, section IV.D , IV.E.1; Guide VI, section III.C , IV.B.1

131.19 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.EQ.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)+ICUETA(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.EQ.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.EQ.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.EQ.1) Q1=1
 IF (TYPE.EQ.2) Q2=1
 Y=Q1*Y1+Q2*Y2

REFERENCES: Guide V, section 7.5.3 , 7.5.4 , 12.5

131.20 INFN

MEANING:

INFN subroutine

CONTEXT: User-supplied subroutine; replaces a PREDPP dummy routine.

USAGE:

SUBROUTINE INFN (ICALL,THETA,DATREC,INDXS,NEWIND)
USE SIZES, ONLY: ISIZE,DPSIZE
USE NMPRD_INT, ONLY: NWIND
INTEGER(KIND=ISIZE) :: ICALL,INDXS(*),NEWIND
REAL(KIND=DPSIZE)   :: THETA(*),DATREC(*)

DISCUSSION:

A run consists of one or more problems, and each problem consists of one or more subproblems. With NONMEM 75, there is an opportunity to drop data records from the NONMEM data set at the start of the run, using the PRED_IGNORE_DATA feature. There are opportunities to make some rudimentary computations at the beginning of a run (run initialization), at the beginning of a problem (problem initialization), at the end of a subproblem (subproblem finalization), at the end of a problem (problem finalization), and at the end of a run (run finalization). For example, at problem initialization, data transgeneration may take place, or a variable that will be modified at subproblem finalization, may be initialized. At problem finalization, the value of this variable may be written to a user file. There is no opportunity to do subproblem initialization.

The INFN subroutine is called by PREDPP to make initialization and finalization computations. The version distributed with PREDPP is a “stub” or “dummy” routine that does nothing. It may be replaced by a user-written code.

Input/Output argument:

ICALL
ICALL=-1: INFN may  set  PRED_IGNORE_DATA=1  for  records  to  be

dropped. The following is required: USE NMPRD_INT, ONLY: PRED_IGNORE_DATA,PRED_IGNORE_DATA_TEST The option $DATA … PRED_IGNORE_DATA is required to cause NONMEM to make a PRED_IGNORE_DATA pass.

ICALL=0: INFN may now make computations for  run  initialization.

ICALL may be reset by INFN to a number in the range 1-8999. This number will appear on NONMEM output, allowing the user to identify the INFN routine being used.

ICALL=1:  INFN  may now make computations for problem initializa-

tion.

ICALL=3: INFN may now make computations for subproblem  finaliza-

tion.

ICALL=3: INFN may now make computations for problem finalization.

If there are subproblems, first do subproblem finalization, if required. Then test for IREP=NREP (the number of the current subproblem equals the total number of subproblems), and if true, do problem finalization. Values of IREP and NREP may be found in NONMEM modules (See Simulation: NREP,IREP).

ICALL=3: INFN may now make  computations  for  run  finalization.

First do problem finalization, if required. Then test for IPROB=NPROB (the number of the current problem equals the total number of problems), and if true, do run finalization. Values of IPROB and NPROB may be found in NONMEM modules (See Problem_Iteration_Counters).

Input arguments:

DATREC

DATREC contains the first data record of the current problem. (At ICALL=0, the current problem is the first problem.) Using PASS (see below), the contents of DATREC are replaced by other data records for the current problem, allowing all these other records to be read and even modified.

THETA

The NONMEM THETA vector. 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.

INDXS

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

NWIND

NWIND has value 0 when INFN is called.  It changes value during a
pass through the data using PASS (see below).
NWIND=0: First record of the data set.
NWIND=1: First record of a subsequent individual record.
NWIND=2: Subsequent data record of an individual record.

EXAMPLES OF USAGE:

Initialization

Constants in the PK routine can be set if they are stored in a module or common block declared both in INFN and PK.

Transgeneration

The data can be accessed and even modified via use of the NONMEM utility routine PASS in routine INFN (See pass). As the data records are passed one-by-one to INFN, each record is stored in turn in DATREC. Data can be transgenerated and additional data items can be produced at both initialization and finalization. Data items that appear in a table or scatterplot with a given subproblem or problem are produced or left unchanged at the subproblem or problem finalization. At finalization estimates of the eta’s can be obtained via the NONMEM utility routine GETETA. When used in conjunction with PASS, the values returned for the eta’s with each call to GETETA are appropriate for the individual whose data record is currently in DATREC.

Interpolation

As an example of transgeneration, interpolated values of a covariate can be computed for event records in which values are missing, e.g. for other-type event records that have been included so that predictions can be obtained at the times in these records. This could also be done in PK or ERROR, but then this would be done with every call to these routines; if done in INFN, the computation is done once only.

(See Infn interpolation example).

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

131.21 INITIALIZATION-FINALIZATION BLOCK

MEANING: Abbreviated code for initialization and finalization

CONTEXT:

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

SAMPLE:

$PRED

IF (ICALL.EQ.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 (i) S1IT (number of current superproblem iteration) equals 1 (or S2IT=1), (ii) S1NUM (number of current superproblem) equals appropriate value, and (iii) IPROB (number of current problem) equals number of first problem in superproblem, and if (i)-(iii) are true, do superproblem initialization (See Problem_Iteration_Counters).

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 Simulation: NREP,IREP). If a superproblem requires finalization, test (i) S1IT=S1NIT (number of the current superproblem iteration equals total number of superproblem iterations) (or S2IT=S2NIT), (ii) S1NUM (number of current superproblem) equals appropriate value, (iii) IPROB (number of current problem) equals number of last problem in the superproblem, and (iv) 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 (i) S1IT=S1NIT (or S2IT=S2NIT), if there are superproblems (ii) S1NUM equals number of last superproblem, if there are superproblems, (iii) IPROB=NPROB (number of the current problem equals total number of problems), and (iv) 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.EQ.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 supp). 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 PASS: PASSRC). NEWIND (See PASS NEWIND: NWIND). NIREC, NDREC (See Record Counters: NIREC,NDREC). NEWL2 (See PASS New L2 record: NEWL2). ETA when ICALL=3 (See Simulation: ETA,EPS) LIREC (See Size of Individual Record) PRED_, RES_, WRES_ when ICALL=3 (See PRED,RES,WRES). IERE, IERC when ICALL=3 (See Estim Covar Error Codes). NINDR, INDR1, INDR2 (See NINDR INDR1 INDR2). NREP, IREP (See Simulation: NREP,IREP). NPROB, IPROB, S1NUM, S2NUM, S1NIT, S2NIT, S1IT, S2IT (See Problem_Iteration_Counters).

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.EQ.0) THEN
     MODE=0
     CALL PASS (MODE)
     MODE=2
     CALL PASS (MODE)
     DO WHILE (MODE.EQ.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.EQ.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.EQ.1) THEN
   SUM=0
   N=0
   RETURN
ENDIF
IF (ICALL.EQ.3) THEN
  N=N+1
  SUM=SUM+THETA(1)
  RETURN
ENDIF
IF (ICALL.EQ.3.AND.N.EQ.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 Parameter Values: Initial and Final). (See write print).

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 Standard Errors). (See Objective Function Value). (See write print).

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

(See abbreviated).

REFERENCES: Guide II, section D.2.2; Guide VI, section VI.A , Figure 37

131.22 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 .EQ. 1) THEN

F_FLAG = 0
Y = IPRED + SD * ERR(1)
ENDIF

IF (TYPE .EQ. 2) THEN

F_FLAG = 1
Y = CUMD
MDVRES=1
ENDIF

REFERENCES: Guide Introduction_7

131.23 MIXNUM_MIXEST_MIXP

MEANING: Variables used with mixture models

CONTEXT: Abbreviated code and user-supplied subroutines

USAGE:

IF (MIXNUM.EQ.1) THEN
  ...
ENDIF
IF (MIXNUM.EQ.2) THEN
  ...
ENDIF
IF (MIXNUM.EQ.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,MIXEST) (See Mixture_model:_MIXP) (See mix, mixture model example).

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

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

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

REFERENCES: Guide IV, section V.C.4; Guide VI, section VI.B , Figures 28, 29, 43; Guide VI, Appendix II

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

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 sizes). 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 model time examples) (See Model Event Time: MNOW,MPAST,MNEXT) (See Model Event Time: MTIME) (See Model Event Time: MTDIFF) (See Circadian Example: Examples Using MTIME to Model Periodic Discontinuities in $DES)

REFERENCES: Guide VI, section III.F.9

131.26 MU_MODEL

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 reparameterized 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 MUTHETA 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:

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

2. Whenever possible, have the MU variables defined unconditionally,

: outside IF…THEN blocks.

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

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

.._sim.ctl ..6.ctl: ..7.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

131.27 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,ADVAN18)

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, soMXSTEP` 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

131.28 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 non-negative, 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

131.29 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

131.30 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, YLO_YUP_Probability:_PR_Y).

Location prior to NONMEM 7: nmpr12

REFERENCES: None

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

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

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

Location prior to NONMEM 7: nmpr13

REFERENCES: None

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

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

131.33 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

131.34 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 nwpri, tnpri).

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

131.35 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.EQ.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 Correlation Across L2 Records)

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 multi-ple-observation L1 record.

Location prior to NONMEM 7: nmpr17

REFERENCES: None

131.36 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

131.37 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:

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 PRED Error Message).

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 Simuation Step. For NONMEM 7.5 use of the error code during simulation, (See Simulation Block) 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

131.38 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 PRED Exit Code)

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

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

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

131.40 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 $table, $scatter). Values are stored by PRED and by subroutines of PREDPP. A SAVE region of NMPRD4 may be designated; (See COMACT,COMSAV).

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

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

131.41 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.NE.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:

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. See help for that version of NONMEM.

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

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 Simulation:_SIMEPS_Error_Code)

Location prior to NONMEM 7: nmprd5

REFERENCES: None

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

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

131.43 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

131.44 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

131.45 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

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

1. 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 epsilon’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.

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

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

131.47 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 .EQ. 1.OR.NPDE_MODE.EQ.1) THEN

F_FLAG = 0
Y = IPRED + SD * ERR(1)
ENDIF

IF (TYPE .EQ. 2.AND.NPDE_MODE.EQ.0) THEN

F_FLAG = 1
Y = CUMD
MDVRES=1
ENDIF

IF(TYPE.EQ.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

131.48 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 higer:

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

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,ISSMOD) (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 State Vector: A). 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 maxi-

mum number of rows in GG is given by IRGG, which is the same as constant PG found in file SIZES (See sizes). 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 variables in modules)

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

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

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 non-active eta list for pred).

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.

1. call DVERK to obtain 2nd derivatives 1,1 2) call DVERK to obtain 2nd derivatives 1,2 and 2,2 3) 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*PE*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.

132 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*(1+PE+PE*(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 (2PEPM+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

132.1 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

132.2 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. (Nonreal 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

132.3 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:

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 DES_AES:_THETA). When IDEFD(1) is set by DES to -9, PREDPP copies all thetas in the problem to THETAS (See DES AES: THETA). 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

132.4 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, model time examples).

Location prior to NONMEM 7: prdpk1

REFERENCES: None

132.5 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, model time examples).

Location prior to NONMEM 7: prdpk2

REFERENCES: None

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

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 State Vector: A).

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, State Vector: A).

Location prior to NONMEM 7: prdpk3

REFERENCES: None

132.7 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.EQ.1) THEN
I_SS=1
ELSE
I_SS=0
ENDIF

(See $model, $pk, model, pk).

Location prior to NONMEM 7: prdpk4

REFERENCES: None

132.8 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   fea-

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

Also see variables in NONMEM modules, NONMEM-PRED modules, and PREDPP modules. (See variables in modules)

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

132.9 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 NONMEN 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

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

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

132.11 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 PRED-defined_variables).

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

erated 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

132.12 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

132.13 HINIT_,HMIN_,HMAX_ (NM760)

MEANING: PREDPP-PK global variables

CONTEXT: User-supplied routines

USAGE:

USE PRLS01_REAL, ONLY: HINIT_,HMIN_,HMAX_

GLOBAL DECLARATION:

USE SIZES, ONLY: DPSIZE REAL (KIND=DPSIZE) HINIT_,HMIN_,HMAX_

DISCUSSION:

These reserved variables are used to modify the integration step size behavior in ADVAN9, ADVAN13, ADVAN14, and ADVAN15. When a modeled short, large rate input occurs at some time during the simulation, that is not a scheduled bolus event or is not easily specified with MTIME(), the LSODA type ODE solvers can miss this event. For example, a gamma function shaped input with a large N>20 parameter, can create a stiff, pseudo-bolus input that may be missed by one of these ADVANs. One way to avoid missing this input is to set the integration step size to an upper limit:

$PK HMAX_=0.01

One may also set the initial step size (HINIT_), or minimal step size (HMIN_) within the $PK block in a similar manner.

The usual technique for handling short-term rate inputs is to set the RTOL and ATOL to very high levels, such as between 13 and 15, but this may not work for every problem, and one may need to resort to explicitly limiting the HMAX_ or HINIT_ in the manner shown above.

For a discussion of these variables, See INTRODUCTION TO NONMEM 7, “HMIN_, HINIT_,HMAX_: Avoiding missed short events in ADVAN9, ADVAN13, ADVAN14, and ADVAN15 (nm760)”

REFERENCES: Guide Introduction_7

132.14 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 ..`DISTRIB.f90,DISTRIBCDF.f90, andDISTRIBRNG.f90. Note that multi-variate densities do not have a correspondingCDF` routine.

Examples of their use are in the ..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

132.15 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 Recursive PRED Indicator), 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

132.16 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:

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 Dose Record: DOSREC).

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

Location prior to NONMEM 7: procm2

REFERENCES: Guide VI, section III.I

132.17 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 Dose Time Non-Event: DOSTIM).

Location prior to NONMEM 7: procm3

REFERENCES: Guide VI, section III.I

132.18 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 State_Vector_TIME:_TSTATE).

Location prior to NONMEM 7: procm4

REFERENCES: Guide VI, section IV.D , Figure 14

132.19 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 Non-Active_ETA_list_for_PRED). 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

132.20 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 DES_AES:_ICALL,IDEFD,IDEFA)

Location prior to NONMEM 7: procm6

REFERENCES: None

132.21 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:

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

132.22 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:

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

132.23 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 State Vector: A) 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

132.24 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

132.25 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

132.26 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, State Vector: A).

Location prior to NONMEM 7: procmc

REFERENCES: None

132.27 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 ..`PROTECT.f90. If you wish to modify their behavior, then copyPROTECT.f90to 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 intputs.

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

132.28 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; Guide V, section 8; Guide VII, section I , III

132.29 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

132.30 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

132.31 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,DATA,N1,N2,DIM)

Location prior to NONMEM 7: rocm1

REFERENCES: Guide IV, section III.B.4

132.32 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

132.33 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 MIXNUM_MIXEST_MIXP)

(See Mixture_model:_MIXP, mix) (See mixture_model_example)

Location prior to NONMEM 7: rocm11

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

132.34 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 a 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 Abbreviated)

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

132.35 CONTR: KCALL

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

132.36 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 $super).

Location prior to NONMEM 7: rocm14

REFERENCES: None

132.37 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

132.38 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

132.39 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

132.40 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

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

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

132.42 CONTR: III,DIM

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

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

132.43 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 Parameter dimensions).

At run and problem initialization and at problem finalization use the variables OMEGAF and SIGMAF. (See Parameter values: Initial and Final).

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.GE.1) THEN

STD=SQRT(SIGMA(1)+F**2*SIGMA(2))
IWRES=(DV-F)/STD
ENDIF

Location prior to NONMEM 7: rocm22

REFERENCES: None

132.44 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 MIXNUM_MIXEST_MIXP)

(See mixnum_mixest_for_mixture_model) (See mix, mixture model example)

Location prior to NONMEM 7: rocm25

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

132.45 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 $super).

Location prior to NONMEM 7: rocm28

REFERENCES: None

132.46 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

132.47 CONTR: 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=>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.

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 2 3 4 5 6 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: 1 3 5 2 4 6 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

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

132.49 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

132.50 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 pred, newind).

Location prior to NONMEM 7: rocm34

REFERENCES: Guide I, section C.3.5.2

132.51 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

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

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:  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 Correlation_Across_L2_Records)

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

132.53 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 YLO YUP) (See copying_block, 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

132.54 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 CTLO, CTUP) (See copying_block, 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

132.55 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

132.56 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

132.57 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

132.58 PRED,RES,WRES

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied PRED and INFN routines

USAGE:

     USE ROCM_REAL, ONLY:                                             &
        PRED_=>APPND(001),RES_=>APPND(002),WRES_=>APPND(003)          &
        IWRS_=>APPND(004),IPRD_=>APPND(005),IRS_=>APPND(006)          &
        NPRED_=>APPND(007),NRES_=>APPND(008),NWRES_=>APPND(009)       &
        NIWRES_=>APPND(010),NIPRED_=>APPND(011),NIRES_=>APPND(012)    &
        CPRED_=>APPND(013),CRES_=>APPND(014),CWRES_=>APPND(015)       &
        CIWRES_=>APPND(016),CIPRED_=>APPND(017),CIRES_=>APPND(018)    &
        PREDI_=>APPND(019),RESI_=>APPND(020),WRESI_=>APPND(021)       &
        IWRESI_=>APPND(022),IPREDI_=>APPND(023),IRESI_=>APPND(024)    &
        CPREDI_=>APPND(025),CRESI_=>APPND(026),CWRESI_=>APPND(027)    &
        CIWRESI_=>APPND(028),CIPREDI_=>APPND(029),CIRESI_=>APPND(030) &
        EPRED_=>APPND(031),ERES_=>APPND(032),EWRES_=>APPND(033)       &
        EIWRES_=>APPND(034),EIPRED_=>APPND(035),EIRES_=>APPND(036)    &
        NPDE_=>APPND(037),ECWRES_=>APPND(038),NPD_=>APPND(039)        &
        OBJI_=>APPND(040)

GLOBAL DECLARATION:
     USE SIZES, ONLY: DPSIZE
     REAL(KIND=DPSIZE) :: APPND(MAXXNAME)

DISCUSSION:

The PRED_,RES_,WRES_ items are the same as PRED, RES and WRES items.

The CPRED_,CRES_,CWRES_ are calculated as if the estimation was performed using a CONDITIONAL method without INTERACTION. (conditional, non-interactive in the manner of Hooker et al.)

The PREDI_,RESI_,WRESI_ are calculated as if the estimation was performed using the FO method with INTERACTION (non-conditional, interactive).

The CPREDI_,CRESI_,CWRESI_ are calculated as if the estimation was performed using a CONDITIONAL method with INTERACTION (conditional, interactive)

EPRED_,ERES_,EWRES_ are Monte-Carlo generated pred, res, and wres values, and are not linearized approximations like the other weighted residual types.

NPDE_ is the normalized prediction distribution error (takes into account within-subject correlations)

NPD_ is the correlated normalized prediction distribution error (does not take into account within-subject correlations)

EWRES_ and NPDE_ and NPD_ are evaluated using predicted function and residual variances evaluated over a Monte Carlo sampled range of etas with population variance Omega.

ECWRES_ is evaluated with only the predicted function evaluated over a Monte Carlo sampled range of etas with population variance Omega, while residual variance is always evaluated at conditional mode or mean. Thus, ECWRES is the Monte Carlo version of CWRES, while EWRES is the Monte Carlo version of CWRESI.

The EPRED_, ERES_, EWRES_, NPD_, NPDE_, ECWRES_ items are calculated by the Table Step. When EPRED_, ERES_, EWRES_, NPD_, NPDE_, ECWRES_ items are displayed, the options ESAMPLE and SEED of the $TABLE record are of interest. (See $table).

The PRED_,RES_,WRES_ (PRED,RES,WRES) items behave as they did with NONMEM VI. Consequently, if FO or a CONDITIONAL method without INTERACTION is used, NPRED_,NRES_,NWRES_ and PRED_,RES_,WRES_ are equivalent. If FO or a CONDITIONAL method with INTERACTION is used, IPRED_,IRES_,IWRES and PRED_,RES_,WRES_ are equivalent.

These items are available with passes through the data set during problem finalization (i.e. ICALL=3), in a data record specific way.

These items may be used as right-hand quantities in $PRED and $INFN during problem finalization. They can also be output in table files by specifying their names (without the underscore) on a $TABLE statement.

(See pred res, wres).

Location prior to NONMEM 7: rocm49

For other variables, see the INTRODUCTION TO NONMEM 7.

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; Guide Introduction_7

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

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 2 3 4 5 6 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: 1 3 5 2 4 6 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

132.60 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.EQ.1) THEN
 COM(1)=IIDX(NIREC)
 COM(2)=CNTID(NIREC)
ENDIF

The following, for example, will produced 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

132.61 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 COMACT,COMSAV)

Location prior to NONMEM 7: rocm6

REFERENCES: None

132.62 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; Guide V, section 5.4.2.1

132.63 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

132.64 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

132.65 SIMULATION BLOCK

MEANING: Abbreviated code for simulation

CONTEXT: Abbreviated code

SAMPLE:

$PK
 IF (ICALL.EQ.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.EQ.4) THEN

… simulation block … ENDIF

Special rules apply to such blocks.

1. No eta derivatives are computed in a simulation block.

2. 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.EQ.4) WT=70+70*ETA(3)

The generated code is:
        IF(ICALL.EQ.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.

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

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

5. 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).GT.5)
CALL SIMETA(ETA)
ENDDO
Another example:
IF (ICALL.EQ.4.AND.NEWIND.NE.2) THEN
  DO WHILE (ETA(1).GT..5.OR.ETA(1).LT.-.5)
    CALL SIMETA(ETA)
  ENDDO
ENDIF
IF (ICALL.EQ.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.EQ.4.AND.NEWIND.NE.2) THEN
  R=1
  DO WHILE (R.GT..5.OR.R.LT.-.5)
    CALL RANDOM(2,R)
  ENDDO
ENDIF
IF (ICALL.EQ.4) WT=70+70*R

This example illustrates how a categorical variable with equallikely 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.EQ.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

6. 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 PRED Exit Code).

(See abbreviated). (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; Guide V, section 12.4.8; Guide VI, section III.E.2 , IV.B.2

132.66 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 $sizes) 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 overridden 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 overridden 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 overridden 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 overridden by user via $SIZES record

LIM15=1000

SIZE OF BUFFER 15: LIM15=NUMBER OF SUBJECTS.  Value may be  overridden 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.^M ! PG:
SIZE OF GG; MAX. NO. OF BASIC+ADDITIONAL PK PARAMS.^M !     (MAX-
IMUM IS PCT+99)^M

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
MAXVRESWRES=39
MAXVRESN=9
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  CON-
CATENATED 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; Guide Introduction_7

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

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; Guide VI, section VI.D , Figure 41; Guide VI, Appendix II

132.68 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 inter-nal 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.

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

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 PRED Exit Code).

(See PRED Error Message).

Variables in read-only commons:

NOETAS, SECOND

(See Partial Derivative Indicators).

When SECOND is true, PREDPP requires second-partial derivatives of etas.

REFERENCES: Guide VI, section III.M

132.69 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_REAL:  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_INT: NINDR,INDR1,INDR2

$ERROR $MIX $PK $PRED $INFN

ROCM_INT: NIREC,NDREC

$DES $AES $ERROR $MIX $PK $PRED $INFN

ROCM_INT: 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
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 ... It needs to be copied from util to the present run directory so that NM-TRAN has access to it.

(See abbreviated code). (See Bayes Example 8).

REFERENCES: Guide Introduction_7

132.70 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.). Lowercase characters can be used freely, if the FORTRAN compiler permits them.

NM-TRAN does make some modifications to verbatim code, as follows:

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

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

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 Objective Function Value Individual). 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