57 NONMEM Stubs

User-replaceable stub routines: CRIT, FUNCA-FUNCI, etc.

1 CCONTR

MEANING: CCONTR subroutine

CONTEXT: User-supplied subroutine; replaces a NONMEM dummy routine

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

USAGE:

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(:,:)

DISCUSSION:

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 epsilons or etas and in other situations, e.g., with categorical population data.

NONMEM sometimes produces this error message:

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:

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.

OPTIONS:

I (input)

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

CNT (output)

The conditional contribution to the objective function for this L2 record.

P1 (output)

P1(i) is the partial derivative of CNT with respect to eta(i).

P2 (output)

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 (output)

0 - Normal return.

non-zero - error return.

IER2 (output)

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 Section 53.49) E.g., USE ROCM_REAL, ONLY: THETA=>THETAC (See Section 53.11). (See Section 53.10).

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.

REFERENCES: Guide IV, section III.B.4

2 CONTR

MEANING: CONTR subroutine

CONTEXT: User-supplied subroutine; replaces a NONMEM dummy routine

USAGE:

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

DISCUSSION:

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.

OPTIONS:

I (input)

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

CNT (output)

Contribution to -2log likelihood for data from the individual record.

IER1 (output)

0 - Normal return.

non-zero - error return.

IER2 (output)

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:

THETA (current theta) (See CONTR_MIX:_THETA)
DV and data values for this L1 record.
(See Section 53.21, CONTR:_III_DIM)
(See Section 57.2)
Predictions and derivatives. (See CONTR:_F_G_H)

NOTE: NONMEM Utility Routines:

Other NONMEM subroutines may be called by CONTR, depending on the type of data, as follows.

CONTINUOUS   POPULATION           SINGLE-SUBJECT
CATEGORICAL  ELS, NCONTR          ELS
             (note: same result)
             NCONTR               none

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

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

REFERENCES: Guide I, section G.3; Guide IV, section III.B.4; Guide V, section 12.4.16

3 CRIT

MEANING: CRIT subroutine

CONTEXT: User-supplied subroutine; replaces a NONMEM routine

USAGE:

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

DISCUSSION:

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

OPTIONS:

ICALL (input): 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 (input): Number of individual record.
N (input): Number of observations in the individual record.
WRES (input): Vector of weighted residuals (as many residuals as there are observations).
V (output): Value of function.

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

REFERENCES: Guide II, section C.6, Figure 8; Guide III, section V.5.0; Guide IV, section III.B.6

4 `INFN`

MEANING: INFN subroutine

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

USAGE:

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

DISCUSSION:

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

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

Input/Output argument:

ICALL

ICALL=-1: INFN may set PRED_IGNORE_DATA=1 for records to be dropped. The following is required:
```
USE NMPRD_INT, ONLY: PRED_IGNORE_DATA,PRED_IGNORE_DATA_TEST
```
The option $DATA ... PRED_IGNORE_DATA is required to cause NONMEM to make a PRED_IGNORE_DATA pass.
ICALL=0: INFN may now make computations for run initialization. ICALL may be reset by INFN to a number in the range 1-8999. This number will appear on NONMEM output, allowing the user to identify the INFN routine being used.
ICALL=1: INFN may now make computations for problem initialization.
ICALL=3: INFN may now make computations for subproblem finalization.
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 Section 53.99, Section 53.99).
ICALL=3: INFN may now make computations for run finalization. First do problem finalization, if required. Then test for IPROB=NPROB (the number of the current problem equals the total number of problems), and if true, do run finalization. Values of IPROB and NPROB may be found in NONMEM modules (See Section 53.89).

Input arguments:

DATREC

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

THETA

The NONMEM THETA vector.

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

INDXS

The values specified in the $INDEX record of the NM-TRAN control stream. (This is the NONMEM INDXS array starting at position 12, the first position beyond those positions used by PREDPP itself.)

NWIND

NWIND has value 0 when INFN is called. It changes value during a pass through the data using PASS (See below).

NWIND=0: First record of the data set.
NWIND=1: First record of a subsequent individual record.
NWIND=2: Subsequent data record of an individual record.

EXAMPLES OF USAGE:

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

(See Infn interpolation example).

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

5 MIX

MEANING: MIX subroutine

CONTEXT: User-supplied subroutine; replaces a NONMEM dummy routine

USAGE:

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)

DISCUSSION:

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 Section 53.50, MIX CONTR:_THETA).

The 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 Section 53.48)

With mixture models, MIXNUM, MIXEST and MIXP are variables that may be used as right-hand quantities (or in logical conditions) in various other abbreviated codes or user-supplied routines. MIXNUM is the index of the subpopulation for which variables are to be computed. At ICALL=3, 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. MIXP refers to the mixture probabilities P computed by subroutine MIX.

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

REFERENCES: Guide III, section V.5.0

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

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

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

6 PRIOR

MEANING: PRIOR subroutine

CONTEXT: User-supplied subroutine; replaces a NONMEM dummy routine

USAGE:

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

DISCUSSION:

The 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 (See Section 53.87). 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: CNT is the penalty term.

Other Inputs:

Other inputs are available to PRIOR in NONMEM read-only modules. (See Section 53.65).

NONMEM Utility Routines:

PRIOR may call NONMEM utility routines, NWPRI and TNPRI. (See Section 59.12, Section 59.21). E.g.,

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

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 Section 59.12, Section 59.21).

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 Section 50.25, Section 52.2). This prior is especially useful for an empirical specification of a penalty function. (See Section 59.21).

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

REFERENCES: Guide V, section 12.4.16

7 SPTWO

MEANING: SPTWO subroutine

CONTEXT: User-supplied subroutine; replaces a NONMEM dummy routine

USAGE:

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)

DISCUSSION:

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 - NONMEM should stop.

Other Inputs:

NONMEM read-only global variables. (See Section 53.50) (See CONTR:_III, Section 53.11) (See CONTR:_F, Section 53.10, Section 53.10) (See Section 53.64) (See Section 53.72) (See Record_Counters:_NIREC, Section 53.92)

REFERENCES: None.

8 STUBS

MEANING: Type of NONMEM, PREDPP or User subroutine and function

CONTEXT: Replaced by a user-written subroutine or function

DISCUSSION:

“Stubs,” or “dummy” routines, are subroutines or functions called by NONMEM, PREDPP or user code. The versions of these routines that are distributed with NONMEM are essentially empty, i.e., they do nothing. They can be replaced by user-written code in advanced applications.

Each stub and utility subroutine or function has its own help entry.

Stubs for NONMEM

CRIT Modifies the computation of the default objective function.

CONTR Specifies the contribution to the objective function of a level 1 (“L1”) record.

CCONTR Specifies the contribution to the objective function of a level 2 (“L2”) record.

MIX Describes the mixing parameter of a mixture model.

PRIOR Allows a Bayesian penalty to be included in the objective function.

SPTWO SPTWO can be used to redefine the RES and WRES items for observation records.

THETAI THETAI is used to transform initial thetas.

THETAR THETAR is used to transform final thetas for reporting.

stubs for PREDPP

INFN Initialization/Finalization routine.

Stubs for User functions

FUNCA, FUNCB, FUNCC, FUNCD, FUNCE, FUNCF, FUNCG, FUNCH, FUNCI Defines a function for abbreviated code.

Code to replace a function stub should be placed in a file, e.g., funcacode. It should be listed on the $SUBROUTINES record. E.g.,

`$SUBROUTINES` ... OTHER = funcacode

REFERENCES: (CRIT) Guide II, section C.6 REFERENCES: (INFN) Guide VI, section VI.A, Figure 37

1 CCONTR

2 CONTR

3 CRIT

4 INFN

5 MIX

6 PRIOR

7 SPTWO

8 STUBS

4 `INFN`