122  PREDPP

NONMEM V Supplemental Guide

1 PK, TRANS, and ERROR routines

2 PK, TRANS, and ERROR Routine Declarations

☞ PK, TRANS, and ERROR user-written subroutines for population data that worked with previous versions of NONMEM will not work with NONMEM V until the declarations in these routines have been revised to reflect the larger numbers of η’s and ε’s allowed with NONMEM V. (No change is needed to abbreviated code in an old $PK or $ERROR block, however.)

See Guide VIII pk, error, trans

3 More Parameters

The maximum number of rows in GG (i.e., of basic and additional PK parameters) increases from 30 to 50. If necessary, this maximum can be increased even further.

See Guide III IV.1.3 V.2.6

See Guide VIII pk, psizes, tsizes

4 Common for DOSTIM

Variable DOSTIM and its η derivatives are defined in read-only common PROCM2. (In the documentation for PREDPP III, the variable was called DOST. The name has been changed to DOSTIM for documentation purposes. This does not require any change to existing PK routines.) The declaration of common PROCM2 has changed to reflect the larger number of η’s allowed with NONMEM V.

See Guide VIII procm2, $pk

5 Active Etas

A user written PK, TRANS, or ERROR routine may compute derivatives for all η’s, or optionally, to reduce run time, only for active η’s.

See Guide VIII procm5

6 Common PRRAND

With PREDPP Version III, realizations of the η and ε variables in the ERROR and PK routines may have been stored in a PREDPP common PRRAND. With PREDPP Version IV, η’s may be stored in a new NONMEM common, NMPRD7. This allows simulated η’s to be automatically displayable by NONMEM. ERROR may store ε’s in common PRRAND, but the declaration is different than it was previously. Declarations for PRRAND in old user-written PK and ERROR routines should be modified to include both NMPRD7 and PRRAND.

See Guide VIII nmprd7, prrand

7 ERROR

8 ERROR’s IDEF

At ICALL=1, a value may optionally be stored in IDEF(3) to reduce run time. No existing ERROR routine need be changed.

See Guide VIII error

9 Event Records

10 The Dose Rate (RATE) Data Item

☞ Documentation change. Guide VI (pre 1998 editions) states: “A 0 indicates that the dose is an instantaneous bolus dose.” There is an exception: a record with AMT=0, RATE=0, SS>0, and II=0 allows steady-state amounts to be computed by PREDPP based on system input given by the DES routine. This is useful when the differential equations provide for endogenous drug production. Furthermore, with NONMEM V, NM-TRAN supplies EVID=1 (dose event) for such records. Note that with NONMEM IV, NM-TRAN supplied EVID=0 (observation event) for such records, which is not correct. Consequently, if such records were present in the data set, the user had to provide the EVID item.

See Guide VIII ss dose event record

11 The Steady State (SS) Data Item

The SS data item may take the value 3. It is useful only with SS6 and SS9.

See Guide VIII ss data item

12 Other User Subroutines

13 INFN

14 Use of an INFN Argument

At ICALL=0, INFN may now change the value of the first argument from 0 to a number in the range 1-8999. PREDPP prints this number in the output to help the user identify his own code. No existing INFN routine need be changed.

See Guide VIII infn

15 MODEL

16 More Compartments and More Parameters

The maximum number of user-defined compartments with a general ADVAN routine increases from 9 to 19. If necessary, these maxima can be increased even further.

See Guide III IV.1.3, V.1.6 IV.1.3, V.1.6

See Guide VIII pk, psizes, tsizes

17 Models with No Basic PK parameters

With ADVAN routines 6, 8, and 9, MODEL may now define models with no basic PK parameters.

See below 40. (Theta and EVTREC are Usable Directly)

18 DES

19 DES Routine Declarations

A new argument DT must be declared. The partial derivative of DADT(i) with respect to T must be stored in DT(i). Old DES routines may or may not require a change. If T does not appear on the right side of any differential equation, then all elements of DT are zero and DES need not compute them because they are initialized to zero by PREDPP. If in addition the Fortran compiler and/or system loader does not consider it to be a fatal error if a calling routine passes more arguments to a subroutine than the subroutine declares, then old DES routines will still work. With some platforms, e.g., Microsoft, there will be an unresolved external reference, and it will be necessary to modify existing user-written DES routines to declare the new argument DT.

See Guide VIII des

20 Structure for DA, DP, DT: Full vs. Compact

☞ Arrays DA, DP, DT can have “full” format, as has been used in the past. E.g., DA is defined as DA(10,10), where DA(i,j) is the partial derivative of DADT(i) with respect to A(j). Now, they may also have “compact” format, in which (e.g.) DA is defined to be in effect one-dimensional and only those derivatives that can be non-zero for the the particular model have defined positions in the array and need be computed.

Existing DES routines can be used with no change (but see 36). However, compact arrays are required with the Laplacian method if second-partial derivatives are computed analytically. The use of “compact” format is optional with other methods. Note that, by default, NM-TRAN implements $DES blocks using compact formats. More information about compact array formats may be obtained by consultation with the NONMEM Project Group.

The option DES of the $ABBREVIATED record specifies the format of the arrays returned by the DES routine: FULL or COMPACT.

See Guide VIII $abbreviated, des, prdde1

21 DES Initialization at ICALL=1

PREDPP Version IV makes an initialization call to the DES routine. This call does not occur with earlier versions of PREDPP. A new common is defined in PREDPP for DES and AES initialization:

COMMON /PRDDE1/ICALL,IDEFD(2),IDEFA(2)
INTEGER ICALL,IDEFD,IDEFA

ICALL has the same value as PK and ERROR’s ICALL argument. At ICALL=1, DES may optionally store values in IDEFD in order to improve run time. Values may be stored in DADT, etc., as at other calls, but these values are ignored.

No changes are required to any existing DES routine because of this change. However, at ICALL=1 a user-written DES routine that does not check ICALL will compute DADT, etc., using values that PK computed (at ICALL=1) with the first event record and compartment amounts that are 0. There is some risk of arithmetic difficulties if, for example, a compartment amount of 0 is raised to a power. If this occurs, the user should insert the following statement at the top of the routine:

IF (ICALL.EQ.1) RETURN

See Guide VIII des, prdde1

22 Displayed DES-defined Items

DES-defined items may be displayed in tables or scatterplots and are computed at the event time in the data record. With previous versions of PREDPP, the displayed items might have been computed at a slightly different time and might have had slightly different values.

23 Theta and EVTREC are Usable Directly

New PREDPP read-only commons contain the current THETA vector and the current event record (the event record to which the system is being advanced). Thus these quantities can be directly referenced by DES (rather than obtained as PK parameters). Similarly, $DES abbreviated code may now include direct reference to THETA elements and data record items. This may improve run time.

See Guide VIII procm6, procm7

24 Use of DOSTIM and DOSREC in DES

PREDPP defines variables DOSTIM and DOSREC in commons PROCM2 and PROCM3. Their use in DES was not previously documented.

A DES routine may test DOSTIM and DOSREC in a logical condition. It may use them on the right-hand side of an assignment statement. If DOSTIM is a random variable, DOSTIM must not be used in DES or $DES. However, DOSTIM may always be used in a $PK block or PK routine to define a random variable which may be used in the DES routine.

See Guide VIII des, procm2, procm3

25 Time T in DES routines

With PREDPP Version III, if a rate parameter, duration parameter, or absorption lag time parameter is a random variable, then T may be used only in logical conditions.

This restriction is now removed. Time T may be used freely in DES routines and in $DES abbreviated code.

26 AES

27 AES Initialization at ICALL=1

PREDPP Version IV makes an initialization call to the AES routine. This call does not occur with earlier versions of PREDPP. A new common is defined in PREDPP for DES and AES initialization:

COMMON /PRDDE1/ICALL,IDEFD(2),IDEFA(2)
INTEGER ICALL,IDEFD,IDEFA

ICALL has the same value as PK and ERROR’s ICALL argument. At ICALL=1, AES may optionally store values in IDEFA in order to improve run time. Values may be stored in A, etc., as at other calls, but these values are ignored. At ICALL=1, INIT has the value 1.

No changes are required to any existing AES routine because of this change. However, at ICALL=1, a user-written AES routine that does not check ICALL will compute A, etc., using values that PK computed (at ICALL=1) with the first event record and compartment amounts that are 0. There is some risk of arithmetic difficulties if, for example, a compartment amount of 0 is raised to a power. If this occurs, the user should insert the following statement at the top of the routine:

IF (ICALL.EQ.1) RETURN

See Guide VIII aes, prdde1

28 Displayed AES-defined Items

AES-defined items may be displayed in tables or scatterplots and are computed at the event time in the data record. With previous versions of PREDPP, the displayed items might have been computed at a slightly different time and might have had slightly different values.

29 Theta and EVTREC are Usable Directly

New PREDPP read-only commons contain the current THETA vector and the current event record (the event record to which the system is being advanced). Thus these quantities can be directly referenced by AES (rather than obtained as PK parameters). Similarly, $AES abbreviated code may now include direct reference to THETA elements and data record items. This may improve run time.

See Guide VIII procm6, procm7

30 Use of DOSTIM and DOSREC in AES

PREDPP defines variables DOSTIM and DOSREC in commons PROCM2 and PROCM3. Their use in AES was not previously documented.

A DES routine may test DOSTIM and DOSREC in a logical condition. It may use them on the right-hand side of an assignment statement. If DOSTIM is a random variable, DOSTIM must not be used in AES or $AES. However, DOSTIM may always be used in a $PK block or PK routine to define a random variable which may be used in the AES routine.

See Guide VIII aes, procm2, procm3

31 Time T in AES routines

With PREDPP Version III, if a rate parameter, duration parameter or absorption lag time parameter is a random variable, then T may appear explicitly in the algebraic equations, as long as no differential equation depends on the equilibrium compartment amounts.

With PREDPP Version IV, this restriction has been removed.

32 The PREDPP Library

33 Laplacian Method

The analytic Laplacian method is supported with all ADVAN, TRANS and SS routines with these exceptions:

ADVAN5 ADVAN7 ADVAN11 ADVAN12 SS5 SS7 SS11 SS12

With the above routines, the the Laplacian method may be used, but only if the $ESTIMATION record includes the option NUMERICAL. (For ADVAN11 and SS11, and ADVAN12 and SS12, see below ADVAN11, ADVAN12.)

See Guide VIII $estimation

34 ADVAN5

Substantial time savings are possible when the PK routine limits calls to once per individual record (CALLFL=1 or ONCE PER IR).

See Guide VIII calling protocol

35 ADVAN7

Substantial time savings are possible when the PK routine limits calls to once per individual record (CALLFL=1 or ONCE PER IR).

See Guide VIII calling protocol

There is new error message. An example of this message follows:

NUMERICAL DIFFICULTIES OBTAINING THE SOLUTION. NON-REAL
EIGENVALUES. PERHAPS ADVAN5 SHOULD BE USED FOR THIS PROBLEM.
"LARGEST" VALUE ALONG SUBDIAGONAL OF SCHUR MATRIX:  0.423E-01
(DIAG:  0.84E+00  0.84E+00)

If the maximum value printed is very small (e.g., E-15), then the computations will probably proceed correctly if the error message is suppressed; information about suppressing the message may be obtained by consultation with the NONMEM Project Group. If the maximum value is sizeable (e.g., E-01), then the model should be scrutinized and if there are no mistakes, ADVAN5 should be used.

36 ADVAN9 as an Algebraic Equation Solver

ADVAN9 allows the user to define a model consisting only of equilibrium compartments, in which case ADVAN9 becomes a purely algebraic equation solver. The quantities A(i) may be thought of as unknowns to be determined rather than as “compartment” amounts.

Several changes are associated with this use of ADVAN9:

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, ADVAN9 is called exactly as other ADVAN routines are called: when the value of TIME increases.

If TIME is not defined, the AES routine specifies the calling protocol for ADVAN9: call with every event record (the default) or once per individual record.

If calls to ADVAN9 are limited, the CALL data item may be defined in the data set and given the value 10 to force additional calls to ADVAN9.

No calls to the DES routine occur. The DES routine may be omitted if the linker permits an unresolved external reference, or may be a dummy routine (stub) that simply executes a return statement. With NM-TRAN, a $DES block may not be present but NM-TRAN generates code for a dummy DES routine.

See Guide VIII aes, prdde1, call data item

37 ADVAN11

ADVAN11 implements the Three Compartment Linear Model. It uses a subroutine EXP3 from the PREDPP library. It may be used with TRANS1, TRANS4, and TRANS6.

See Guide VIII advan11, trans4, trans6

38 ADVAN12

ADVAN12 implements the Three Compartment Linear Model with First Order Absorption. It uses subroutines EXP3 and EXP4 from the PREDPP library. It may be used with TRANS1, TRANS4, and TRANS6.

See Guide VIII advan12, trans4, trans6

39 TRANS6

TRANS6 may be used with ADVAN3, ADVAN4, ADVAN11 and ADVAN12. The parameters are ALPHA, BETA and (with ADVAN11 and ADVAN12) GAMMA, plus rate constants from peripheral compartments to to the central compartment.

See Guide VIII trans6