Chapter IV - How to Install and Test PREDPP
This chapter describes how to install
PREDPP. It is convenient, but not necessary, to work in a
reserved disk area.
UNIX users might work in a dedicated directory called
(say) /export/home/nmvi/pr.
MS-DOS users might work in a dedicated directory
called (say) c:\nmvi\pr.
CMS users can safely work in the same disk area as in
Chapter III because no PREDPP subroutine has the same name
as any NONMEM subroutine.
It is assumed that you have already read the source code for single or double precision PREDPP into two disk files: one for the Kernel routines, and one for the Library routines. It is also assumed that you have already read the file SIZES from the NONMEM distribution medium into the directory above the PREDPP directory, as discussed in chapters 2 and 3.
Whereas all NONMEM routines are needed for every run, only selected PREDPP routines are required. The set of subroutines needed for a given run (i.e., for a given pharmacokinetic model) is documented in NONMEM Users Guide, Part VI. Also, for each run, NM-TRAN produces a file (FREPORT) describing the required subroutines. This chapter guides you through the following steps.
For the file of Kernel subroutines:
|
1. |
Separate the file into smaller files. |
|
2. |
Make any required changes to the source code. |
|
3. |
Compile the subroutines and build a binary library. |
For the file of Library subroutines:
|
4. |
Separate the file into smaller files. |
|
5. |
Make any required changes to the source code. |
|
6. |
Compile the subroutines. |
For NONMEM-PREDPP as a whole:
|
7. |
Create a simple test case. |
|
8. |
Build a NONMEM-PREDPP executable and run the test case. |
Kernel subroutines are subroutines which are used with all kinetic models. There are 7 Kernel subroutines. Of these, four (PRED, PREDI, CHECK, SADVAN) are actually required for every run.
Subroutine INFN is a "stub", or "dummy", which does nothing; one may occasionally choose to substitute one’s own INFN subroutines. (See Section VI.A of NONMEM Users Guide, Part VI.)
Subroutines SSS and SSS0 have the same entry name. A choice must be made between them at the time the NONMEM-PREDPP executable is built. SSS is required if an "SS" subroutine is included to compute steady-state drug levels (e.g., if steady-state doses are included in the data set). SSS0 is a "stub" which may be used if no SS routine is included. When SSS0 is included, the executable may be considerably smaller.
The single file of Kernel subroutines should be separated into individual subroutines. They may be separated using the SEP program described in Chapter III. It makes no difference if SEP or SEPG77 is used with PREDPP. It is easiest to use whichever was used for NONMEM.
UNIX:
sep < PPD1
MS-DOS:
sep < ppd1
CMS:
FORTVS SEP FILEDEF 5 DISK PPD1 FORTRAN A LOAD SEP ( START LIST FILE ( EXEC RENAME CMS EXEC A PPD1 EXEC A PPD1 EXEC REN
You may also use your system’s editor to separate the routines. Locate "CD" lines and save the code between these lines in appropriately named files. For example, the file starts as follows:
CDCHECK
...
many lines of code ...
...
END
CDINFN
All the code between the lines beginning "CDCHECK" and the END statement preceding "CDINFN" should be stored in a separate file. (E.g., a file named check.for in UNIX and MS-DOS, or CHECK FORTRAN A in CMS.)
When bugs are found in PREDPP, the fixes are described in emails and technical newsletters. Please check any newsletters that may have been sent with the NONMEM distribution medium or that are received afterwards. You will have to modify the source code and recompile portions of PREDPP.
See also Chapter 1, Section 7, for internet sites of interest.
Within the NONMEM report, the first line
of PREDPP’s output contains characters identifying the
version and level numbers of PREDPP. The characters
identifying the level are located in subroutine PREDI, in a
statement similar to the following†:
----------
DATA LEV/’1.0’/
Changing this number in PREDI will never be necessary, but the user may choose to do this in order to establish a record that the bug fixes were implemented. See also Chapter III, Section 2.2.4.
The remaining changes to the source code are optional.
Certain constants are used by PREDPP to control array sizes, and may be changed by the user. These constants are set by PARAMETER statements in the include file SIZES. Constants that are changed in SIZES take effect only after all of PREDPP has been recompiled.
Note that NONMEM and NM-TRAN and the NM-TRAN Library Routines also share the include file. Certain constants are common to more than one of these components. If you change a constant in SIZES, comments will tell you if other components of the NONMEM system should be recompiled. Appendix 2 lists all the constants and the components in which they appear.
Several of the constants in SIZES are of special interest.
Parameters LTH and LVR appear in both NONMEM and PREDPP. They are discussed in Chapter III, Section 2.9, and in Appendix 2.
Parameter PC gives the maximum allowable number of compartments, including the output compartment, in all general ADVAN and SS routines (ADVAN5-9, SS5-9). The value on the distribution medium is as follows.
PARAMETER (PC=30)
If this constant is exceeded in a user-written MODEL subroutine, PREDPP produces an error message such as the following:
NUMBER OF USER-DEFINED COMPARTMENTS, 30, MUST BE LESS THAN "PC"
PC may be increased or decreased. If PC is changed in SIZES, PREDPP and NM-TRAN must be recompiled. (see Chapter V Section 1.6).
Parameter PG gives the number of rows in GG, the array in which PK routine stores the basic and additional PK parameters. Each row corresponds to a distinct PK parameter. The value on the distribution medium is as follows.
PARAMETER (PG=50)
If this constant is exceeded in a user-written PK routine, PREDPP produces an error message such as the following:
ERROR IN PK: INAPPROPRIATE VALUE IN IDEF( 5, 1): 51 ROW IN GG MUST BE 1 THRU "PG" FOR COMPARTMENT 1’S SCALE
PG may be increased or decreased. If PG is changed in SIZES, PREDPP and NM-TRAN must be recompiled (see Chapter V Section 1.6).
Certain potentially large arrays used by DES routines with the General Non-Linear ADVAN routines may be stored in compact form. Parameter PIR gives the maximum size of these arrays. The value on the distribution medium is as follows.
PARAMETER (PIR=350)
The arrays are large enough for all normal use of PREDPP. Constant PIR may be increased. If PIR is changed in SIZES, PREDPP and NM-TRAN must be recompiled (see Chapter V Section 1.6).
With NONMEM VI, PREDPP allows additional PK parameters called Model Event times, e.g., MTIME(1). Parameter PCT gives the maximum number of these parameters. The value on the distribution medium is as follows.
PARAMETER (PCT=30)
Constant PCT may be increased. If PCT is changed in SIZES, PREDPP and NM-TRAN and NM-TRAN Library routines must be recompiled (see Chapter V Section 1.6).
With NONMEM V, the Maximum number of additional and lagged doses for an individual record was fixed at 20. With NONMEM VI, this number is set by parameter PAL. The value on the distribution medium is as follows.
PARAMETER (PAL=20)
Constant PAL may be increased. PREDPP must be recompiled.
Compile the PREDPP Kernel subroutines as you did the NONMEM subroutines in Chapter III. Save the object code for later use. (E.g., in CMS, in PPD TXTLIB A.) UNIX users may wait to compile both Kernel and Library subroutines at the same time.
|
CMS: |
Make a file called ADDPPD EXEC A containing the statement:
TXTLIB ADD PPD &2
Input the following commands:
PPD1 EXEC COMPILE TXTLIB GEN PPD PRED PPD1 EXEC ADDPPD PPD1 EXEC ERASE2 FORTVS SSS FORTVS SSS0 ERASE * LISTING
Note that the TXTLIB is deliberately named PPD rather than PPD1. Note also that only one of SSS and SSS0 can be retrieved from the TXTLIB because they have the same entry name. TEXT files for SSS and SSS0 MUST remain on the local disk.
As with NONMEM, we recommend optimized compiles. Similar warning messages to those seen with NONMEM may occur. Similar error messages concerning the include file SIZES may also occur, and it may be necessary to rename the include file. See Chapter III Section 3.
If the compiler produces fatal error messages, or if you are concerned about warning messages, contact the NONMEM consultant. Do not attempt to fix the source code yourself! Phone (410) 696-3098 or send e-mail to nmconsult@globomaxnm.com.
Now work with the second file of PREDPP routines that was read from the distribution medium. This file contains the PREDPP Library subroutines discussed in NONMEM Users Guide, Part VI. It contains four groups of subroutines.
Each of the first three groups consists of subroutines having different names on the distribution medium, but having the same entry name. PREDPP users will choose at most one subroutine from each of the first three groups for a given NONMEM-PREDPP run.
|
1. |
Group 1 subroutines all have entry name ADVAN and implement specific pharmacokinetic models: ADVAN1, ADVAN2, ADVAN3, ADVAN4, ADVAN5 ADVAN6, ADVAN7, ADVAN8, ADVAN9, ADVAN10 ADVAN11, ADVAN12 |
|
2. |
Group 2 subroutines all have entry name TRANS and implement a specific parameterization: TRANS1, TRANS2, TRANS3, TRANS4, TRANS5, TRANS6 |
|
3. |
Group 3 subroutines have entry name SS and perform steady-state calculations for specific pharmacokinetic models: SS1, SS2, SS3, SS4, SS5, SS6, SS7, SS9, SS11, SS12 |
|
Each SS routine is used with the ADVAN having the same number. SS6 may also be used with ADVAN8 and ADVAN10. |
|
4. |
Group 4 subroutines consists of auxiliary routines and auxiliary routine-groups and are used with ADVAN5 through ADVAN12 and SS5 through SS12. The set of auxiliary routines and auxiliary routine-groups required for a particular ADVAN and SS combination is described in NONMEM Users Guide, Part VI and is also displayed in the NM-TRAN output file FREPORT. |
The subroutines in groups 1-3 of this file MUST be separated into individual files, although this is optional for the routines and routine-groups of group 4. As with the Kernel routines, you can separate the subroutines using your system’s editor, or you can use the program SEP.
A routine-group consists of a group of routines that are used together and are grouped together following a single "CD" routine- header. These are:
DGEAR1, LSODI1, MMPHI, REXPON, RRXPON, RXSUBS, ZSPOW1, ZSPOW2
Each routine-group should be stored in a single file for convenience. Program SEP will do this automatically.
|
UNIX: |
sep < PPD2
|
MS-DOS: |
sep < ppd2
|
CMS: |
FILEDEF 5 DISK PPD2 FORTRAN A LOAD SEP ( START LIST FILE ( EXEC RENAME CMS EXEC A PPD2 EXEC A PPD2 EXEC REN
If disk space is extremely limited, and you are quite certain that no NONMEM-PREDPP user will ever use certain ADVAN and SS routines, you can erase these routines and any auxiliary routines that are used exclusively by them. We do not recommend this step. It is best to retain the option of easily using the largest variety of models for future use.
The double-precision REXPON routine, which is used only with ADVAN5, uses double-precision complex variables. Such variables are not part of the FORTRAN 77 standard. Most compilers include them as an extension to the standard. If your compiler does not, you will not be able to compile double-precision REXPON and therefore will not be able to use double-precision ADVAN5.
Even the compilers that do allow this kind of variable may use different built-in function names. For example, REXPON uses the function DREAL to obtain the double-precision real portion of a double-precision complex number. Some compilers may require that a different function name be used instead. If your compiler produces error messages while compiling REXPON (or any other PREDPP subroutine), please call the NONMEM Consultant before changing the source code.
When bugs are found in PREDPP, the fixes are described in technical newsletters. Please check any newsletters that may have been sent with the NONMEM distribution medium or that are received afterwards. You will have to modify the source code and recompile portions of PREDPP.
As with NONMEM, you may notice that certain IMSL and LINPACK subroutines are used. Please do not substitute locally-installed versions of these routines. The versions distributed with NONMEM are somewhat different than the standard versions.
You should now compile the PREDPP subroutines separately using the FORTRAN 77 compiler and save the resulting object code in separate files for later use.
|
UNIX: |
f77 -O -c *.f >& emsgs.txt
Note that this will compile both Kernel and Library routines.
|
MS-DOS: |
Using PowerStation Fortran:
fl32 /c /G4 /Ox /Op *.for >
emsgs.txt
Use the same option /G3, /G4, or /G5 as for the compilation of NONMEM itself.
Using DIGITAL Visual Fortran:
df /c /optimize:1 /fpe:0 *.for > emsgs.txt
Note that these commands compile both Kernel and Library routines.
|
CMS: |
PPD2 EXEC COMPILE PPD2 EXEC ADDPPD ERASE * LISTING
Note that all Library object modules have been saved in "PPD TXTLIB A". However, only one Library subroutine for a given entry name can be retrieved from the library. TEXT files for routines from groups 1, 2, and 3 MUST remain on the local disk. TEXT files for routines and routine-groups from group 4 can be erased.
As with NONMEM, we recommend optimized, non-standard compiles. Similar warning messages to those seen with NONMEM may occur. Similar error messages concerning the include file SIZES may also occur, and it may be necessary to rename the include file. See Chapter III Section 3.
The simplest NONMEM-PREDPP test case is given in NONMEM Users Guide, Part VI, Figures 7 and 11. It performs the same analysis as does the test case for NONMEM, but using PREDPP rather than the PRED subroutine of NONMEM Users Guide, Part I. Differences in the output should be very slight. It requires a PK subroutine (Figure 7) and an ERROR subroutine (Figure 11). Read the subroutines from file "PK1" and file "ERROR1" of the distribution medium, or create them using your system editor.
IF YOU ARE INSTALLING SINGLE-PRECISION NONMEM, DELETE THE LINES STARTING "DOUBLE PRECISION ...".
Figure 25 is a NONMEM control stream, complete with data. Read it from file "CONTROL2" of the distribution medium, or create it using your system editor, being extremely careful to enter the file exactly as shown.
The PK and ERROR subroutines must now be
compiled and linked with the NONMEM routines and the
following PREDPP routines:
PRED, PREDI, CHECK, INFN, SADVAN, SSS0, ADVAN2, TRANS1
This list includes PREDPP Kernel routines, SSS0 (because
there are no steady-state doses in the data; see Section 1)
and the ADVAN and TRANS routines for the appropriate kinetic
model.
For UNIX, assume that NONMEM has been compiled in the directory /export/home/nmvi/nm, as before. Assume that all the PREDPP subroutines are in directory /export/home/nmvi/pr with the names given to them by program SEP. In the current working directory, assume that the PK and ERROR subroutines are in files pk1.for and error1.for. Because the command to build the executable is lengthy, it is easiest to construct two files. The first is a list of object files called build2.lnk, with the following lines:
/export/home/nmvi/pr/PRED.o /export/home/nmvi/pr/PREDI.o /export/home/nmvi/pr/CHECK.o /export/home/nmvi/pr/INFN.o /export/home/nmvi/pr/SADVAN.o /export/home/nmvi/pr/SSS0.o /export/home/nmvi/pr/ADVAN2.o /export/home/nmvi/pr/TRANS1.o
The second is a shell script, called (say) build2, containing the following commands:
ndir="/export/home/nmvi/nm" n="$ndir/NONMEM.o $ndir/BLKDAT.o $ndir/nonmem.a" f77 -O pk1.for error1.for ‘cat build2.lnk‘ $n
This is a Bourne shell script which can be run under either the Bourne shell or C-shell. If you choose to include comment lines, do not start the shell script with a line whose first character is ’#’, because this will cause it to be interpreted as a C-shell script. The character ‘ (grave, backquote) appears twice in the shell script. It is located the same key as ~ on many keyboards. ‘cat build2.lnk‘ means "the output of the command cat build2.lnk". Finally, don’t forget to make the shell script executable as follows:
chmod 755 build2
The command to build the executable is:
|
UNIX: |
build2
For MS-DOS, assume that NONMEM has been compiled in the directory c:\nmvi\nm, as before. Assume that all the PREDPP subroutines are in directory c:\nmvi\pr with the names given to them by program SEP. In the current working directory, assume that the PK and ERROR subroutines are in files pk1.for and error1.for. Because the command to build the executable is lengthy, it is easiest to construct two files. The first file is a linker command file, build2.lnk, with the following lines:
c:\nmvi\pr\pred.obj c:\nmvi\pr\predi.obj c:\nmvi\pr\check.obj c:\nmvi\pr\infn.obj c:\nmvi\pr\sadvan.obj c:\nmvi\pr\sss0.obj c:\nmvi\pr\advan2.obj c:\nmvi\pr\trans1.obj
The second is a batch file, build2.bat, with the following lines:
Using PowerStation Fortran:
set ndir=c:\nmvi\nm set n=%ndir%\nonmem.obj %ndir%\blkdat.obj %ndir%\nonmem.lib fl32 /G4 /Ox /Op pk1.for error1.for @build2.lnk %n% rename pk1.exe nonmem.exe
Using DIGITAL Visual Fortran:
set ndir=c:\nmvi\nm set n=%ndir%\nonmem.obj %ndir%\blkdat.obj %ndir%\nonmem.lib df /optimize:1 /fpe:0 pk1.for error1.for @build2.lnk %n% rename pk1.exe nonmem.exe
The command to build the executable is:
|
MS-DOS: |
build2
For CMS, we assume the following environment: NMD TXTLIB A and BLKDAT TEXT A are as before. The five Kernel PREDPP subroutines are part of PPD TXTLIB A. SSS0, ADVAN2 and TRANS1 have been compiled locally and exist as SSS0 TEXT A, ADVAN2 TEXT A and TRANS1 TEXT A. The PK and ERROR subroutines are in files PK1 FORTRAN A and ERROR1 FORTRAN A.
|
CMS: |
FORTVS PK1 FORTVS ERROR1 GLOBAL TXTLIB VSF2LINK VSF2FORT CMSLIB NMD PPD LOAD NONMEM BLKDAT PK1 ERROR1 ADVAN2 TRANS1 SSS0
The test case is run using commands similar to those of Chapter III, Section 4.3, but you must specify the new control stream and a new output file.
For UNIX, assume the NONMEM control stream is stored in file control2.
|
UNIX: |
a.out < control2 > report2
For MS-DOS, assume the NONMEM control stream is stored in file control2.
|
MS-DOS: |
copy control2 fcon nonmem copy output report2
For CMS, assume that the control stream is stored in file CONTROL2 DATA A.
|
CMS: |
FILEDEF FILE2 TERMINAL ( LRECL 133 FILEDEF 5 DISK CONTROL2 DATA A FILEDEF 6 DISK REPORT2 LISTING A ( LRECL 133 START
Compare the output report with the output report from the first NONMEM test case (Chapter III). You may see some slight discrepancies due to differences in arithmetic between PREDPP and the PRED subroutine, and also due to small differences in the problem specifications of the two test cases. However, the final value of the objective function and the final parameter estimates should be the same to the number of significant digits (3) that are printed. If a serious problem such as an operating system interrupt or an error message from NONMEM occurs, the most likely causes are that NONMEM, PREDPP, PK, and ERROR are not consistent as to precision (single vs. double), or that a keying error has been made.
If the output report appears correct, proceed to Chapter V.
TOP
TABLE OF CONTENTS
NEXT CHAPTER ...