COM, COMACT, COMSAV, and COMRES, these 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".)

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

  1	$TABLE COM(1) COM(2)

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

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: not a copying pass.
• COMACT=1: a copying pass with final THETAs and zero-valued ETAs.
• COMACT=2: a copying pass with final THETAs and conditional estimates of ETAs.
• COMACT=3: a copying pass with conditional (nonparametric) estimates of ETAs.

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

1

  $NONPARAMETRIC ETAS

If a mixture model is used, with each value of MIXNUM there are more than two sets of calls. With ETA=0, there is a set of calls for each distinct value of MIXNUM with COMACT=1. If conditional estimates are used, then with ETA’s set to these estimates, there is a set of calls for each distinct value of MIXNUM with COMACT=2. Note that nonparametric estimates cannot be obtained with a mixture model.

PRED-defined items are stored in variables defined in PRED (PK or ERROR if PREDPP is used). Normally, these items may change from call to call. Therefore if an item is computed at a call with a particular data record (of the individual record) when COMACT=1, it may no longer be available at another call with the same data record when COMACT=2, due to there being (in general) multiple calls to PRED (PK and ERROR) with different data records of the individual record. In order to access an item across the PRED calls, we can put the item in the save region of NONMEM MODULE NMPRD4. All items stored in this region at a call to PRED (PK or ERROR) with a particular data record when COMACT=1 are available at a call with the same data record when COMACT=2. In fact, with mixture models in mind, if at any call to PRED (PK or ERROR) with a particular data record (when COMACT=1 or 2 and MIXNUM has any value), an item is stored in a variable listed in the save region, then the item is available at any subsequent call with the same data record (when COMACT=1 or 2 and MIXNUM has any value). See COMSAV for more about save regions.

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

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

1
2
3
4
5

! USAGE:
  USE NMPRD_INT, ONLY: COMACT,COMSAV

! GLOBAL DECLARATION:
  INTEGER(KIND=ISIZE) :: COMACT,COMSAV

COMRES=n1 (option of $ABBREVIATED): 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): can 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 userwritten PRED routine at ICALL<=1, or at COMACT=1 with the very first data record. n2 is as described above.

(See PRED-Defined Variables, abbreviated code).

1
2
3
4
5
6
7
8

 ! 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

These variables define data items from the $INPUT record that are accessible to subroutine CONTR, CCONTR, and MIX in the DATA array.

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

1
2
3
4
5
6

 ! USAGE:
      USE ROCM_REAL, ONLY PR_CT

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

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, expectation, data average blocks)

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

1
2
3
4
5

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

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: IEST_ERR,ICOV_ERR

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

 ! 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

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 (no index) names that they had in $INFN. Suppose variables X1 and X2 are used in $INFN, and the following is present in the generated INFN routine: X1=>TLCOM(00001); X2=>TLCOM(00002)

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

Prior to the first executable statement, include: X1=>TLCOM(1); X2=>TLCOM(2)

Now the code is X=X1/X2.

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

1
2
3
4
5
6

 ! USAGE:
      USE ROCM_REAL, ONLY: MIXPT=>MIXP_RAW

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

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

1
2
3
4
5
6

 ! USAGE:
      USE ROCM_REAL, ONLY: THETA=>THETAC

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

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

For an example, see the mixture model. In that model, the current value of THETA is loaded from module ROCM_REAL, and same for data items DATA if required.

1
2
3
4
5
6

 ! USAGE:
      USE ROCM_REAL, ONLY: DATA=>RDATA

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

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

1
2
3
4
5

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

 ! GLOBAL DECLARATION:
      REAL(KIND=ISIZE):: NINDOBS,IDXOBSF,IDXOBSL

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

1
2
3
4
5
6

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

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

1
2
3
4
5
6

 ! USAGE:
      USE ROCM_REAL, ONLY: OBJECT

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

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

1
2
3
4
5
6
7
8

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

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.

Namely, 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 accessed with 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).

They may also be displayed in a table, using

1

 $ABBR COMRES=2

in the $ERROR or $PK block:

1
2
3
4

 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:

1

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

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

1
2

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

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

1
2
3
4
5

 ! USAGE:
      USE NMPRD_INT, ONLY: NEWL2

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: NEWL2

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

1
2
3
4
5

 ! USAGE:
      USE NMPRD_INT, ONLY: NWIND

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: NWIND

• NWIND The NEWIND value at ICALL 0, 1 and 3. NWIND changes value in conjunction with calls to PASS. (See PRED, NEWIND).

1
2
3
4
5

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

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: NWTHT,NWETA,NWEPS

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

1
2
3
4
5

 ! USAGE:
      USE NMPRD_INT, ONLY: IPS

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: IPS

• IPS = 1 when the data are population data.
• IPS = 2 when the data are single-subject data.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

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

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

1
2
3
4
5
6
7

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

• 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 superprob- lem. 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).

1
2
3
4
5

 ! USAGE:
      USE ROCM_INT, ONLY: NIREC=>NINDREC,NDREC=>NDATINDR

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: NINDREC,NDATINDR

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

In addition to NDREC and NIREC, NONMEM v7.4+ provides additional record counters. All except IRECIDX refers to a record number within the current individual record. They can be accessed through the nonmem_reserved_general file:

1
2
3
4
5
6
7
8

$PK
include nonmem_reserved_general
...
EXCL=1
IF(NDREC==LASTOBS) EXCL=0
IF(NDREC==FIRSTOBS) EXCL=0
...
$TABLE ID TIME IPRED EXCLUDE_BY EXCL NOPRINT NOAPPEND file=mytable.TAB

Then, only the record containing first and last observations will be printed to the table.

• 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). ELASTDOS=-1 if no dose record PREDPP is not used
• 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.

1
2
3
4
5

 ! USAGE:
      USE ROCM_INT, ONLY: NREP,IREP=>NCREP

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: NREP,NCREP

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

1
2
3
4
5

 ! USAGE:
      USE ROCM_INT, ONLY: LIREC=>NDATPASS

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: NDATPASS

LIREC is The number of data records contained in the individual record at the current call to PRED. It changes value accordingly with calls to PASS. It may be used as a right-hand quantity in $PRED, $PK, and $ERROR blocks, and in a $INFN block in conjunction with PASS.

1
2
3
4
5

 ! USAGE:
      USE NMPRD_INT, ONLY IPRNV

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: IPRNV(2)

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

1
2
3
4
5
6

 ! USAGE:
      USE ROCM_REAL, ONLY: PR_Y

 ! GLOBAL DECLARATION:
      USE SIZES, ONLY: DPSIZE
      REAL(KIND=DPSIZE) :: PR_Y

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, expectation, data average blocks)

For the purpose of computing this probability, an actual observation need not exist in the record. If the mean and variance of the intraindividual 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.

1
2
3
4
5
6

 ! USAGE:
      USE ROCM_REAL, ONLY: TEMPLT=>VRAW

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

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

1
2
3
4
5
6

 ! USAGE:
      USE ROCM_REAL, ONLY: OMEGA=>VARNF

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

• OMEGA The current value of OMEGA being used.

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

1

      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:

1
2
3
4
5
6

 $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

1
2
3
4
5
6

 ! USAGE:
      USE NMPRD_INT, ONLY NAETA,LVOUT

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

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

1
2
3
4
5
6

 ! USAGE:
      USE ROCM_REAL, ONLY NSIG=>SIGD,SIG=>DIFA

 ! GLOBAL DECLARATION:
      USE SIZES, ONLY: LPAR,DPSIZE
      REAL(KIND=DPSIZE) :: SIGD,DIFA(LPAR)

• SIG(i): when the minimization in the Estimation Step terminates due to round- ing 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 gives the minimum of the values found in the vector SIG

The NSIG and SIG values should only be used with ICALL = 3.

1
2
3
4
5

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

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: IFRSTDER,ISECDER,IFIRSTEM

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

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

  1 2 3 4 5

  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.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

! USAGE:
  IF (MIXNUM.EQ.1) THEN
    ...
  ENDIF
  IF (MIXNUM.EQ.2) THEN
    ...
  ENDIF
  IF (MIXNUM.EQ.3) THEN
    ...
  ENDIF

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

  1 2 3

  MIXP(MIXNUM) MIXP MIXP(i)

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

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

  (See MIXNUM,MIXEST,MIXP)

  (See MIX, mixture model example).

1
2
3
4
5
6
7

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

• 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 and $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)

1
2
3
4
5
6
7

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

• SETHET(i): the standard error of THETA(i) estimate.
• 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 and $PRED, and SETHETR is the standard error of the theta reported in the report file.
• SEOMEG(i, j): the standard error of the estimate of OMEGA(i,j).
• SESIGM(i, j): the standard error of the estimate of SIGMA(i,j).

These values should only be used with ICALL = 3.

1
2
3
4
5

 ! USAGE:
      USE NMPR_INT, ONLY: ICMAX=>IMAXSIM

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: IMAXSIM

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

1

 MAXIMUM ATTEMPTS TO OBTAIN SAMPLE EXCEEDED

• ICMAX: setting ICMAX overrides the default value of 100, e.g., in a PRIOR subroutine:

  1 2 3

  USE NMPR_INT, ONLY: ICMAX=>IMAXSIM ... other code ... ICMAX=500

1
2
3
4
5

 ! USAGE:
      USE NMPRD_INT, ONLY: IERSQ

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: IERSQ

For user-defined PRED and ERROR routines.

SIMEPS is only relevant when correlations are stored in CORRL2.

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

Up to NONMEM through 7.2, C was used rather than CORRL2; Up to NONMEM 7.3, the value of IERSQ is not checked in generated code.

1
2

 ! USAGE:
      CORRL2(n,m)=...

For PRED and ERROR routines.

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

For example, assume bivariate L2 observations chronologically ordered by TIME, additionally 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):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

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

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

RESTRICTIONS:

With versions of NONMEM before 7.3, C should be used rather than CORRL2. Because C is not recognized by NM-TRAN, in addition to 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, 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).

With versions of NONMEM before 7.4.2:

1
2
3
4
5

 ! USAGE:
      USE NMPRD_INT, ONLY: IERPRD,NETEXT

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: IERPRD,NETEXT

With versions of NONMEM starting with 7.4.2:

1
2
3
4
5

 ! USAGE:
      USE NMPRD_INT, ONLY: IERPRD,IERPRDU,NETEXT

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: IERPRD,IERPRDU,NETEXT

• 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 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 $PRED error recovery.

1
2
3
4
5
6
7

 ! 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

• NPDE: Monte-Carlo generated normalized probability distribution error.
• NPD: the correlated (or non-decorrelated) NPDE value.
• NPD and NPDE are calculated at the Table Step if listed in $TABLE or $SCATTER, in that case, NONMEM sets NPDE_MODE=1, otherwise NPDE_MODE=0.

• Example: the code below incorporates Limit of Quantification (LOQ) data into NPDE assessments.

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

  ; 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), 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 NM743, you can specify an above-quantifiable limit with the reserved parameter DV_LAQ as well. For example, (..\examples\loq\ad3tr4a_loq0):

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24

  $ERROR SD = THETA(5) IPRED = LOG(F) DUM = (LOQ - IPRED) / SD ; LOQ=lower level of quantifiable level CUMD = PHI(DUM)+1.0E-10 DUMA = (LAQ - IPRED) / SD ; LAQ=Upper (above) quantifiable level CUMDA = PHI(DUMA)-1.0E-10 IF(TYPE.EQ.2) DV_LOQ=LOQ ; Type=2 is concentration below LOQ IF(TYPE.EQ.3) DV_LAQ=LAQ ; Type=3 is concentration above LAQ IF (TYPE .EQ. 1.OR.NPDE_MODE==1) THEN F_FLAG = 0 Y = IPRED + SD * ERR(1) ENDIF IF (TYPE .EQ. 2.AND.NPDE_MODE==0) THEN F_FLAG = 1 Y = CUMD MDVRES=1 ENDIF IF (TYPE .EQ. 3.AND.NPDE_MODE==0) THEN F_FLAG = 1 Y = (1.0-CUMDA) MDVRES=1 ENDIF

  New in nm74, for use with NPD, the user may supply the cumulative distribution function using the reserved variable CDF_L: For example, in a general likelihood modeled problem, essentially the previous example, but the Y values of all data are returned in their -2LL form (..\examples\loq\ad3tr4_loq6):

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

  $ERROR SD = THETA(5) IPRED = LOG(F) DUM2 = (DV - IPRED) / SD DUM = (LOQ - IPRED) / SD CUMD = PHI(DUM)+1.0E-30 CUMD2 = PHI(DUM2)+1.0E-30 IF(TYPE.EQ.1) THEN Y=2.0*LOG(SD)+DUM2*DUM2 CDF_L=CUMD2 ENDIF IF(TYPE.EQ.2) THEN Y = -2.0*LOG(CUMD) CDF_L=CUMD DV_LOQ=LOQ ENDIF … $EST METHOD=COND LAPLACE -2LL MAXEVAL=9999 NSIG=3 SIGL=9 SIGLO=9 PRINT=5 NOABORT MCETA=5 $TABLE ID TIME DV IPRED NPD NOAPPEND ONEHEADER ESAMPLE=1000 FILE=ad3tr4_loq6.TAB NOPRINT

  Note that only NPD can be evaluated without consideration of EWRES and EPRED constructs. NPDE, EWRES and EPRED cannot be evaluated for general non-normal likelihood data, or when normal data are modeled in a general log-likelihood manner, rather than assumed normal in the usual way. 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. In such cases, the DV_LAQ/CDF_LA variables must define the lower bound of a categorical level, while the DV_LOQ/CDF_L defines the upper boundary of a level, which is counter-intuitive, and its use is demonstrated as follows. In the following example, some data are normally distributed, and others are binomial (categorical). The NPDE will be evaluated only for those that are normal, while NPD are evaluated for both types of data. The CDF_L indicates to the diagnostics routine that this datum is to be treated as non-normal, with a cumulative distribution value of CDF_L, which it can use for evaluating the NPD. Because the probability is categorical, the lower bound CDF_LA needs also to be given, to map the probability of having data value DV (=0 or 1) be between CDF_LA and CDF_L for a random uniform variable (..\examples\loq\example10lcdf).

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28

  $ERROR EXCL2=1.0-TYPE EXCL=TYPE EXCL3=0.0 IF(EVID/=0) EXCL=1.0 IF(EVID/=0) EXCL2=1.0 IF(EVID/=0) EXCL3=1.0 EXPP=THETA(4)+F*THETA(5) IPRED=F ; Use protected exponent PEXP, to avoid numerical overflow A=PEXP(EXPP) B=1.0+A IF (TYPE.EQ.0.OR.NPDE_MODE==1) THEN ; PK Data F_FLAG=0 Y=F+F*ERR(1) ; a prediction ELSE ; Categorical data F_FLAG=1 Y=DV*A/B+(1.0-DV)/B ; a likelihood MDVRES=1 ENDIF IF(TYPE==1) THEN CDF_L=(1.0-DV)*1.0/B + DV CDF_LA=DV*1.0/B DV_LOQ=DV DV_LAQ=DV-1.0 ENDIF

  For DV=0 the lower bound of its value is DV_LAQ=-1 with a cumulative probability of CDF_LA=0 (that is, it is impossible for DV to have a value of -1), and upper bound DV_LOQ=0 has probability of CDF_L of 1/B (that is, the probability of it being 0 is 1/B, which is consistent with how the likelihood Y is defined). When DV=1, then range of its value is from lower bound DV_LAQ=0 with cumulative probability CDF_LA=1/B (which is consistent with the upper bound interpretation for DV=0), to upper bound DV_LOQ=1 with cumulative probability CDF_L= of 1 (consistent with the idea that the highest DV can be is 1).

  In summary, we have the following:

  DV	Lowe bound (DV_LAQ)	Upper bound (DV_LOQ)	Lower cumulative (CDF_LA)	Upper cumulative (CDF_LOQ)
  0	-1	0	0	1/B
  1	0	1	1/B	1

  The rationale is to direct the NPD algorithm to create random positioned NPD values for any data that are below DV_LOQ, and or above DV_LAQ. For continuous data, values are accurately known as the observed value DV between DV_LOQ and DV_LAQ, but are not known below DV_LOQ, or above DV_LAQ, and so, the NPD should create a scrambled DV value whenever it is below DV_LOQ and/or above DV_LAQ. Categorical data have discrete values, so in order to turn them into continuous, normally distributed equivalents for NPD, scrambled values must be created, for values above DV_LAQ, and/or below DV_LOQ, that is, for all legitimate discrete values. Thus, when DV_LOQ<DV_LAQ, the DV_LOQ and DV_LAQ serve as the boundaries for the outer distribution region for scrambling, and when DV_LAQ<DV_LOQ, the DV_LAQ and DV_LOQ serve as boundaries for the inner distribution region for scrambling.

1
2
3
4
5

 ! USAGE:
      USE NMPRD_INT, ONLY: ETASXI

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE), ALLOCATABLE, DIMENSION(:)   :: ETASXI

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

• ETASXI(i): 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 index i refers to ETA(i). ETASXI(i) overrides ETASTYPE.

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

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

For example, with

1
2

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

for all subjects, ETA(3) is excluded and ETA(4) is included. while with

1
2

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

ETA(1) is excluded for subject 1, and ETA(3) included for subject 23.

The additional output file root.shm ("shrinkage map") contains information which ETAs are excluded in the ETA shrinkage assessment.

1
2
3
4
5

 ! USAGE:
      USE NMPRD_CHAR, ONLY :: ETEXT

 ! GLOBAL DECLARATION:
      CHARACTER(LEN=132) :: ETEXT(3)

• ETEXT: 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.

1
2
3
4
5
6

 ! USAGE:
      USE NMPR_REAL, ONLY CTUP,DCTUP,DDCTUP

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

An observation can represent the event that a normally distributed variable falls within a specified interval. NONMEM automatically computes the likelihood for this event. In the data record, specify the variable’s mean and variance as usual, and set CTUP to the interval’s upper endpoint.

If the endpoint depends on an ETA variable (for population data), also provide its first and second derivatives with respect to ETAs. Derivatives equal to 0 need not be set, and only the lower-triangular elements of DDCTUP are required.

CTUP may be assigned in $PRED or $ERROR code, where NM-TRAN automatically sets derivatives. NONMEM detects when CTUP is unset. When CTUP is used, the Laplacian estimation method is required.

CTLO may be used in conjunction with CTUP.

PR_CT is the estimated probability that an observation will be of the category in question.

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

1
2
3
4
5
6

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

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.

PR_CT is the estimated probability that an observation will be of the category in question.

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

1
2
3
4
5

 ! USAGE:
      USE NMPR_INT, ONLY SKIP_=>SKIP

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: SKIP

• SKIP_: 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- evel 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:

1
2
3
4
5

 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

In other words, the following three are equivalent:

1
2
3
4
5
6
7
8
9

      SKIP_=2

      IF (...) THEN
         END SECOND-LEVEL SUPERPROBLEM ITERATION
      ENDIF

      IF (...) THEN
         ENDSECONDLEVELSUPERPROBLEMITERATION
      ENDIF

1
2
3
4
5

 ! USAGE:
      USE NMPR_INT, ONLY: F_FLAG=>IPRDFLG1

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: IPRDFLG1

• F_FLAG=1: when LIKELIHOOD or -2LOGLIKIHOOD options are used in $ESTIMATION, F_FLAG=1, indicating that for all observations, the variable Y (in NM-TRAN abbreviated code) or F (in user-supplied PRED or ERROR routine) is being set to a LIKELIHOOD/-2LOGLIKIHOOD value for the observation.
• F_FLAG=0: when neither LIKELIHOOD or -2LOGLIKIHOOD used, for a given observation, F_FLAG=0, and Y or F is being set to a "prediction" of the observation. One can manually set F_FLAG=1 or F_FLAG=2 in the PRED or ERROR routine, so that Y or F will be set to LIKELIHOOD/-2LOGLIKIHOOD value for this particular observation.

• F_FLAG may be set in NM-TRAN abbreviated code:

  1 2 3 4 5 6 7 8

  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.

• When F_FLAG/=0 for some observation, neither the LIKELIHOOD or -2LOGLIKIHOOD option may be used, and the Laplacian estimation method must be used.
• F_FLAG=0 except with all observations within an individual record. In that case RES and WRES will be 0 for all data records for the individual.
• When F_FLAG/=0 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 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.

1
2
3
4
5
6

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

THETA, OMEGA, and SIGMA from a Simulation Step using the user-supplied routine PRIOR must be stored in THSIMP, OMSIMP, and SGSIMP, respectively. This is done automatically when NONMEM utility routines NWPRI or TNPRI is used to generate THETA, OMEGA, and SIGMA values.

• Without $THETAR, THSIMPR contains the same values as THSIMP
• With $THETAR, 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).

1
2
3
4
5
6

 ! USAGE:
      USE NMPR_REAL, ONLY: YLO,YUP

 ! GLOBAL DECLARATION:
      USE SIZES, ONLY: DPSIZE
      REAL(KIND=DPSIZE) :: YLO,YUP

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.

1
2
3
4
5
6

 ! USAGE:
      USE NMPRD_REAL, ONLY: PASSRC

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

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.

1
2
3
4
5
6

 ! 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

• RPTO: the "repetition output value", can be used in PRED, or as a left-hand quantity in $PRED, $PK and $ERROR.

  • RPTO=0: no effect.
  • RPTO=n (n 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-sub- ject data, contiguous records of the data set) which will be repeated. See the repeat data item (See RPT_).
  • RPTO=-n (n 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: 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 singlesubject 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: 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 ini- tiated 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: "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: 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: the output from PRED with a passed record (except for the values of the repetition variables) is to be ignored by NONMEM.
  • PRDFL=1: 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.

  (See repeti1, repeti2)

  Help file repeti1 discusses the following files in the examples directory:

  repeat1.ctl repeat1s.ctl repeat1t.ctl repeatf.ctl

1
2
3
4
5

 ! USAGE:
      USE NMPRD_INT, ONLY: I_REC=>IRECRSIV

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: IRECRSIV

A PRED routine may be recursive: 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. This is the case for PREDPP.

• PRED is nonrecursive by default. At ICALL=0 or 1, one can declare PRED recursive by setting I_REC=1. This can be changed from problem to problem. For a problem with population data I_REC is always reset to 0.
• When I_REC=1 while PRED does not use repetition, the SPECIAL option needs not appear on the $COVARIANCE record, as the special computation is automatically applied.
• 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 setin $PRED, NM-TRAN sets I_REC=1.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

 ! 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

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:

1

COMRES=-1

Variables from all blocks of abbreviated code can be excluded from the module by including the above code on the $ABBREVIATED record.

Variables from NMPRD4 can be used in a user-written subroutine by adding

1

USE NMPRD4

statement. The variables are COM(1), COM(2), …., so that they can be used as

1

 X=COM(1)/COM(1)

One can also use variables $PRED, $PK or $ERROR, e.g., for variables CL and V from $PK, and the following in the generated PK routine:

1

  CL=>COM(00001); V=>COM(00002)

Then in the user-written subroutine, after the last declaration, one can include:

1

 POINTER :: CL,V

Prior to the first executable statement, include:

1

 CL=>COM(1); V=>COM(2)

Now the code can be written as

1

 X=CL/V

See also: Guide IV, $ABBREVIATED, $TABLE, $SCATTERPLOT, and abbreviated code.

1
2
3
4
5
6

 ! USAGE:
      USE NMPRD_REAL, ONLY: ETA,EPS

 ! GLOBAL DECLARATION:
      USE SIZES, ONLY: LVR,DPSIZE
      REAL(KIND=DPSIZE) :: ETA(LVR),EPS(LVR)

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

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.

1
2
3
4
5

 ! USAGE:
      USE NMPR_INT, ONLY: IETAOL,IEPSOL

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: IETAOL,IEPSOL

IETAOL and IEPSOL override the NEW option in $SIMULATION. This can 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 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. If this call is to be affected, values must be stored using verbatim code in the FIRST block.

1
2
3
4
5

 ! USAGE:
      USE NMPRD_INT, ONLY: MDVRES

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: MDVRES

MDVRES stands for missing dependent variable (MDV) for residual (RES). Setting MDVRES=1 temporarily declares an observation as missing during the computation of residuals and weighted residuals. MDVRES=0 by default. Set MDVRES to 1 in the $ERROR or $PRED routine if you do not want to include a particular value for weighted residual assessment. This may be useful when, for example, this data point is assessed by a non-normal distribution likelihood such as the PHI() function for below detection limit values, in which F_FLAG is set. By default, if at least one data value of a given subject is fitted with a non-normal distribution likelihood, then population weighted residual diagnostics are not assessed for any of the data for that subject. By setting MDVRES=1 to these particular below detection values, the weighted residual algorithm can assess the remaining normally distributed values for that subject.

• MDVRES can be set in $ERROR or $PRED.

• Example: when F_FLAG is used, by default, if F_FLAG/=0 for any observation within an individual record, the RES and WRES items will be 0 for all data records for that individual. MDVRES=1 overrides this default so that NONMEM will compute RES and WRES for observations. 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.

  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.

  1 2 3 4 5 6 7 8 9 10 11 12 13 14

  $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

1
2
3
4
5
6
7
8
9

  ! USAGE:
  USE PKERR_REAL, ONLY :: MTIME

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

  ! in the generated PK routine from FSUBS:
  USE PKERR_REAL,ONLY: MTIME

Model event times are additional PK parameters defined in the PK routine or $PK block. Similar to absorption lag times, a model event time MTIME(i) defines a time at which the system is modified or advanced (i is not related to compartment but merely a counter). When MTIME(i) is reached, read-only indicator variables MNOW(i), MPAST(i), MNEXT(i) change value and a call to PK is made. The calls to PK, DES, AES, and ERROR can use the indicator variables to change behavior of the system, such as adding a term in the differential equation or adjusting the rate of an infusion. This feature may be used with any ADVAN routine.

The indicator variables are defined as

1
2
3
4
5
6

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

PCT defines (in PSIZES and TSIZES) the maximum number of model event times. The default value is 30. They are all intialized to 0 at start of an IR and at RESET events.

The indicator variables change value in the following way.

• MNEXT: 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: 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. For example, assume MTIME(1)<MTIME(2)<MTIME(3), then the MNEXT and MPAST values assume the following sequence.

  1 2 3 4 5 6 7 8

  MTIME(1) MTIME(2) MTIME(3) ............|..............|..............|.................. 011111111111100000000000000000000000000000000000000 MNEXT(1) 000000000000011111111111111100000000000000000000000 MNEXT(2) 000000000000000000000000000011111111111111100000000 MNEXT(3) 000000000000011111111111111111111111111111111111111 MPAST(1) 000000000000000000000000000011111111111111111111111 MPAST(2) 000000000000000000000000000000000000000000011111111 MPAST(3)

• MNOW: MNOW=i if MNEXT(i)=1 for some i. MNOW=0 otherwise.

In addition, NONMEM provides variable MTDIFF

1
2
3
4
5

  ! USAGE:
    USE PRMOD_INT, ONLY: MTDIFF

  ! GLOBAL DECLARATION:
    INTEGER(KIND=ISIZE) :: MTDIFF

to flag that the values of MTIME have possibly been reset. The value of MTDIFF is 0 when PK is called. If PK sets MTDIFF to a value other than 0, 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, because these record automatically reset all MTIME(i) to 0.

MTIME does not have to be consecutive or in ascending order: PK may define MTIME(i) and MTIME(i+2) but not MTIME(i+1). In this case MTIME(i+1)=0. (Internally PK copies MTIME parameters and their ETA derivatives to GG. If there are gaps in the sequence of MTIME parameters, the corresponding positions in GG are left as-is. Since GG is initialized to 0 before calls to PK, the omitted MTIME parameters is 0. Since ETA derivatives are not included in MTIME, the ERROR routine should not use MTIME parameters in such a way as to influence the value of Y if those parameters have ETA derivatives.)

The MTIME array is never listed in NMPRD4. Therefore, if an MTIME parameter is to be output it must be copied to a PK-defined variable in NMPRD4, e.g.,

1
2
3
4

  MTIME(1)=...
  MT1=MTIME(1)
  ...
  $TABLE MT1

MTIME is independent of non-event dose times. In particular, MTIME is ignored during Steady-State calculation since it is intended for a single repeated dose with no changes in the status of the system.

MTIME is in fact a random variable so may contain ETA in the definition. Therefore the indicator variables can be implicitly ETA-dependent. However, PREDPP does not consider the indicator variables as random variables, and their ETA-derivatives are always 0.

For example, consider an infusion with rate

• 400*EXP(ETA(1)) from time 0 to 1.5;
• 300*EXP(ETA(2)) from time 1.5 to 2.5;
• 200*EXP(ETA(3)) from time 2.5 till end of infusion.

One can write $PK as

1
2
3
4
5
6

MTIME(1)=1.5
MTIME(2)=2.5
R1= 400*EXP(ETA(1))*(1-MPAST(1))
R1=R1+300*EXP(ETA(2))*(MPAST(1)-MPAST(2))
R1=R1+200*EXP(ETA(3))*MPAST(2)
WRITE (82,*) TIME,MNOW,MNEXT(1),MNEXT(2),MPAST(1),MPAST(2),R1,TSTATE

with events at time 0, 1, 3. Then the MTIME output (file fort.82) is

1
2
3
4
5
6

TIME    MNOW    MNEXT1  MNEXT2  MPAST1  MPAST2  R1        TSTATE
0.00    0.00    0.00    0.00    0.00    0.00    400.00    0.00
1.00    0.00    0.00    0.00    0.00    0.00    400.00    0.00
3.00    1.00    1.00    0.00    0.00    0.00    400.00    1.00
3.00    2.00    0.00    1.00    1.00    0.00    300.00    1.50
3.00    0.00    0.00    0.00    1.00    1.00    200.00    2.50

For another example, consider an Enterohepatic Recycling (EHC) model (see MTIME example). The model has drug transfer from compartment 4 to 1 controlled by a random "FLAG":

1
2

  DADT(1)=-KA*A(1)+K41*A(4)*FLAG
  DADT(4)=K1G*A(2)-K41*A(4)*FLAG

The approaches below are equivalent.

• No use of model event times but define two dummy compartments (5 and 6) and dummy doses with lag times

  1 2 3 4 5

  CID DOSE TIME DV EVID CMT 101 10 0 0 1 2 101 1 0 0 1 5 101 1 0 0 1 6 101 0 2.0 0 0 2

  and define FLAG in $DES:

  1 2 3 4 5 6 7 8 9 10 11 12 13 14

  $PK ;#... ALAG5=THETA(8)*EXP(ETA(8)) DELTA=THETA(9)*EXP(ETA(9)) ALAG6=ALAG5+DELTA ;#... $DES FLAG=0.0 IF (T.GE.ALAG5) FLAG=1 IF (T.GE.ALAG5.AND.DOSTIM.EQ.ALAG5) FLAG=0 IF (T.GE.ALAG5.AND.DOSTIM.EQ.0.AND.TIME.EQ.ALAG5) FLAG=0 IF (T.GE.ALAG6) FLAG=0 IF (T.GE.ALAG6.AND.DOSTIM.EQ.ALAG6) FLAG=1 IF (T.GE.ALAG6.AND.DOSTIM.EQ.0.AND.TIME.EQ.ALAG6) FLAG=1

• Using the same data setup as the above, but instead define FLAG in $PK:

  1 2 3 4 5 6 7 8 9 10 11 12 13

  $PK ;#... ALAG5=THETA(8)*EXP(ETA(8)) DELTA=THETA(9)*EXP(ETA(9)) ALAG6=ALAG5+DELTA IF (NEWIND.LT.2) THEN FLAG=0.0 OLDTIM=0 ENDIF IF (OLDTIM.EQ.ALAG5) FLAG=1 IF (OLDTIM.EQ.ALAG6) FLAG=0 OLDTIM=DOSTIM

• Use model event times, no dummy compartments or doses,

  1 2 3

  CID DOSE TIME DV EVID CMT 101 10 0 0 1 2 101 0 2.0 0 0 2

  and define MTIMES and FLAG in $PK

  1 2 3 4 5

  $PK MTIME(1)=THETA(8)*EXP(ETA(8)) DELTA=THETA(9)*EXP(ETA(9)) MTIME(2)=MTIME(1)+DELTA FLAG=MPAST(1)-MPAST(2)

  Note that here FLAG is considered by NMTRAN to be an implicit basic PK parameter hence its ETA derivatives (always 0) are included in the calculations.

• Use same model event times as above, and define FLAG in $DES:

  1 2 3 4 5 6

  $PK MTIME(1)=THETA(8)*EXP(ETA(8)) DELTA=THETA(9)*EXP(ETA(9)) MTIME(2)=MTIME(1)+DELTA $DES FLAG=MPAST(1)-MPAST(2)

  Unlike the previous approach here FLAG is known not to have derivatives because it is DES-defined.

For an example of modifying MTIME, consider events at times 0 and 10 but one wants to advance in increments of 1 with stops at times 1, 2, 3, …. , 9, 10. Intead of writing

1
2
3
4
5

  IF (TIME.EQ.0) THEN
    MTIME(1)=0
  ELSE
    MTIME(1)=MTIME(1)+1
  ENDIF

one should use

1
2
3
4
5
6

    IF (TIME.EQ.0) THEN
       TEMP=0
    ELSE
       TEMP=TEMP+1
    ENDIF
    MTIME(1)=TEMP

This is because if a basic or additional PK parameters is set conditionally in the $PK block, NM-TRAN inserts statements setting it to 0 so that, if it is not set by the $PK block, its value is 0. In the code that does not work, MTIME(1) does not retain its value from one call to the next. In the code that does work, TEMP (being a PK-defined item that does not depend on ETAs) does retain its value. See model time examples for details.

When MTIME values contains coincidence of times, the following rules apply.

• MTIME(i)=MTIME(j), i < j. There will be two calls to PK:

  1 2 3

  call MNEXT(i) MNEXT(j) MPAST(i) MPAST(j) MNOW 1 1 0 0 0 1 2 0 1 1 0 2

• MTIME(i)=AFLAGj. MNEXT(i) and DOSTIM are set on separate calls to PK. First, MNEXT(i). Then, DOSTIM. For example

  1 2 3 4 5

  $PK ;# ... ALAG1=.5 MTIME(1)=ALAG1 WRITE (82,*) TIME,MNOW,MNEXT(1),MPAST(1),DOSTIM,TSTATE

  Events at times 0, 1, 3. Values in fort.82 are

  1 2 3 4 5 6

  TIME MNOW MNEXT MPAST DOSTIM TSTATE 0.00 0.00 0.00 0.00 0.00 0 1.00 1.00 1.00 0.00 0.00 0 1.00 0.00 0.00 1.00 0.50 .5 1.00 0.00 0.00 1.00 0.00 .5 3.00 0.00 0.00 1.00 0.00 1.0

• MTIME(i)=event time. There will be two calls: first MTIME(i), followed by event time. For example,

  1 2 3 4

  $PK ;# ... MTIME(1)=1 WRITE (82,*) TIME,MNOW,MNEXT(1),MPAST(1),TSTATE

  Events at times 0, 1, 3. Values in fort.82 are

  1 2 3 4 5

  TIME MNOW MNEXT MPAST TSTATE 0.00 0.00 0.00 0.00 0 1.00 1.00 1.00 0.00 0 1.00 0.00 0.00 1.00 1 3.00 0.00 0.00 1.00 1

  With the above output in mind, consider ALAGj=event time. In this case there will be two calls: first, at ALAG1, followed by at the event time. For example,

  1 2 3 4

  $PK ;# ALAG1=1 WRITE (72,*) TIME,DOSTIM,TSTATE

  Events at times 0, 1, 3. Values in fort.72 are

  1 2 3 4 5

  TIME DOSTIM TSTATE 0.00 0.00 0 1.00 1.00 0 1.00 0.00 1 3.00 0.00 1

• MTIME(i)=additional dose time MNEXT(i) and DOSTIM are set on separate calls to PK: first, MNEXT(i) is set, folowed by DOSTIM. For example,

  1 2 3 4

  $PK ;#... MTIME(1)=.5 WRITE (82,*) TIME,MNOW,MNEXT(1),MPAST(1),DOSTIM,TSTATE

  Events at times 0, 1, 3. Dose at time 0 specifies ADDL=1, II=.5. Values in fort.82 are

  1 2 3 4 5 6

  TIME MNOW MNEXT MPAST DOSTIM TSTATE 0.00 0.00 0.00 0.00 0.00 0.00 1.00 1.00 1.00 0.00 0.00 0.00 1.00 0.00 0.00 1.00 0.50 0.50 1.00 0.00 0.00 1.00 0.00 0.50 3.00 0.00 0.00 1.00 0.00 1.00

• MTIME(i)=additional dose time = event time. There will be three calls to PK: MNEXT(i) and DOSTIM are set on separate calls to PK. First, MNEXT(i). Then, DOSTIM. Finally, a call at event time. For example,

  1 2 3 4

  $PK ;#... MTIME(1)=1 WRITE (82,*) TIME,MNOW,MNEXT(1),MPAST(1),DOSTIM,TSTATE

  Events at times 0, 1, 3. Dose at time 0 specifies ADDL=1, II=1. Values in fort.82 are

  1 2 3 4 5 6

  TIME MNOW MNEXT MPAST DOSTIM TSTATE 0.00 0.00 0.00 0.00 0.00 0.00 1.00 1.00 1.00 0.00 0.00 0.00 1.00 0.00 0.00 1.00 1.00 1.00 1.00 0.00 0.00 1.00 0.00 1.00 3.00 0.00 0.00 1.00 0.00 1.00

  Now compare the above situation with MTIME(i)= lagged dose time = event time. There will be three calls to PK: MNEXT(i) and DOSTIM are set on separate calls to PK. First, MNEXT(i). Then, DOSTIM. Finally, a call at event time. For example,

  1 2 3 4 5

  $PK ;#... MTIME(1)=1 ALAG1=1 WRITE (82,*) TIME,MNOW,MNEXT(1),MPAST(1),DOSTIM,TSTATE

  Events at times 0, 1, 3. Dose at time 0 specifies ADDL=1, II=1. Values in fort.82 are

  1 2 3 4 5 6 7

  TIME MNOW MNEXT MPAST DOSTIM TSTATE 0.00 0.00 0.00 0.00 0.00 0.00 1.00 1.00 1.00 0.00 0.00 0.00 1.00 0.00 0.00 1.00 1.00 1.00 1.00 0.00 0.00 1.00 0.00 1.00 3.00 0.00 0.00 1.00 2.00 1.00 3.00 0.00 0.00 1.00 0.00 2.00

1
2
3
4
5
6

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

When A_0FLG==1 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) w.r.t. ETA(i)
• D2A_0: D2A_0(n,i,j) = the second derivative of A_0(n) w.r.t. 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.
• 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 State Vector A.)

1
2
3
4
5

 ! USAGE:
      USE PROCM_INT, ONLY: A_0FLG

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: 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-order ETA derivatives (DAETA and D2AETA) are set to zero. A_0FLG=0 at all other calls to PK.

User can initialize PK compartments conditional on A_0FLG=1, by setting the initial values and partial derivatives in A_0, DA_0, D2A_0.

NM-TRAN includes A_0FLG in the PK routine when the $PK block uses variables A_0FLG, A_0(n), or A_INITIAL(n), or verbatim code is used.

1
2
3
4
5
6

 ! USAGE:
      USE PROCM_INT, ONLY: NACTIV,M=>IDXETA

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

• NACTIV: NACTIV = number of ETAs in the problem - NRETA. (See non-active ETA list for PRED). It is the number of ETAs that NONMEM is currently calculating partial derivatives for.
• 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:

1
2

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

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

A message similar to the following is sometimes produced by ADVAN7

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

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

The differential equation settings are not fully documented. The interested user may be able to obtain more information by studying the appropriate sections of PREDPP code.

1
2
3
4
5

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

These variables allow the user to override 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:

  1 2	$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

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

  1 2 3 4 5 6 7 8

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

  1	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 (2*PE*PM+PM=189). Then for problems with large numbers of compartments and/or ETAs, the work arrays will not be large enough, with either INTFLG=-1 or INTFLG!=-1.

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

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

1
2
3
4
5
6
7
8

 ! 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

For user-supplied DES and AES routines.

Passed by PREDPP to PK and ERROR routines, EVTREC(I,J) is the Jth data item of the Ith data record of the event record.

• EVTREC: same as EVTREC;
• NVNT: same as NVNT passed by PREDPP to PK and ERROR routines.

1
2
3
4
5
6

 ! USAGE:
      USE PROCM_REAL, ONLY: DOSTIM,DDOST,D2DOST

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

For user-supplied PK, DES, AES routines.

• 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-order 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)

1
2
3
4
5
6

 ! USAGE:
      USE PROCM_REAL, ONLY: DOSREC

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

For user-supplied PK, DES, AES routines.

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

1
2
3
4
5

 ! USAGE:
      USE PROCM_INT, ONLY: NEWIND=>PNEWIF

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: PNEWIF

For user-supplied PK and ERROR routines. 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.

1
2
3
4
5

 ! USAGE:
      USE PROCM_CHAR, ONLY: FMT

 ! GLOBAL DECLARATION:
      CHARACTER*80 FMT(3)

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

1
2
3
4
5
6

 ! USAGE:
      USE PROCM_REAL, ONLY: TSTATE

 ! GLOBAL DECLARATION:
      USE SIZES, ONLY: DPSIZE
      REAL(KIND=DPSIZE) :: 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.

1
2
3
4
5
6

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

• A: 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.

For an example, see Guide VI, Figure 14.

1
2
3
4
5

 ! USAGE:
      USE PROCM_INT, ONLY: ISFINL

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: 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.

1
2
3
4
5

 ! USAGE:
      USE PRMOD_INT, ONLY ICALL=>ICALLD,IDEFD,IDEFA

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

• ICALL: identical to the argument ICALL passed by NONMEM to PREDPP.

• IDEFD: DES may set IDEFD when ICALL = 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) is full/compact flag for DES: when IDEFD(2)=0 DES will return compact arrays; when 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) for the 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

1
2
3
4
5
6

 ! USAGE:
      USE PROCM_REAL, ONLY: THETA=>THETAS

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

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

1
2
3
4
5

 ! USAGE:
      USE PRMOD_INT, ONLY: I_SS,ISSMOD

 ! GLOBAL DECLARATION:
      INTEGER(KIND=ISIZE) :: I_SS,ISSMOD

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.

  Similar 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

  1 2 3 4 5

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

  (See $MODEL, MODEL).

1
2
3
4
5
6

  ! USAGE:
       USE PRDDESLVU, ONLY: PASTZERO ! for ADVAN18
       USE PRRADAR5U, ONLY: PASTZERO ! For ADVAN16/17
  ! GLOBAL DECLARATION:
       USE SIZES, ONLY: DPSIZE
       REAL (KIND=DPSIZE) PASTZERO

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,

1

 $DES PASTZERO=-10.0

1
2
3
4
5
6
7

  ! 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

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

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

1
2
3
4
5
6
7
8
9

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

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

1

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

  1	IF(TIME==4.0) STOP_TIME=5.0

• To set back to default (end of normal integration interval)

  1	STOP_TIME=-1.0d+300

1
2
3
4
5
6

  ! USAGE:
        USE PRLS01_REAL, ONLY: HINIT_,HMIN_,HMAX_

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

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:

1

 $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)"