ICALL is an argument passed by NONMEM to user-supplied subroutines CCONTR, CONTR, CRIT, PRED, PRIOR and MIX. It is also selectively passed to PK, ERROR, and INFN. It can be used in $PK, $ERROR, and $PRED abbreviated code. The discussion below describes the values of ICALL as seen by PRED.

• ICALL=-1: the routine has been called for the PRED_IGNORE_DATA feature (NM75). One call per data record, at the start of the run. These calls occur only if abbreviated code uses variables PRED_IGNORE_DATA or PRED_IGNORE_DATA _TEST, or if the PRED_IGNORE_DATA option of $DATA is used. Otherwise, there are no calls to PRED with ICALL=-1.
• ICALL=0: the routine has been called for initialization at the beginning of the NONMEM run; one such call per run.
• ICALL=1: the routine has been called for initialization at the beginning of a NONMEM problem; one such call per problem.
• ICALL=2: the routine has been called for a prediction. Multiple calls occur.
• ICALL=3: the routine has been called for finalization at the end of a NONMEM problem; one such call per problem.
• ICALL=4: the routine has been called during the Simulation Step; multiple calls occur, as with ICALL=2.
• ICALL=5: the routine has been called when expectations are being computed; multiple calls occur.
• ICALL=6: the routine has been called when raw data averages are being computed; multiple calls occur.

Note that not every subroutine listed is called all possible ICALL values.

One common pattern of using ICALL is to test it in the abbreviated code:

 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

IF (ICALL==0) THEN
;! Run Initialization block
ENDIF

IF (ICALL==1) THEN
;! Problem Initialization block
ENDIF

IF (ICALL==2) THEN
;! Data Analysis block
ENDIF

IF (ICALL==3) THEN
;! Problem and Run Finalization block
ENDIF

IF (ICALL==4) THEN
;! Simulation block
ENDIF

IF (ICALL==5) THEN
;! Expectation block
ENDIF

IF (ICALL==6) THEN
;! Data Average block
ENDIF

See code blocks for extensive use of ICALL.

USAGE:

1
2
3
4

      SUBROUTINE CONTR (I,CNT,IER1,IER2)
      USE SIZES, ONLY: ISIZE,DPSIZE
      INTEGER(KIND=ISIZE), INTENT(IN OUT) :: I,IER1,IER2
      REAL(KIND=DPSIZE),   INTENT(IN OUT) :: CNT

CONTR is a user-supplied routine for computing the contribution made to the objective function from an L1 record. It is used to override the NONMEM default objective function.

A user-supplied CONTR routine may be used when the dimension of OMEGA is zero, i.e., when there are no ETAs in the problem, and in other situations, e.g., with categorical data.

When NM-TRAN is used, the $CONTR record may be used to request that information from the data records be made available to CONTR.

Input argument:

• I Similar to ICALL for PRED subroutine. Possible values: 0, 1, 2

Output argument:

• CNT Contribution to -2log likelihood for data from the individual record.
• IER1 0 - Normal return; non-zero - error return.
• IER2 0 - error-recovery is to be implemented when IER1 is nonzero; 1 - NONMEM is to stop when IER1 is nonzero.

Other Inputs: other inputs are available to CONTR in NONMEM read-only global variables. In particular:

• Current THETA (See also CONTR_MIX:THETA)
• DV and data values for this L1 record. (See $CONTR)
• Predictions and derivatives. (See CONTR)

NONMEM Utility routines may be called by CONTR, depending on the type of data:

If the scatterplot step is implemented, and zero lines are appropriate for values of RES and/or WRES, CONTR should request that NONMEM generate such lines. (NONMEM does this by default when a user supplied CONTR is not supplied.) To request zero lines for RES and WRES, CONTR should set OPSCRS(2) and OPSCRS(3) (respectively) to 1. e.g.,

1
2
3
4
5
6

      USE CMNM6_INT, ONLY: OPSCRS=>ICONTRSC
       ...
      IF (ICALL.LE.1) THEN
      OPSCRS(2)=1
      OPSCRS(3)=1
      ENDIF

1
2
3
4
5

 USAGE:
      SUBROUTINE CCONTR (I,CNT,P1,P2,IER1,IER2)
      USE SIZES, ONLY: ISIZE,DPSIZE
      INTEGER(KIND=ISIZE), INTENT(IN OUT)    :: I,IER1,IER2
      REAL(KIND=DPSIZE),   INTENT(IN OUT)    :: CNT,P1(:),P2(:,:)

CCONTR is a user-supplied routine for computing the contribution made to the objective function from an L2 record. It is used to override the NONMEM default objective function.

CCONTR may be used when there are no EPS or ETA and in other situations, e.g., with categorical population data.

NONMEM could output error message:

1
2

 USER CCONTR ROUTINE NOT USED, BUT THERE ARE NO EPSILONS,
 AND ETAS ARE TO BE ESTIMATED

This can happen when POSTHOC ETAs are requested, but the data are single-subject data. The user may have included the POSTHOC option in error.

The CCONTR routine may contain the following code:

1

 CALL CELS (CNT,P1,P2,IER1,IER2)

If the data is correlated across L2 records (e.g., auto-regressive data), CCONTR computes the contribution to the objective function for data from an entire individual record.

Input argument:

• I Similar to Ifor PRED subroutine Possible values: 0, 1, 2

Output argument:

• CNT The conditional contribution to the objective function for this L2 record.
• P1 P1(i) is the partial derivative of CNT with respect to eta(i).
• P2 P2(i,j) is the second partial derivative of CNT with respect to eta(i) and eta(j) (for i <= j). At ICALL=1, CCONTR sets P2(1,1)=-1 if second derivative values are to be used. Otherwise, if cross-gradient values are to be used.

• IER1 0(Normal return); >0(error return).

• IER2 0 if error-recovery is to be implemented when IER1 is nonzero; 1 if NONMEM is to stop when IER1 is nonzero.
• Other inputs Other inputs are available to CCONTR in NONMEM read-only global variables. (See CONTR_MIX:THETA) E.g., USE ROCM_REAL, ONLY: THETA=>THETAC (See CCONTR:_Y,DATA,N1,N2,DIM) (See CCONTR:_F,G,H)

CCONTR is called by NONMEM's NCONTR routine with one level 2 ("L2") record after another. If no CCONTR routine is supplied by the user, NCONTR calls NONMEM utility CELS ("Conditional ELS"; ELS contribution conditional on knowing eta). If no L2 data item is present, each level 2 record is a single observation event record. Otherwise, it is a group of observation records grouped together by a common value of L2.

USAGE:

1
2
3
4
5
6
7

      SUBROUTINE CRIT (ICALL,J,N,WRES,V)
      USE SIZES, ONLY: ISIZE,DPSIZE
      INTEGER(KIND=ISIZE), INTENT(IN)     :: J,N
      INTEGER(KIND=ISIZE), INTENT(IN)     :: ICALL
      REAL(KIND=DPSIZE),   INTENT(OUT)    :: V
      REAL(KIND=DPSIZE),   INTENT(IN)     :: WRES(*)
      END SUBROUTINE CRIT

The CRIT subroutine is used to modify the NONMEM objective function used with the First-Order (or the Extended Least Squares) Estimation method. This objective function may be regarded as being the sum of contributions computed from each individual record. The first term in the contribution from an individual record is independent of data, but the second term in the contribution is the sum of the squared weighted residuals for the data in the record. The weights are functions of the model parameters and are obtained so that with a given set of parameter values, assumed to be the true parameter values, each weighted residual has unit variance and all the weighted residuals are mutually uncorrelated. With the CRIT routine, a function of the weighted residuals other than the sum of their squares may be substituted for the second term. The function may vary between individual records. The CRIT routine is called by NONMEM with one individual record after another (individual records without observations are skipped).

Input argument:

• ICALL Similar to ICALL for PRED subroutine.

  • 0 - First call to CRIT in the run
  • 1 - First call to CRIT in the current problem
  • 2 - Computation of function value required
• J Number of individual record
• N Number of observations in the individual record
• WRES Vector of weighted residuals (as many residuals as there are observations)

Output argument:

• V Value of function

Note: When a user CRIT is supplied, NONMEM subroutine CELS may not be called.

For use with PREDPP's ADVAN9 and ADVAN15 and ADVAN17.

1
2
3
4
5
6

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

In general, a system of differential-algebraic equations has the form $$ \frac{dA(t)}{dt}=g(A(t), p, t),\quad 0=h(A(t), p, t) $$ For both equations the left-hand-side (LHS) and right-hand-size (RHS) are vectors in general, \(A=[A_1, \dots, A_{n_1}]^T\), \(g=[g_1, \dots, g_{n_1}]^T\), \(h=[h_1, \dots, h_{n_2}]^T\). A denotes the drug amount in all compartments except the output compartment, \(p\) the internal PK parameters, and \(t\) the time. This is used to describe a system with \(n_1\) compartments in nonequilibrium and \(n_2\) compartments in equilibrium.

For example, $$ p=[K_e, K_a, R]^T,\quad g_1=-K_aA_1, \quad g_2=K_aA_1-K_2A_2, \quad h_1=A_3-RA_2 $$ describes the one compartment model with linear elimination and absorption from a drug depot (ADVAN2), coupled with a third compartment in equilibrium with the central central compartment. Constant R is the ratio of the drug amount.

The AES subroutine is called by PREDPP to evaluate algebraic expressions for ADVAN9, ADVAN15, and ADVAN17. It evaluates \(h()\) functions and store the results in vector E. The evaluation \(g()\) is delegated to the DES routine.

Input argument:

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

Input/output arguments:

• INIT When AES is called with INIT=1, this is an initial condition call at the start of an integration interval. Approximate amounts in each equilibrium compartment n at time T must be stored in A(n). (The amounts in the non-equilibrium compartments are already stored in the lower-numbered elements of A.) DA, DP, DT need not be computed. If AES stores approximate values in A, it must set INIT=0; if AES stores exact values in A, it must leave INIT unchanged. When AES is called with INIT=2, the values of the algebraic expressions must be stored in E and the derivatives in DA, DP, and DT.
• A(n) The amount in the nth compartment at time T.

Output argument:

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

Also see variables in NONMEM modules, NONMEM-PRED modules, particularly DES AES: ICALL,IDEFD,IDEFA.

REFERENCES: Guide IV, section V.C.8 , V.C.9

For use with ADVAN 6,8,9,13,14,15,16,17,18, called by PREDPP to evaluate right-sides of differential equations.

1
2
3
4
5

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

In general, a system of differential equations has the form

$$ \frac{dA(t)}{dt}=g(A(t), p, t). $$

Here both left-hand-side (LHS) and right-hand-size (RHS) are vectors of dimention n: \(A=[A_1, \dots, A_n]^T\), \(g=[g_1, \dots, g_n]^T\). A denotes the drug amount in all compartments except the output compartment, \(p\) the internal PK parameters, and \(t\) the time. For example, for the one compartment model with linear elimination and absorption from a drug depot (ADVAN2) we have $$ n=2,\quad p=[K_e, K_a]^T,\quad g_1=-K_aA_1,\quad g_2=K_aA_1-K_eA_2 $$

The above arguments are the input arguments for the DES routine. The routine's output argument DADT stores the evaluation of \(g()\).

Input argument:

• A(n): the amount in the nth compartment at time T.
• P(n): the value of the nth PK parameter.
• T: time. T takes values continuously over an integration interval.

Output argument:

• DADT(n) The derivative with respect to T of the nth compartment's amount. It is important to note that PREDPP itself adds in the rates for any infusions that may be active.

  For example, the above equations for ADVAN2 can be coded as:

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

• DA(i,j) The derivative of \(g_i()\) with respect to A(j). Continuing the above example,

  1 2 3

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

• DP(i,j) The derivative of \(g_i()\) with respect to P(j). Continuing the above example,

  1 2 3

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

• DT(n) The derivative of \(g_i()\) with respect to T.

The full implementation of the above example model is

 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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

  SUBROUTINE DES (A,P,T,DADT,IR,DA,DP,DT)
    USE NMPRD4P
    USE SIZES, ONLY: DPSIZE,ISIZE
    USE PRDIMS, ONLY: GPRD,HPRD,GERD,HERD,GPKD
    USE NMPRD_INT, ONLY: MSEC=>ISECDER,MFIRST=>IFRSTDER,IFIRSTEM,IFIRSTEMJAC,FIRSTEM
    USE PRCOM_INT, ONLY: DES_DER=>MITER
    USE NMPRD_INT, ONLY: MDVRES,ETASXI,NPDE_MODE,NOFIRSTDERCODE
    USE NMPRD_REAL, ONLY: DV_LOQ,CDF_L,DV_LAQ,CDF_LA
    USE PRMOD_INT, ONLY: ICALL=>ICALLD,IDEFD,IDEFA
    USE NMBAYES_REAL, ONLY: ADDL_ACTUAL,ADDL_TIMEDIFF,ADDL_TIME
    IMPLICIT REAL(KIND=DPSIZE) (A-Z)
    SAVE
    INTEGER(KIND=ISIZE) :: IR
    DIMENSION :: A(*),P(*),DADT(*),DA(IR,*),DP(IR,*),DT(*)
    INTEGER(KIND=ISIZE) :: IFIRSTEMJACIN
    FIRSTEM=IFIRSTEM
    IF(DES_DER==1.OR.DES_DER==4) FIRSTEM=1
    IFIRSTEMJACIN=IFIRSTEMJAC
    IF(NOFIRSTDERCODE/=1) THEN
       IFIRSTEMJAC=FIRSTEM
    ELSE
       IFIRSTEMJAC=0
    ENDIF
    IF(IFIRSTEMJACIN==-2) RETURN
    IF (ICALL == 1) THEN
       CALL ASSOCNMPRD4
       IDEFD(1)= 0
       RETURN
    ENDIF
    ! level 0
    ! level 0
    DADT(1)=-P(002)*A(1)
    DADT(2)=P(002)*A(1)-P(001)*A(2)
    IF (FIRSTEM == 1) THEN ! 1
       ! E000004 = DERIVATIVE OF DADT(1) W.R.T. A(001)
       E000004=-P(002)
       ! F000081 = DERIVATIVE OF DADT(1) W.R.T. P(002)
       F000081=-A(1)
       ! E000005 = DERIVATIVE OF DADT(2) W.R.T. A(001)
       E000005=P(002)
       ! E000006 = DERIVATIVE OF DADT(2) W.R.T. A(002)
       E000006=-P(001)
       ! F000082 = DERIVATIVE OF DADT(2) W.R.T. P(002)
       F000082=A(1)
       ! F000083 = DERIVATIVE OF DADT(2) W.R.T. P(001)
       F000083=-A(2)
    ENDIF !1
    IF (FIRSTEM == 1) THEN !3
       DA( 1, 1)=E000004
       DA( 2, 1)=E000005
       DA( 2, 2)=E000006
       DP( 1,002)=F000081
       DP( 2,001)=F000083
       DP( 2,002)=F000082
    ENDIF !3
    RETURN
  END SUBROUTINE DES

See variables for module variables involved in the code.

The format of arrays DA, DP, DT described above is called "full format". It is the default format. Alternately, compact format may be used. See Guide VI, Appendix IV. Compact Arrays in DES.

Also see variables in NONMEM modules, NONMEM-PRED modules, and PREDPP modules, particularly DES AES: ICALL,IDEFD,IDEFA.

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

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

  ! With NONMEM v7.2+:
  SUBROUTINE ERROR (ICALL,IDEF,THETA,IREV,EVTREC,NVNT,INDXS,F,G,HH)
    USE SIZES,     ONLY: DPSIZE,ISIZE
    USE PRDIMS,    ONLY: GERD,HERD
    IMPLICIT REAL(KIND=DPSIZE) (A-Z)
    REAL(KIND=DPSIZE) :: EVTREC
    INTEGER(KIND=ISIZE) :: ICALL,IDEF,IREV,NVNT,INDXS
    DIMENSION :: IDEF(*),THETA(*),EVTREC(IREV,*),INDXS(*)
    REAL(KIND=DPSIZE) :: G(GERD,*),HH(HERD,*)

The ERROR subroutine is called by PREDPP to model intra-individual error in observed values. It can also be used to to convert predictions from PREDPP, i.e., scaled drug amounts, to other types of predictions (for example, to obtain the prediction of a drug effect as a function of concentration, in a pharmacodynamic study).

Input argument:

• ICALL: see ICALL above for general discussions.

  • ICALL=1: ERROR is being called for initialization at the beginning of a NONMEM problem; one such call per problem. EVTREC contains the first event record. THETA contains the initial estimates. ERROR must return values in IDEF which inform PREDPP what tasks it will perform at later calls. It may also set elments of HH to the appropriate derivatives, when it has requested that ERROR be called only once per problem.
  • ICALL=2: ERROR has been called to obtain the modeled value; multiple calls occur. ERROR should compute derivatives of prediction F to be stored in HH. If ERROR changes F, it should also change the derivates of F in G.
  • ICALL=4: ERROR has been called during the Simulation Step; multiple calls occur. ERROR should compute simulated observations and store them in F.
  • ICALL=5: ERROR has been called during the computation of expectations; multiple calls occur. Such calls occur when the marginal (MRG_) data item is defined in the data set and has non-zero values for some records. If the MRG_ data item has the value 1 or 2, expectations are computed for that record, and the value returned by ERROR in F contributes to the expectation that is being computed for the PRED data item. The value of an ERRORdefined item contributes to the expectation computed for the item.
  • ICALL=6: ERROR has been called during the computation of raw data averages; multiple calls occur. Such calls occur when the rawdata (RAW_) data item is defined in the data set and has the value 1 for some records (See template). ERROR may re-compute DV when the value of DV in the data record is not the quantity to be included in the average. ERROR may return a value of 1 in F if no DV item is to be included in the average with the particular record.
• THETA The NONMEM THETA vector.
• EVTREC The PREDPP event record.
• INDXS The values specified in the $INDEX record of the NM-TRAN control stream. (This is the NONMEM INDXS array starting at position 12, the first position beyond those positions used by PREDPP itself.)

Output argument:

• IDEF ERROR should store values in IDEF only when ICALL=1. A value of 1 in IDEF(1) indicates that ERROR will store the derivatives of log y in HH (which causes PREDPP to multiply each element of HH by F). That is, PREDPP understands that the "error in log y" is modeled.

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

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

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

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

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

Input/Output argument:

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

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

1
2
3
4
5
6

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

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

The INFN subroutine is called by PREDPP to make initialization and finalization computations. The dummy distributed with PREDPP may be replaced by a user-written code.

Input/Output argument:

• ICALL

  • ICALL=-1: INFN may set PRED_IGNORE_DATA=1 for records to be dropped. The following is required:

    1	USE NMPRD_INT, ONLY: PRED_IGNORE_DATA,PRED_IGNORE_DATA_TEST

    The option $DATA PRED_IGNORE_DATA option is required to cause NONMEM to make a PRED_IGNORE_DATA pass.

  • ICALL=0: INFN may now make computations for run initialization. ICALL may be reset by INFN to a number in the range 1-8999. This number will appear on NONMEM output, allowing the user to identify the INFN routine being used.
  • ICALL=1: INFN may now make computations for problem initialization.
  • ICALL=3: INFN may now make computations for problem finalization. If there are subproblems, first do subproblem finalization, if required. Then test for IREP=NREP (the number of the current subproblem equals the total number of subproblems), and if true, do problem finalization. Values of IREP and NREP may be found in NONMEM modules (See Simulation: NREP,IREP).

INPUT ARGUMENTS:

• DATREC DATREC contains the first data record of the current problem. (at icall=0, the current problem is the first problem.) using pass (see below), the contents of datrec are replaced by other data records for the current problem, allowing all these other records to be read and even modified.
• THETA The NONMEM THETA vector. At ICALL=0, THETA contains the initial estimates for the first problem. At ICALL=1, THETA contains the initial estimates for the current problem. At ICALL=3, THETA contains the final estimates for the current problem.
• INDXS The values specified in the $INDEX record of the NM-TRAN control stream. (This is the NONMEM INDXS array starting at position 12, the first position beyond those positions used by PREDPP itself.)
• NWIND NWIND has value 0 when INFN is called. It changes value during a pass through the data using PASS (see below). NWIND=0: First record of the data set. NWIND=1: First record of a subsequent individual record. NWIND=2: Subsequent data record of an individual record.

EXAMPLES OF USAGE:

• Initialization: constants in the PK routine can be set if they are stored in a module or common block declared both in INFN and PK.
• Transgeneration: the data can be accessed and even modified via use of the NONMEM utility routine PASS in routine INFN. As the data records are passed one-by-one to INFN, each record is stored in turn in DATREC. Data can be transgenerated and additional data items can be produced at both initialization and finalization. Data items that appear in a table or scatterplot with a given subproblem or problem are produced or left unchanged at the subproblem or problem finalization. At finalization estimates of the eta's can be obtained via the NONMEM utility routine GETETA. When used in conjunction with PASS, the values returned for the eta's with each call to GETETA are appropriate for the individual whose data record is currently in DATREC.
• Interpolation: as an example of transgeneration, interpolated values of a covariate can be computed for event records in which values are missing, e.g. for other-type event records that have been included so that predictions can be obtained at the times in these records. This could also be done in PK or ERROR, but then this would be done with every call to these routines; if done in INFN, the computation is done once only. (See Infn interpolation example).

USAGE:

1
2
3
4
5
6
7
8
9

      SUBROUTINE MIX (ICALL,NSPOP,P)
      USE SIZES, ONLY: ISIZE,DPSIZE,LTH
      USE ROCM_REAL, ONLY: THETA=>THETAC
      INTEGER(KIND=ISIZE), INTENT(IN) :: ICALL
      INTEGER(KIND=ISIZE), INTENT(OUT) :: NSPOP
      REAL(KIND=DPSIZE),   INTENT(OUT) :: P(*)

GLOBAL DECLARATION:
      REAL(KIND=DPSIZE) :: THETAC(LTH)

MIX is a NONMEM routine that is replaced by a user-supplied routine when a mixture model is used. The MIX subroutine is used to describe the mixture parameters of a mixture model. It is called by NONMEM with one individual record after another.

Input argument:

• ICALL Similar to ICALL for PRED subroutine.

Output argument:

• NSPOP: an integer variable or integer constant. The maximum number of sub-populations that are possible. Must be given a value when ICALL=1.
• P: an array. For each i (i=1, … , NSPOP), P(i) gives the modeled fraction of the population in the ith subpopulation. The sum of the P(i) should equal 1. In principle, the P(i) can change from individual to individual. If for a given individual, the second (for example) subpopulation doesn't apply, then set P(2)=0 for that individual.

Other inputs are available to MIX in NONMEM read-only global variables. In particular, data items that are requested using the $CONTR record, and the current value of THETA, as shown above. (See MIX:DATA, CONTR_MIX:THETA).

The MIX CONTR: TEMPLT data record in a NONMEM read-only global variable also serves to provide an additional way for individual-specific information to be made available.

See also MIXNUM, MIXEST and MIXP.

See mixture model example for using $MIX and MIX.

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

! USAGE:
 SUBROUTINE MODEL(IDNO,NCM,NPAR,IR,IATT,LINK)
 USE PRMOD_CHAR, ONLY: NAME
 USE SIZES,     ONLY: DPSIZE,ISIZE
 INTEGER(KIND=ISIZE) :: IDNO,NCM,NPAR,IR,IATT,LINK
 DIMENSION :: IATT(IR,*),LINK(IR,*)

! GLOBAL DECLARATION:
! Versions before NONMEM 7.4:
 CHARACTER(LEN=8) :: NAME(PC)
! Versions NONMEM v7.4+:
 USE SIZES,     ONLY: SD
 CHARACTER(LEN=SD) :: NAME(PC)

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

Input argument: None.

Output argument:

• IDNO: An identification number for the MODEL routine. The value assigned by MODEL to IDNO is printed on the first PREDPP problem summary page. The user may have several MODEL routines and use different ones for different runs. The routine used in a particular run can be identified from the output. For this to happen, an integer identification value should be assigned by MODEL to the variable IDNO. This value will be printed on the first PREDPP problem summary page. When NM-TRAN abbreviated code is used, IDNO is set to 9999.
• NCM: the total number of compartments in the model, excluding the output compartment. Contains 0 when MODEL is called. NCM must be no greater than PC-1.
• NPAR: basic PK parameters exist for general linear and nonlinear models as they do for more specific models. A TRANS routine is used which translates the set of basic PK parameters whose values are computed in the PK routine to a set of parameters used internally by the ADVAN routine. The maximum number of basic PK parameters to be used in any TRANS routine is specified by assigning this number to the variable NPAR. NPAR may be 0, e.g., when only THETA and data record items are used in differential equations. The maximum number of basic PK parameters plus the number of additional parameters whose row indices are given explicitly in PK (at ICALL=1) cannot exceed PG, a constant in SIZES.f90 which is given by PARAMETER (PG=50+PCT), where PCT is the maximum number of model event time parameters given by PARAMETER (PCT=30) Both these parameters can be changed with the $SIZES record. With the general non-linear models (ADVAN6, ADVAN8, ADVAN9, ADVAN13, ADVAN14, ADVAN15, ADVAN16, ADVAN17, ADVAN18), NPAR may remain 0.

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

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

  Most pharmacokinetic models involve only nonequilibrium compartments, compartments such that the amounts of drug in them can be given by a solution to a system of differential equations. However, some ADVAN routines - ADVAN9, ADVAN15, ADVAN17 - allow a model (a general nonlinear model) to be comprised of both nonequilibrium and equilibrium compartments. Equilibrium compartments are, roughly speaking, compartments such that at any time the amounts of drug in them can be given by a solution to a system of algebraic equations. These ADVAN routines allow the user to define a model consisting only of equilibrium compartments, in which case the ADVAN becomes a purely algebraic equation solver. The quantities A(i) may be thought of as unknowns to be determined rather than as "compartment" amounts. Records with EVID=1 and EVID=4 (dose, reset and dose) may not be present in the data set because doses cannot be placed in equilibrium compartments. Similarly, data items related to doses (RATE, AMT, SS, II, ADDL) may or may not be used in the data set. If used, they must contain null values. The TIME data item is optional. If TIME is used, ADVAN is called exactly as other ADVAN routines are called: when the value of TIME increases. If TIME is not defined, AES routine specifies the calling protocol for ADVAN: call with every event record (the default) or once per individual record (see section E.C). If calls to ADVAN are limited, the CALL data item may be defined in the data set and given the value 10 to force additional calls to ADVAN (see chapter V, section J). There are two additional attributes to which values must be given only when these ADVAN routins are used. The first of these simply identifies the compartment as an equilibrium compartment or not. The second of these relates to the output compartment. The amount of drug in the output compartment at time t is given by A+B-C, where A is the total amount in the system at s, the time the compartment is turned on, B is the total amount of drug input to the system between times s and t, and C is the total amount in the system at time t. If an equilibrium compartment represents a subcompartment, i.e. the amount D of drug in the compartment is part of the amount of drug in another compartment, D should be excluded from A and C. The attribute in question is concerned with whether D should or should not be excluded from A and C. The settings below is used only with ADVAN9, ADVAN15, and ADVAN17:

  • IATT(I,8)=0 not an equilibrium compartment
  • IATT(I,8)=1 an equilibrium compartment
  • IATT(I,9)=0 should not be included in the total drug amount in the system interior
  • IATT(I,9)=1 should be included in the total drug amount in the system interior
• NAME: labels for the compartments (to be printed on the PREDPP summary page under "FUNCTION"). NAME(I) is the label for compartment i. With versions before NONMEM 7.4, NAME was limited to 8 characters. With NONMEM 74 NAME may be up to SD characters long. SD is defined in SIZES and is set to 30 with NONMEM 7.4.

• LINK: Only used with general linear models (ADVAN5 and ADVAN7). The internal parameters of these models are the rate constants. The user assigns each rate constant a number, any number between 1 and the value assigned to NPAR. The numbering is estab- lished using the LINK array. LINK is a two-dimensional integer array. If no drug can distribute from the Ith compartment to the Jth compartment, then one can assign 0 to LINK(I,J), or not bother assigning any value to LINK(I,J). In particular, LINK(I,I) should always be ignored. If drug can distribute from the Ith compartment to the Jth compartment, then one assigns to LINK(I,J) the number of the rate constant quantifying this (first- order) distribution. The LINK array should, in particular, account for the distribution of drug from com- partment I to the output compartment. That is, if such distribution can take place, then a number should be assigned to LINK(I,NCM+1). The numbers of the rate constants need not start with the number 1, and they need not be consecutive, i.e. numbers may be skipped. Moreover, two rate constants can be assigned the same number; this forces their values and η-derivatives to be the same. With NM-TRAN, there are two ways to specify LINK. When the $PK abbreviated code is used, link relationships are implied by variable names such as Kij or KiTj (where "T" stands for "TO"). When a user-supplied PK is used, the LINK relationships must be specified explicitly on the $MODEL record using options such as Kij.

  With a general nonlinear model the user explicitly specifies by DES. These equations are parameterized in terms a set of internal kinetic parameters. The LINK array plays no role with a general nonlinear model. The internal parameters are numbered between 1 and the number assigned to NPAR. The rules concerning internal parameter numbering are the same as given above for rate constant numbering.

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

Example below uses MODEL routine to specify the one compartment linear model with first order absorption, just as with ADVAN2.

 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
29
30
31
32
33
34
35
36
37
38
39
40

  ! DEFINES A 1 COMPARTMENT LINEAR MODEL WITH FIRST-ORDER ABSORPTION
  ! COMPT1: DRUG DEPOT COMPT2: CENTRAL COMPT
  !
  SUBROUTINE MODEL (IDNO,NCM,NPAR,IR,IATT,LINK)
    USE PRMOD_CHAR, ONLY: NAME
    USE SIZES, ONLY: DPSIZE,ISIZE,SD
    USE PRDIMS, ONLY: GPRD,HPRD,GERD,HERD,GPKD
    INTEGER(KIND=ISIZE) :: IDNO,NCM,NPAR,IR,IATT,LINK,I,J
    DIMENSION :: IATT(IR,*),LINK(IR,*)
    SAVE
    INTEGER(KIND=ISIZE), DIMENSION (2,7) :: MOD
    CHARACTER(LEN=SD), DIMENSION(2) :: CMOD
    DATA (MOD(I, 1),I= 1, 2)/&
         ! INITIAL STATUS: OFF ON
         0,1 /
    DATA (MOD(I, 2),I= 1, 2)/&
         ! ON/OFF ALLOWED: YES NO
         1,0 /
    DATA (MOD(I, 3),I= 1, 2)/&
         ! DOSE ALLOWED: YES YES
         1,1 /
    DATA (MOD(I, 4),I= 1, 2)/&
         ! DEFAULT FOR OBSERVATIONS: NO YES
         0,1 /
    DATA (MOD(I, 5),I= 1, 2)/&
         ! DEFAULT FOR DOSES: YES NO
         1,0 /
    DATA (MOD(I, 6),I= 1, 2)/&
         0,0 /
    DATA (MOD(I, 7),I= 1, 2)/&
         0,0 /
    DATA (CMOD(I),I= 1, 2) &
         /’DEPOT’,’CENTRAL’/
    FORALL (I=1:2) NAME(I)=CMOD(I)
    FORALL (I=1:2,J=1:7) IATT(I,J)=MOD(I,J)
    IDNO=9999
    NCM= 2
    NPAR=002
    RETURN
  END SUBROUTINE MODEL

For another example, we implement the MODEL routine for the following $MODEL block

1
2

$MODEL COMP=(DEPOT,NOOFF,DEFDOSE) COMP=(CENTRAL NOOFF NODOSE)
COMP=(EFFECT, NOOFF NODOSE DEFOBS)

 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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

  ! DEFINES A 3 COMPARTMENT MODEL
  ! COMPT1: DRUG DEPOT COMPT2: CENTRAL COMPT COMPT3: EFFECT COMPT
  !
  SUBROUTINE MODEL (IDNO,NCM,NPAR,IR,IATT,LINK)
    USE PRMOD_CHAR, ONLY: NAME
    USE SIZES, ONLY: DPSIZE,ISIZE,SD
    USE PRDIMS, ONLY: GPRD,HPRD,GERD,HERD,GPKD
    INTEGER(KIND=ISIZE) :: IDNO,NCM,NPAR,IR,IATT,LINK,I,J
    DIMENSION :: IATT(IR,*),LINK(IR,*)
    SAVE
    INTEGER(KIND=ISIZE), DIMENSION (3,7) :: MOD
    CHARACTER(LEN=SD), DIMENSION(3) :: CMOD
    DATA (MOD(I, 1),I= 1, 3)/&
         ! INITIAL STATUS: ON ON ON
         1,1,1 /
    DATA (MOD(I, 2),I= 1, 3)/&
         ! ON/OFF ALLOWED: NO NO NO
         0,0,0 /
    DATA (MOD(I, 3),I= 1, 3)/&
         ! DOSE ALLOWED: YES NO NO
         1,0,0 /
    DATA (MOD(I, 4),I= 1, 3)/&
         ! DEFAULT FOR OBSERVATIONS: NO NO YES
         0,0,1 /
    DATA (MOD(I, 5),I= 1, 3)/&
         ! DEFAULT FOR DOSES: YES NO NO
         1,0,0 /
    DATA (MOD(I, 6),I= 1, 3)/&
         0,0,0 /
    DATA (MOD(I, 7),I= 1, 3)/&
         0,0,0 /
    DATA (CMOD(I),I= 1, 3) &
         /’DEPOT’,’CENTRAL’,’EFFECT’/
    FORALL (I=1:3) NAME(I)=CMOD(I)
    FORALL (I=1:3,J=1:7) IATT(I,J)=MOD(I,J)
    IDNO=9999
    NCM= 3
    NPAR=004
    ! SET LINK:
    ! K12
    LINK( 1,002)=001
    ! K23
    LINK( 2,003)=003
    ! K20
    LINK( 2,004)=002
    ! K30 (KEO)
    LINK( 3,004)=004
    RETURN
  END SUBROUTINE MODEL

(See SIZES).

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

USAGE: before NONMEM 7.2:

1
2
3
4
5
6

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

With NONMEM 7.2 and higer:

1
2
3
4
5
6
7
8

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

The PK subroutine is called by PREDPP to obtain values for basic and additional pharmacokinetic parameters. Basic PK parameters are typically the rate constants ("micro-constants") for use in kinetic formula. PK can compute instead parameters such as clearance and volume, and a translator ("TRANS") subroutine can be used to convert these to rate constants. Additional PK parameters include compartment scale parameters, which PREDPP uses to convert compartment amounts to concentrations, and dose-related parameters such as modeled infusion rates.

Input argument:

• ICALL: see ICALL above for general discussions.

  • ICALL=1: PK routine is being called for the first time in the NONMEM problem. At such a time PK must store certain information in array IDEF, and optionally certain information in GG.
  • ICALL=2: PK routine is being called for regular data analysis and that values of PK parameters are to be stored in the first column of GG. These can be typical (population mean) values , or they can be subject-specific values. In addition, partial derivatives are also stored. see sections D and E.
  • ICALL=4: PK routine is being called for regular data simulation. If the data are population data, simulated subject-specific PK parameters values are to be stored in the first column of GG; see section E.2. However, if the data are all from a single subject, so that the subject’s specific values are synonomous with the typical values, then typical values are stored in this column.
  • ICALL=5: PK routine is being called for regular expectations computation. Multiple calls can occur. See Expectation blocks. In this case no ETA derivatives are needed.

If there is abbreviated code in the $PK block conditional on ICALL=0, ICALL=1, or ICALL=3, the code is transcribed to the INFN routine as part of an $INFN block.

• THETA: the NONMEM THETA vector.
• EVTREC: the PREDPP event record. See EVTREC.
• INDXS: the values specified in the $INDEX record of the NM-TRAN control stream. (This is the NONMEM Index array starting at position 12, the first position beyond those positions used by PREDPP itself).
• NETAS: the number of population ETAs in the problem.

Output argument:

• IDEF: stores values only when ICALL=1. Values may be stored in the following elements:

  • IDEF(1,1)=-9 (required)

  • IDEF(1,2) is the call limiting element (compare $PK's CALLFL). Values are:

    • -2: call with every event record and at additional and lagged dose times.
    • -1: call with every event record (default)
    • 0: call with first event record and new TIME values
    • 1: call once per individual record

    Compartment initialization may be performed by routine PK.

    An initial steady state may be requested by routine PK;

    (See Initial Steady State: I_SS,ISSMOD).

  • IDEF(1,3) describes whether PK performs compartment initialization, i.e., whether or not PK initializes elements of the initial state vector A_0(n). Values are:

    • -1: PK may initialize A_0.
    • 0: PK does not initialize A_0.
    • 1: PK does initialize A_0.

    The default used by PREDPP is IDEF(1,3)=-1. However, when compartment initialization is not implemented, then if IDEF(1,3) is set to 0, PREDPP can avoid some time-consuming processing. Indeed, when $PK abbreviated or verbatim code is supplied, and there is no reference to compartment initialization amounts A_0(n) in either the abbreviated or verbatim code, then NM-TRAN sets IDEF(1,3)=0.

    Compartment amounts may be used by routine PK (See State Vector A).

  • IDEF(1,4) describes whether PK uses derivatives of compartment amounts (e.g. compartment amounts themselves are used as random variables in arithmetic statements in PK). Values are:

    • -1: PK may use derivatives of compartment amounts.
    • 0: PK does not use derivatives of compartment amounts.
    • 1: PK uses derivatives of compartment amounts.

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

  • Remaining elements contain row numbers in GG:

    • IDEF(2,1): row number of F0 (output fraction)
    • IDEF(2,2): row number of XSCALE (Time Scale)
    • IDEF(2,3): row number of lowest-numbered MTIME
    • IDEF(2,4): row number of highest-numbered MTIME
    • IDEF(3,n): row number of Sn (Scale for comp. n) (thru n+1 output)
    • IDEF(4,n): row number of Fn (bioavailability fraction for comp. n)
    • IDEF(5,n): row number of Rn (modeled rate for comp. n)
    • IDEF(6,n): row number of Dn (modeled duration for comp. n)
    • IDEF(7,n): row number of ALAGn (absorption lag for comp. n)

• GG: the array of PK parameters and their eta derivatives, initialized to zero immediately before PK calls. The maximum number of rows in GG is given by IRGG, which is the same as constant PG found in file SIZES (See SIZES).

  • At ICALL = 2:

    • GG(k,1,1) contains the value of the k'th parameter;
    • GG(k,i+1,1) contains its derivative with respect to the ETA(i);
    • GG(k,i+1,j+1) contains its second derivative with respect to ETA(i) and ETA(j) (lower-triangular; j=1, …, i). Recall that second derivatives are only needed with METHOD=LAPLACE, therefore GG may be declared as a two-dimensional array GG(IRGG,*) when the Laplacian method is not used.
  • At ICALL = 4: GG(k,1,1) contains the individual-specific value of the k'th parameter. Since ICALL=4 indicates simulation, other columns of GG for partial derivatives need not be computed.
  • At ICALL = 1: GG(k,1,1)=[0|1] specifies transformation of the values that will be stored at GG(k,1,1) during calls with ICALL=2 or 4. GG(k,1,1)=0 means no transformation, while GG(k,1,1)=1 indicates GG(k,1,1) will store a log-transformed parameter value.

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

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

! Versions before NONMEM 7.2:
 SUBROUTINE PRED (ICALL,NEWIND,THETA,DATREC,INDXS,F,G,H)
 USE SIZES,     ONLY: DPSIZE,ISIZE,LVR
 REAL(KIND=DPSIZE) :: DATREC
 INTEGER(KIND=ISIZE) :: ICALL,NEWIND,INDXS
 DIMENSION :: THETA(*),DATREC(*),INDXS(*),G(LVR,*),H(LVR,*)

! NONMEM v7.2+:
 SUBROUTINE PRED (ICALL,NEWIND,THETA,DATREC,INDXS,F,G,H)
 USE SIZES, ONLY: DPSIZE,ISIZE
 USE PRDIMS,ONLY: GPRD,HPRD,GERD,HERD,GPKD
 IMPLICIT REAL(KIND=DPSIZE) (A-Z)
 REAL(KIND=DPSIZE) :: DATREC
 INTEGER(KIND=ISIZE) :: ICALL,NEWIND,INDXS
 REAL(KIND=DPSIZE) :: G(GPRD,*),H(HPRD,*)
 DIMENSION :: THETA(*),DATREC(*),INDXS(*)

The PRED subroutine is called by NONMEM to obtain modeled values. PREDPP is a special PRED subroutine that is distributed with NONMEM, for common Population PK models.

Input argument:

• ICALL

  • ICALL=-1: the routine has been called for the PRED_IGNORE_DATA feature (NM75). One call per data record, at the start of the run. These calls occur only if abbreviated code uses variables PRED_IGNORE_DATA or PRED_IGNORE_DATA _TEST, or if the PRED_IGNORE_DATA option of $DATA is used. Otherwise, there are no calls to PRED with ICALL=-1.
  • ICALL=0: PRED has been called for initialization purposes at the beginning of the NONMEM run; one such call per run. DATREC contains the first data record. THETA contains the initial estimates. PRED need not compute F, G, or H.
  • ICALL=1: PRED has been called for initialization purposes at the beginning of a NONMEM problem; one such call per problem. Otherwise, identical to ICALL=0.
  • ICALL=2: For the data record contained in DATREC, PRED has been called for the purpose of computing F, the value of the prediction, and/or the values of other PRED-defined items, appropriate for the record. PRED should compute F, and also G and H as appropriate. THETA contains the values to be used to compute F. With conditional estimation, to obtain ETA values, PRED should call GETETA.
  • ICALL=3: PRED has been called for finalization purposes at the end of a NONMEM problem; one such call per (sub)problem. DATEC contains the first data record. THETA contains the final estimates. Otherwise, identical to ICALL=0.
  • ICALL=4: For the data record contained in DATREC, PRED has been called during the Simulation Step for the purpose of computing a value of the dependent variable and, possibly, values of independent variables, appropriate for the record. PRED should compute F (the value of the dependent variable). THETA contains the initial estimates, which are the values to be used to compute F. PRED should call SIMETA (and SIMEPS) to obtain simulated values of ETA (and EPS).
  • ICALL=5: For the data record contained in DATREC, PRED has been called for the purpose of computing the expectation of the PRED item and possibly, the expectations of other PRED-defined items, appropriate for the record. Such a call occurs when the marginal data item (MRG_) is defined in the data set and has a non-zero value for the data record in question. If the MRG_ data item on the record has the value 1 or 2, the value returned by PRED in F contributes to the expectation of the PRED item. Similarly, the values returned in other PRED-defined items contribute to expectations of these items. THETA contains the final estimates. The expectations in question are over possible values of ETA, and to obtain ETA values, PRED should call GETETA.
  • ICALL=6: PRED has been called for the purpose of computing the raw data average of the DV data items and, possibly, the raw data averages of PRED-defined items. Such a call occurs when the raw-data data item (RAW_) is defined in the data set and has a non-zero value for a template data record (See template). The value of the DV data item in the data record contained in DATREC will be included in the raw data average of the DV data items. However, when the raw data average corresponding to the label DV in a table or scatterplot is to be different from the raw data average of the DV items themselves, PRED may recompute the value of DV. PRED may return a value of 1 in F to omit the DV item in the data record from the average.

• NEWIND

  • NEWIND=0: First record of the data set. THETA value may differ from value at last call with this record.
  • NEWIND=1: First record of the data set, THETA value does not differ from value at last call with this record, and PRED is nonrecursive (see I_REC), or, First record of a subsequent individual record.
  • NEWIND=2: Subsequent data record of an individual record.
• THETA: the NONMEM THETA vector.
• DATREC The current data record.
• INDXS The values specified in the $INDEX record of the NM-TRAN control stream.

Output argument:

• F When ICALL=2, the prediction associated with the data record. With discrete data, the likelihood of the observation in the record, but if there is no observation, F is ignored. When ICALL=4, the value of the simulated observation associated with the data record. Alternatively, F can be ignored, and the DV item in the data record can be directly set to the value of the simulated observation. With discrete data, F is ignored; PRED should directly set the DV item to the value of the simulated observation.
• G An array of derivatives of F with respect to ETAs. Values should be set when ICALL=2. G(i,1) is the partial derivative of F with respect to eta(i). When the data are population, G(i,j+1) is the second partial derivative of F with respect to eta(i), eta(j) (lower-triangular; j=1,…, i). Second derivatives are needed only when the Laplacian method is used to estimate parameters.
• H An array of partial derivatives of F with respect to EPSILONs. When the data are population, values should be set when ICALL=2. H(i,1) is the derivative of F with respect to eps(i). H(i,j+1) is the partial derivative of H(i,1) with respect to eta(j) These mixed second derivatives are needed only when the INTERACTION option isused to estimate parameters. (See $ESTIMATION).

Also see variables in NONMEM modules.

1
2
3

    USE SIZES, ONLY: DPSIZE,LVR
    REAL(KIND=DPSIZE):: EPS(LVR)
    CALL SIMEPS (EPS)

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

  ! ERROR ROUTINE FOR THE PHENOBARB POPULATION DATA
  ! ILLUSTRATING DATA SIMULATION
  ! EXPONENTIAL ERROR MODEL
  !
  SUBROUTINE ERROR (ICALL,IDEF,THETA,IREV,EVTREC,NVNT,INDXS,F,G,HH)
    USE SIZES, ONLY: DPSIZE,ISIZE
    USE PRDIMS, ONLY: GERD
    USE NMPRD_REAL,ONLY: EPS
    IMPLICIT REAL(KIND=DPSIZE) (A-Z)
    REAL(KIND=DPSIZE) :: EVTREC
    INTEGER(KIND=ISIZE) :: ICALL,IDEF,IREV,NVNT,INDXS
    DIMENSION :: IDEF(*),THETA(*),EVTREC(IREV,*),INDXS(*)
    REAL(KIND=DPSIZE) :: G(GERD,*),HH(*)
    IF (ICALL.EQ.2) HH(1)=F
    IF (ICALL.EQ.4) THEN
       CALL SIMEPS (EPS)
       F=F*EXP(EPS(1))
    ENDIF
    RETURN
  END SUBROUTINE ERROR

1
2
3
4

! USAGE:
      USE SIZES, ONLY: DPSIZE,LVR
      REAL(KIND=DPSIZE):: ETA(LVR)
      CALL SIMETA (ETA)

1
2
3
4
5

    IF (ICALL.EQ.4.AND.NEWIND.NE.2) THEN
       DO WHILE (ABS(ETA(2)).GT.5)
          CALL SIMETA (ETA)
       ENDDO
    ENDIF

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

    IF (ICALL.EQ.4.AND.NEWIND.NE.2) THEN
       DO WHILE (ABS(ETA(2)).GT.5)
          CALL SIMETA (ETA)
       ENDDO
       ETA2=ETA(2)
       DO WHILE (ABS(ETA(1)).GT.0.52)
          CALL SIMETA (ETA)
       ENDDO
       ETA1=ETA(1)
    ENDIF

1
2
3
4
5
6
7

    IF (ICALL.EQ.4.AND.NEWIND.NE.2) THEN
       DO WHILE(ABS(ETA(2)).GT.5.OR.ABS(ETA(1)).GT.0.52)
          CALL SIMETA (ETA)
       ENDDO
       ETA2=ETA(2)
       ETA1=ETA(1)
    ENDIF

USAGE:

1
2
3
4

      SUBROUTINE PRIOR (ICALL,CNT)
      USE SIZES, ONLY: ISIZE,DPSIZE
      INTEGER(KIND=ISIZE), INTENT(IN) :: ICALL
      REAL(KIND=DPSIZE),   INTENT(IN OUT) :: CNT

A user-written PRIOR subroutine allows a penalty function based on a prior to be specified and added to the -2log likelihood function (Gisleskog et al, JPP, 2002, p. 473-505). This serves as a constraint on the estimates of THETA, OMEGA, and SIGMA and thus as a way for stable estimates to be obtained with insufficient data.

When the Simulation Step is implemented, THETA and OMEGA, and SIGMA may also be simulated (along with ETAs and EPSILONs, should any such appear in the model and have nonzero-variances) in the PRIOR subroutine. However, this need not be done (simply execute a return in PRIOR at ICALL=4), in which case the values for THETA, OMEGA, and SIGMA used in the simulation are the values given in the NONMEM control stream or input Model Specification File.

Input argument:

• ICALL Similar to ICALL for PRED subroutine. Possible values: 0, 1, 2, and 4. In a multiple problem run, PRIOR is called with ICALL=1 only with the first problem.

Output argument:

• CNT: the penalty term.

Other Inputs are available to PRIOR in NONMEM read-only modules.

PRIOR may call NONMEM utility routines NWPRI and TNPRI:

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

  SUBROUTINE PRIOR (ICALL,CNT)
    USE SIZES, ONLY: DPSIZE,ISIZE
    REAL (KIND=DPSIZE) :: CNT
    REAL (KIND=DPSIZE) :: PLEV
    INTEGER (KIND=ISIZE) :: ICALL
    NTHETA=3
    NETA=3
    NEPS=1
    NTHP=2
    NETP=2
    NEPP=1
    PLEV=0
    CALL NWPRI (NTHETA,NETA,NEPS,NTHP,NETP,NEPP,NPEXP,ITYP,PLEV, &
         NSAM,ISS,CNT)
    RETURN
  END SUBROUTINE PRIOR

NWPRI and TNPRI compute particular types of penalty functions. NWPRI computes a function based on a prior that has a multivariate normal form for THETA, and also, in the case of population data, an inverse Wishart form for OMEGA (independent from the normal for THETA). When used during a Simulation Step, it produces a random value of THETA and a random value of OMEGA from the prior. The prior information is entered manually into the control stream. This prior is especially useful for a subjective specification of a penalty function. (See NWPRI, TNPRI below).

Model parameters may be constrained in various ways. Those parameters whose values are not fixed are transformed to new parameters whose values are not at all constrained a priori (the "unconstrained parameters", or UCP). TNPRI computes a penalty function based on a prior that has a multivariate normal form for all UCP. When used during a Simulation Step, it produces a random value of the vector of all model parameters (whose values are not fixed). The prior information is found in an input Model Specification File, and it has been automatically stored there as part of a NONMEM analysis of a prior data set. (See also $MSFI). This prior is especially useful for an empirical specification of a penalty function. (See TNPRI).

The $PRIOR statement can be used instead of a PRIOR subroutine. (See $prior.ctl).

1
2
3
4
5
6
7
8

    USE SIZES, ONLY: ISIZE,DPSIZE
    INTEGER (KIND=ISIZE) :: NTHETA,NETA,NEPS,NTHP,NETP,NEPP,NPEXP
    INTEGER (KIND=ISIZE) :: ITYP,NSAM,ISS
    REAL (KIND=DPSIZE), ONLY: CNT
    REAL (KIND=DPSIZE), ONLY: PLEV
    INTEGER (KIND=ISIZE) :: ICALL
    CALL NWPRI (NTHETA,NETA,NEPS,NTHP,NETP,NEPP,NPEXP,ITYP,PLEV, &
         NSAM,ISS,CNT)

1
2
3
4
5
6

 $PRIOR NWPRI NTHETA=3 NETA=3 NTHP=3 NETP=3 NPEXP=1
   ...
 $THETA 3 FIX .08 FIX .04 FIX
 $THETA 100 FIX
 $OMEGA BLOCK (3) .494 .00207 .0000847 .000692 .0000471 .0000292 FIX
 $OMEGA BLOCK (3) .7 .04 .05 .02 .06 .08 FIX

1
2
3
4
5
6
7
8
9

 $PRIOR NWPRI NTHETA=3 NETA=3 NTHP=3 NETP=3 NPEXP=1
   ...
 ;prior information for THETA
 $THETA 3 FIX .08 FIX .04 FIX
 $OMEGA BLOCK (3) .494 .00207 .0000847 .000692 .0000471 .0000292 FIX

 ;prior information for OMEGA
 $OMEGA BLOCK (3) .7 .04 .05 .02 .06 .08 FIX
 $THETA 100 FIX

1
2
3
4
5
6
7
8
9

 $PRIOR NWPRI
   ...
 ;prior information for THETA
 $THETAP 3 FIX .08 FIX .04 FIX
 $THETAPV BLOCK (3) .494 .00207 .0000847 .000692 .0000471 .0000292 FIX

 ;prior information for OMEGA
 $OMEGAP BLOCK (3) .7 .04 .05 .02 .06 .08 FIX
 $OMEGAPD 100 FIX

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

 ;usual records
 $THETA  (0,4,10) (0,.09,.5) (.004,.01,.9)
 $OMEGA BLOCK (3) .7 .04 .05 .02 .06 .08

 ;prior information from experiment 1
 $THETA 3 FIX .08 FIX .04 FIX
 $THETA 100 FIX
 $OMEGA BLOCK (3) .494 .00207 .0000847 .000692 .0000471 .0000292 FIX
 $OMEGA BLOCK (3) .7 .04 .05 .02 .06 .08 FIX

 ;prior information from experiment 2
 $THETA 2 FIX .05 FIX .04 FIX
 $THETA 50 FIX
 $OMEGA BLOCK (3) .6 .003 .0001 .0004 .00001 .00003 FIX
 $OMEGA BLOCK (3) .9 .02 .05 .01 .06 .09 FIX

1
2
3
4
5
6

  USE SIZES, ONLY: ISIZE,DPSIZE
  INTEGER (KIND=ISIZE) :: IFND,MODE,ITYP,NSAM,ISS,IVAR
  REAL (KIND=DPSIZE) :: PLEV
  REAL (KIND=DPSIZE) :: CNT
  REAL (KIND=ISIZE) :: ICALL
  CALL TNPRI (IFND,MODE,ITYP,PLEV,NSAM,ISS,IVAR,CNT)

1
2
3
4
5

! usage
  USE SIZES, ONLY: ISIZE,DPSIZE
  INTEGER(KIND=ISIZE) :: KR
  REAL(KIND=DPSIZE) :: R
  CALL RANDOM (KR,R)

The NONMEM utility routine RANDOM may be called by PRED, PK or ERROR during the Simulation Step (ICALL=4) and data average block (ICALL=5) to obtain numbers from random number generators.

Input argument:

• KR: an integer variable or integer constant. The index of the random source. Random sources are defined using the $SIMULATION record. With standard normal as the default distribution. Typically, the first source is reserved by NONMEM to generate realizations of the ETA and EPSILON variables and/or to randomly mix individuals into different subpopulations according to the mixing parameter. Thus, typically, RANDOM must be called with KR > 1. A random source that is specified on the $SIMULATION record as NONPARAMETRIC should not be used to obtain a value of R.

Output argument:

• R: A number from the KR RNG. R is of double precision since NONMEM 7 but single precision in earlier versions. Each time RANDOM is called, a new R is generated.

An abbreviated code may use RANDOM explicitly in either a simulation or a data average block. When RANDOM is called in abbreviated code, R is reserved and is used for the random number. For example, below WT (a data item and a local variable with the same name) is generated with a simulated value having mean 70 and standard deviation 7.

1
2
3
4

  IF (ICALL.EQ.4.AND.NEWIND.NE.2) THEN
  CALL RANDOM(2,R)
  ENDIF
  IF (ICALL.EQ.4) WT=70+7*R

USAGE:

1
2
3
4
5

      SUBROUTINE SPTWO (ICALL,I1,I2,NROB,D,IER)
      USE SIZES, ONLY: ISIZE,DPSIZE,NO
      INTEGER(KIND=ISIZE), INTENT(IN)     :: NROB,ICALL
      INTEGER(KIND=ISIZE), INTENT(IN OUT) :: I1,I2,IER
      REAL(KIND=DPSIZE),   INTENT(IN OUT) :: D(NO,2)

SPTWO is used to redefine the meaning of the RES and WRES items for observation records within an individual record. It is called with each individual record. The labels 'RES' and 'WRES' can be changed, as usual.

Input argument:

• ICALL Similar to ICALL for PRED subroutine. Possible values: 0, 1, 2
• NROB Number of observation records in the individual record.

Output argument:

• I1,I2: when SPTWO is used, by default, I1 and I2 are 0, meaning zero lines are not to be generated through RES or WRES values on scatterplots. If zero lines through RES or WRES values on scatterplots are desired, SPTWO should set I1 or I2, respectively, to 1.
• D(J,1): Value of RES for Jth observation record, J=1,…,NROB.
• D(J,2): Value of WRES for Jth observation record, J=1,…,NROB
• IER Error indicator. 0 - Normal return; non-zero - error stop.

Other Inputs:

NONMEM read-only global variables.

(See MIX:_DATA)

(See Non-active ETA for PRED)

(See Parameters OMEGA SIGMA: Current)

(See Record_Counters:_NIREC,NDREC)

1
2
3
4
5

 USAGE:
 SUBROUTINE TRANS (ITRANS,IRGG,GG,NETAS)
 USE SIZES, ONLY: ISIZE,DPSIZE,LVR
 INTEGER(KIND=ISIZE) :: IRGG,NPETAS,ITRANS
 REAL(KIND=DPSIZE)   :: GG(IRGG,LVR+1,LVR+1)

The TRANS subroutine translates (or transforms) the values for a set of basic PK parameters modeled in PK to a set of values for the inter nal parameters required by the ADVAN. The PREDPP Library has a number of TRANS subroutines, representing different possible parameterizations in PK, from which the user may choose. If a suitable translator is not found in the Library, the user may write his own.

Input/Output argument:

• ITRANS

  • ITRANS=1: TRANS has been called for initialization at the beginning of a NONMEM problem; one such call per problem. ITRANS must be reset by TRANS to a number in the range 1-8999. This number appears on NONMEM output, allowing the user to identify the TRANS routine being used.
  • ITRANS=2: On input the GG array has stored in it the values computed by PK (except that were any PK parameter modeled in its logarithm form in PK, PREDPP would have already exponentiated its typical/subject-specific value and multiplied its eta derivatives by its exponentiated typical/subject-specific value). On output the GG array should have stored in it the values that would be computed by PK were the internal parameters of the ADVAN modeled directly in PK (and none in their logarithmic form).
  • ITRANS=4: TRANS has been called during the Simulation Step. Only the first column of the GG array need be computed as with ITRANS=2. Other columns need not be computed.
  • GG: the array of PK parameters and their eta derivatives.

Input argument:

• NETAS: the number of population ETAs in the problem.

Certain variables are available in modules. Their use is optional.

• Variables in read/write modules: IERPRD NETEXT ETEXT (See PRED Exit Code, PRED Error Message).
• Variables in read-only commons: NOETAS, SECOND (see Partial Derivative Indicators). When SECOND is true, PREDPP requires second-partial derivatives of ETAs.

REFERENCES: Guide VI, section III.M

 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

  ! Versions before NONMEM 7.4:
  SUBROUTINE TOL(NRD)
  USE SIZES,     ONLY: ISIZE
  INTEGER(KIND=ISIZE) :: NRD
  DIMENSION :: NRD(*)

  ! Example for versions before NONMEM 7.4:
  SUBROUTINE TOL (NRD)
  DIMENSION NRD(*)
  NRD(1)=4
  RETURN
  END

  ! NONMEM v7.4+
  SUBROUTINE TOL(NRD,ANRD,NRDC,ANRDC)
  USE SIZES,     ONLY: ISIZE
  INTEGER(KIND=ISIZE) :: NRD(0:*), ANRD(0:*), NRDC(0:*), ANRDC(0:*)

  ! Example
  SUBROUTINE TOL(NRD,ANRD,NRDC,ANRDC)
  USE SIZES, ONLY: ISIZE
  INTEGER(KIND=ISIZE) :: NRD(0:*), ANRD(0:*), NRDC(0:*), ANRDC(0:*)
  NRD(1)=5
  RETURN
  END

Optional declarations with NONMEM 7.4:

1
2
3

 USE NMPRD_INT, ONLY: IPROB
 USE NM_BAYES_INT, ONLY: NM_STEP,BASE_STEP,EST_STEP,COV_STEP, &
  TABLE_STEP,SIML_STEP,INE_STEP, NONP_STEP

The TOL subroutine is called by PREDPP when ADVAN 6, 8, 9, 10, 13, 14, 15, 16, 17, or 18 is used. It is also called when SS6 or SS9 is used. With NONMEM 7.4, there are multiple calls during the run, for each NONMEM step. With earlier version, TOL is called only once at the start of a run.

Output argument:

• NRD(I): The number of digits that are required to be accurate in the computation of the drug amount in compartment I, i.e., the relative tolerance. ADVAN 9, 13, 16, 17, and 18 have the capability of using different values of NRD for different compartments (ADVAN 14 and 15 only allow different absolute tolerances for each compartment). For compartments not specified, the tolerance of the last compartment specified will be used. However, all the other ADVAN routines requiring TOL take the relative tolerance to be the same for all compartments; NRD(I), I > 1, is ignored, and only NRD(1) is used. With NONMEM 7.4, NRD(0) is the relative tolerance for the Steady State computations. If NRD(0) is not specified, NRD(1) is used. The value of NRD(1) can also be specified using $SUBROUTINES option TOL. The value of NRD(0) can also be specified using $SUBROUTINES option SSTOL.
• ANRD(I) (NM74): the absolute tolerance in the computation of the drug amount in compartment I. The default is 12 (that is, accuracy is 10**(-12)). Used by ADVAN 9, 13, 14, 15, 16, 17, and 18, which have the capability of using different values of ANRD for different compartments. For compartments not specified, the tolerance of the last compartment specified will be used. ANRD(0) is the absolute tolerance for the Steady State computations. If ANRD(0) is not specified, ANRD(1) is used. The value of ANRD(1) can also be specified using $SUBROUTINES option ATOL. The value of ANRD(0) can also be specified using $SUBROUTINES option SSATOL.
• NRDC(I) (NM74): same as NRD(I), but used for the FOCE/LAPLACE covariance step. Used with ADVAN 9, 13, 14, and 15, 16, 17, and 18. If not set, NRDC defaults to the value of NRD. NRDC(0) is used for Steady State computations during the FOCE/LAPLACE covariance step. The value of NRDC(1) can also be specified using $SUBROUTINES option TOLC. The value of NRDC(0) can also be specified using $SUBROUTINES option SSTOLC.
• ANRDC(I) (NM74): Same as ANRD(I), but used for the FOCE/LAPLACE covariance step. Used with ADVAN 9, 13, 14, and 15, 16, 17, and 18. If not set, ANRDC defaults to the value of ANRD. ANRDC(0) is used for Steady State computations during the FOCE/LAPLACE covariance step. The value of ANRDC(1) can also be specified using $SUBROUTINES option ATOLC. The value of ANRDC(0) can also be specified using $SUBROUTINES option SSATOLC.

When NM-TRAN is used, this information may be supplied by either the TOL option of the $SUBROUTINES record or the $TOL record.

One may supply a TOL routine that assigns values of NRD and ANRD specifically for the initial (base) setting and each NONMEM step (estimation, covariance, simulation, table/scatter step, simulation, initial parameters estimate, nonparametric). For example, create a toluser.f90 file,

 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

  SUBROUTINE TOL(NRD,ANRD,NRDC,ANRDC)
    USE NMPRD_INT, ONLY: IPROB
    USE NM_BAYES_INT, ONLY: NM_STEP,BASE_STEP,EST_STEP,COV_STEP, &
         TABLE_STEP,SIML_STEP,INE_STEP, NONP_STEP
    IMPLICIT NONE
    INTEGER :: NRD(0:*), ANRD(0:*), NRDC(0:*), ANRDC(0:*)
    IF(NM_STEP==EST_STEP) THEN
       NRD(1)=6
       ANRD(1)=10
    ELSE IF (NM_STEP==COV_STEP) THEN
       NRD(1)=7
       ANRD(1)=8
    ELSE IF (NM_STEP==TABLE_STEP) THEN
       NRD(1)=8
       ANRD(1)=7
    ELSE
       NRD(1)=9
       ANRD(1)=12
    ENDIF
    IF(IPROB>1) THEN
       NRD(1)=NRD(1)+1
       ANRD(1)=ANRD(1)+1
    ENDIF
    RETURN
  END SUBROUTINE TOL

and incorporate it using $SUBR

1

 $SUBROUTINES ADVAN13 TRANS1 TOL=toluser.f90

USAGE:

1

"      verbatim line

Verbatim code is Fortran code within a block of abbreviated code that is to be copied by NM-TRAN to the generated Fortran subroutine. It is not itself regarded as abbreviated code. Such code is marked by having the character " as the first non-blank character. The " is dropped and the characters to the right are copied as-is to columns 1-72 of the generated subroutine. Lines of verbatim code can include any Fortran statements: comment, declaration (e.g., INTEGER, COMMON, USE), I/O, CALL, assignment, continuation, DO, GOTO, etc.).

NM-TRAN makes some modifications to verbatim code:

• Placement: the verbatim code is adjusted as necessary to conform to FORTRAN column conventions. Alphabetic text that follows the initial ", or that follows a statement number, is moved to column 7, as required by FORTRAN.
• Comment lines: If the character that immediately follows the initial " is !, this conforms to the FORTRAN 90 syntax for comment lines. The line is copied unchanged. If the character that immediately follows the initial " is C or c or " or *, this conforms to the FORTRAN 77 syntax for comment lines. The line is copied unchanged, but C or c or " or * is replaced by !.

• Continuation lines: Fortran 77 continuation lines (non-blank in position 6) are not permitted with NONMEM 7. Instead, the line to be continued should end with character &. Example:

  1 2	" X=A & " +D/E

• Replacement Rule: in $PK, $ERROR, $DES, $AES, $INFN, and $PRED, in a line of abbreviated code labels of items in the data record are replaced by direct references to the data record itself (either DATREC or EVTREC, as appropriate). Thus, for example, if such a label occurs as the left-hand side of an assignment statement, then without this rule, when the statement is executed, the value of a local variable having the label is modified, whereas with the rule, an item in the data record is modified.

The character @, immediately before a label, can be used as an "escape" to prevent the label from being replaced. If the character @ immediately follows the initial ", none of the labels occuring in the line are replaced.

Labels occurring in common statements or as subroutine arguments are never replaced.

Tab characters (and other characters that are smaller than blank in the computer's collating sequence, such as carriage return ^M) are permitted in verbatim code. With NONMEM 7, the last non-blank character on the line is replaced by a space if it is a low-value character. This permits DOS-type line endings ^M.

By default, all verbatim code goes in the main section of code and is called MAIN verbatim code. (The main section follows declarations and initial executable code inserted by NM-TRAN.) Within the main section, verbatim and abbreviated code may be freely mixed. Each line of verbatim code is positioned in the generated code after all code generated from the preceding line of abbreviated code. The user may explicitly specify a different location as follows.

• FIRST verbatim code: Verbatim lines which must be positioned immediately after the declarations which are part of the normal subroutine header, and prior to the FIRST executable statement of the subroutine, must precede the first line of abbreviated code and must start with the line "FIRST.
• MAIN verbatim code: FIRST verbatim code is normally terminated by the first line of abbreviated code. If there is both FIRST and MAIN verbatim code, and/or the main section is to start with verbatim code, the line "MAIN may be used to separate the FIRST and MAIN verbatim code.

• LAST verbatim code: Verbatim lines which are to immediately precede the RETURN statement from the generated subroutine must follow the last line of abbreviated code and must be preceded by the line "LAST.

  Example:

  1 2 3 4

  $ERROR Y=F*(1+ERR(1)) "LAST " PRINT *,HH(1,1)

  This displays values after they have been assigned, immediately prior to the return.

If any lines of verbatim code are present in a block of abbreviated code, NM-TRAN generates USE statements appropriate to the kind of abbreviated code and allows variables undefined in abbreviated code to be used as right-hand quantities in abbreviated code.

Since v7.2+, NONMEM employs dynamic memory allocation. Subroutine FSIZESR contains the constants for the allocation. The $SIZES record can be used to override some of the values in FSIZESR. Constants set to 0 cannot be determined or are not given by NM-TRAN and will default to the values in resource/SIZES.f90 in NONMEM source code.

Module NMPRD4 stores NONMEM runtime variables. It is also accessible in user-supplied routines and generated code, and also by NONMEM. User can use $TABLE to output the module variables. It is possible for the user to set aside a portion of NMPRD4 for variables defined in user-supplied code, or for variables directly controlled by the user (see COMACT, COMRES, COMSAV in Chapters III.B.7 and IV.E.2).

Module PRINFN is only for user-supplied and generated code. NM-TRAN creates this module only when $INFN is used.

Module DECLAREVARIABLES stores variables in $ABBREVIATED DECLARE control record. (NM73)

The two subroutines implement the $THETAI and $THETAR records, respectively. They are created only when the corresponding record is used.

Subroutine MUMODEL2 subroutine is based on the PRED or PK subroutine in FSUBS. It contains only statements (if any) for the MU model, which is used in the new (Bayseian) methods of NONMEM.

Related to FSUBS, NM-TRAN the following files for user checking and debugging purposes. They are not directly used by NONMEM.

• FSUBS_MU.F90: the file for MUMODEL2 in FSUBS.
• FSIZES: same as the FSIZESR routine in FSUBS.
• FMSG: messages (information, warning, error) NM-TRAN run, same as displayed in terminal.
• FORIG: the original (pre-replacement) abbreviated code and $TABLE and $SCATTER records.
• FREPL: the new (post-replacement) abbreviated code and $TABLE and $SCATTER records.
• FSUBS2, =FSUBS.F90: duplicates of FSUBS.