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

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

• NEWIND: Same as the NEWIND argument passed by NONMEM to PREDPP.

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

• NEWL2

  • NEWL2=1: First record of an L2 record.
  • NEWL2=2: Otherwise.

• ICALL

  • ICALL=0: Run initialization.
  • ICALL=1: Problem initialization.
  • ICALL=2: Normal call.
  • ICALL=3: Problem finalization.
  • ICALL=4: Simulation.
  • ICALL=5: Expectation.
  • ICALL=6: Data Average.
  • Special rules apply to blocks of abbreviated code that are executed when ICALL is not 2.

  (See special code blocks).

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

DATREC INDXS G H DADT(n) A(n) E(n) P(n)

When PRED exits with a nonzero PRED error return code, either the NONMEM run is immediately aborted or an error-recovery procedure is implemented. An error-recovery procedure entails continued calls to PRED, but with values for the THETA’s or ETA’s different from those with previous calls which resulted in nonzero return codes. There are two error-recovery procedures: one with which different values for ETA’s are tried, the ETA-recovery , a second with which different values for THETA’s (and possibly ETA’s) are tried, the THETA-recovery . Whenever it is possible to implement the ETA-recovery, this is done. If this procedure fails, or if it is not possible to implement the ETA-recovery, and the error return code is obtained during either the search in the Estimation Step or the search in the Initial Estimation Step, then a choice exists between an abort and implementation of the THETA-recovery. If the THETA- recovery fails, or if it is not actually possible to implement the THETA-recovery, the NONMEM run is aborted.

A PRED error return code can have values 0, 1, or 2. The value 0 means that the return is a normal return. The value 1 means that if the choice exists between an abort or implementation of the THETA-recovery, then this choice is to be made using control stream information. The value 2 means that if the choice exists between an abort or implementation of the THETA-recovery, then the abort should be chosen.

When an abort occurs, an error message will appear in the NONMEM output, in the intermediate output file (if such a file exists), and in the PRED Error file. When the THETA-recovery is implemented, an error message appears in the intermediate output file (if such a file exists), in the PRED Error file, and if recovery is not possible, in the NONMEM output. The error message is called a PRED error message . When the PRED error return code is 1, and a choice exists between implementation of the THETA-recovery and an abort, the THETA-recovery is implemented if the NOABORT option is used on the $ESTIMATION ($THETA) record. If the NOABORT option is not used, then the run is aborted. Often, the most appropriate response to an abort occuring during the Initial Estimate Step, or during the Estimation Step after the 0th iteration summary has been output, is to rerun the problem requesting that the THETA-recovery procedure be implemented. Warning: If the NOABORT option is used before an actual abort has occured, be sure to check the PRED Error file for possibly useful diagnostic information that is otherwise available in NONMEM output when an abort occurs.

The NOABORTFIRST option of $THETA is the same as NOABORT, but also applies to the first value of the theta vector that is tried. With NONMEM 7 and the NOABORT option of $ESTIMATION, NONMEM will force most non-positive Hessian matrices to be positive definite, allowing NONMEM to continue. With NONMEM 72 and option NOHABORT of $ESTIMATION, positive definite corrections are made at all levels of the estimation. But note this can hide a serious ill-posed problem.

An quick exit from PRED with a nonzero return code can be implemented in abbreviated code for PRED (or in abbreviated code for PK, or ERROR, in which case the exit is from PREDPP) with this statement:

1

EXIT n k

Here n is the return code (1 or 2) and k a user code (1-999). If the user code is used, it can be any value the user wishes in the indicated range. In this case a part (shown here) of the PRED error message gives the user code:

1

PRED SUBROUTINE: USER ERROR CODE = k

The user code can be omitted. In that case the return code can also be omitted, and then the return code is 1 by default.

The EXIT statement can be used to reject simulated results and/or simulation error Forgiveness. To have the simulation immediately terminated, one can do

1

IF(ICALL==4.and.IPRED<0.1 .and. TIME>20.0) EXIT 2

Alternatively one may wish to check a prediction and potentially request a new set of ETAs and EPSILONs, by using EXIT 1:

1
2

;# in $ERROR block
IF(ICALL==4.and.IPRED<0.01 .and. TIME>20.0) EXIT 1 2300

Then when the condition evaluated true, NONMEM will try another random ETA and EPS sample.

Note that if you wish to simply create a truncated normal distribution that only requires testing the eta value directly, this can be done with:

1
2
3
4
5

  $P
  ;#...
  DO WHILE (ETA(1).GT.5)
    CALL SIMETA(ETA)
  ENDDO

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

1

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

1
2
3
4
5
6
7
8

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(10) such errors occur in the same subject, NONMEM considers that the cause of the simulation error is not due to an occasional bad random sample but by a systematic error in the control stream. The simulation step is terminated with the message

1

PRED ERROR OCCURRED TOO OFTEN ON SIMULATION

See also PRED EXIT code.