Chapter IX - Further Information About NONMEM Files
This chapter contains a complete discussion of the files used by a NONMEM executable. Several of these files were discussed in earlier chapters. The final section presents a few considerations special to certain operating systems.
Three kinds of files are used during a NONMEM run: NONMEM required files, NONMEM optional files, and user files.
NONMEM required files:
|
control stream |
NONMEM optional files:
|
Table Files |
Optional user files:
|
NM-TRAN Library subroutines control
file |
This table lists the files and their default names and the logical unit numbers to which they are assigned. File names are used in FORTRAN OPEN statements.
† May be embedded in the control stream. †† In file control stream. ‡ Optional.
BLKDAT is discussed in Chapter III, Section 2.1.
Each type of file is discussed separately.
These files have been discussed earlier. Some of them may not actually be used during a NONMEM run, but their definition is required. When NM-TRAN is used, it builds the control stream and data file, and the user need not be concerned about their contents.
The control stream is read from FORTRAN unit 5. Each record must have length exactly 80 bytes. Some operating systems may generate a file with variable length physical records at the time the control stream is initially keyed in, and may fail to pad such records with trailing blanks at the time NONMEM reads them. In this case, the NONMEM support utility PAD may be useful; see Chapter X.
The first record in the control stream must be a FILE record. If no NONMEM optional file is used, the FILE record must be exactly as shown:
FILE NULL
The characters FILE are in positions 1-4 and the characters NULL are in positions 9-12 of the record.
If any NONMEM optional files are used, the FILE record gives the name of the file control stream, a file containing the names of the optional files. Then the FILE record is exactly as shown:
FILE filestreamname
The characters FILE are in positions 1-4 and the name of the file control stream is in a 72-byte field starting in position 9.
There must be exactly one FILE control record, even if the NONMEM run consists of multiple problems (i.e., even if the NONMEM control records which follow the FILE control record contain more than one PROBLEM ("PROB") record).
Part I and Part II of the NONMEM Users Guide describe the FILE record and the remaining records in the NONMEM control stream. They also describe multiple-problem control streams.
Data for a NONMEM run may be embedded in the control stream or read from separate files whose names are placed in the file control stream. In either case, NONMEM reads the data according to a FORTRAN format specification which is included in the control stream. When NM-TRAN is used, the data must always be in a separate file. If no format specification is supplied, NM-TRAN constructs one for NONMEM’s use.
When the data records are embedded in the control stream, they must have record length 80 bytes. When these are in a separate file, they may have any fixed record length. When NM-TRAN is used, the maximum record length is 300 bytes.
NONMEM’s report file is written to FORTRAN unit 6. It contains fixed length records of length 133 bytes. The first byte of each line is a FORTRAN carriage control character: blank, 0, 1, or +. Operating system commands should be used to direct unit 6 to a terminal, a printer, or a disk file for later review and/or printing. The last technique is the usual and safest approach. When the report is printed, it is necessary to convert the carriage control characters into characters understood by the printer.
Many UNIX systems include the fpr utility:
fpr < report-file | lpr
The output should be printed using a non-proportional font in landscape orientation. It may be necessary to redirect the output of fpr to a file and use a command other than lpr to print the file.
For CMS, the disk file should be given the file type LISTING. FORTRAN carriage control is then recognized automatically.
If the operating system does not offer any means for converting carriage control characters in the output report, the NONMEM support utility PRINT may be useful; see Chapter X.
Suggestions for modification of the OPEN statement for unit 6 are given in Chapter III, Section 2.1.1.
Intermediate output from the Estimation Step is written only when it is requested using the ESTIMATION ("ESTM") record of the NONMEM control stream (or, with NM-TRAN, using the $ESTIMATION record). If it is requested, it is written both to the output report and to the special file for intermediate output discussed in Chapter III. The special file is opened with the file name stored in BLKDAT variable FNINT.
This file will contain fixed length records of length 133 bytes. The first byte of each line is a FORTRAN carriage control character: blank or 0. Operating system commands should be used to direct the file to a terminal, to a dummy file, or to an unbuffered disk file.
Suppose the file name stored in FNINT is ’FILE2’. To see this output at the terminal for a given run, include the following:
ln -s /dev/tty FILE2
FILEDEF FILE2 TERMINAL ( LRECL 133
To suppress this output for a given run, include the following:
ln -s /dev/null FILE2
FILEDEF FILE2 DUMMY ( LRECL 133
Several options have been given for dealing with the special file for intermediate output. They give varying degrees of control over this file.
|
• |
If the BLKDAT constant FNINT is set to a value such as ’/dev/tty’ or ’/dev/null’ (in a UNIX system), then the choice has been made at compile time for all NONMEM runs. |
|
• |
If BLKDAT constant FNINT contains an ordinary file name as in the above examples, then the assignment of the device for the special file is made once for the entire NONMEM run (but for no other runs) using operating system commands. |
|
• |
A NONMEM run can consist of more than one problem. The choice of whether or not any intermediate output should be produced for a given NONMEM problem is made for that problem using a field of the ESTIMATION control record (or, with NM-TRAN, an option of the $ESTIMATION record) for that problem. |
The intermediate output from the Estimation Step discussed above contains iteration estimates of the unconstrained parameters (UCP). It may be helpful to see iteration estimates in the original parameterization. If NONMEM has been directed to write an Output Model Specification File, then it also writes the Intermediate Printout File containing iteration estimates in the original parameterization for those iterations whose summaries appear in the intermediate output.
The intermediate printout file is opened with the file name stored in BLKDAT variable FNINTR; by default it is INTER. It contains fixed length records of length 133 bytes. The first byte of each line is a FORTRAN carriage control character: blank or 0.
The intermediate printout file exists only during the duration of the run.
The file for PRED error messages is always opened. The name of the file is stored in BLKDAT variable FNERR; by default, it is PRDERR. The file contains fixed length records of length 133 bytes. The first byte of each line is a FORTRAN carriage control character: blank or 0.
NONMEM creates up to 23 temporary files. They are opened with file names FILE07 and FILE10, FILE11, FILE12, FILE13, ..., FILE25 and FILE31, FILE32, FILE33, and FILE35, FILE36, FILE37. (But see Section 2.1.2 of Chapter III). These files are normally deleted when they are closed at the end of the NONMEM run. If NONMEM is interrupted they will still exist and may be deleted. In CMS, if no FILEDEF statements are supplied for these files, they will have names such as FILE FILE7 A, FILE FILE10 A, etc.
For IBM batch operating systems it is necessary to include data definitions for these files. The following information may be helpful for this purpose, and may also be helpful with other systems.
The contents of this section has not been updated for NONMEM VI. However, the material is retained because it may be of interest to users who are installing NONMEM on a platform other than Unix, OS X or Windows.
The recommended DCB subparameters are:
The BLKSIZE values are based on values for NONMEM buffer sizes set in file SIZES.
Recommended primary and secondary space allocations for these files are:
The recommended primary allocations for files 7, 10, 11, 13, 14, 19, 20 and 33 are based on there being at most 1200 data records. The primary allocations for files 12, 15-18, and 23-25 are based on there being at most 400 individual records. The primary allocations for files 21-22 are based on there being at most 100 data records per individual record. The primary allocations for files 31-32 are based on there being at most 25 superproblems. These allocations are also based on values for the NONMEM buffer sizes (See Chapter III, Section 2.9.4).
See Chapter III, Section 4.3 for a discussion of the optional CMS FILEDEF statements for these NONMEM work files.
A Model Specification File (MSF) can be output by NONMEM. It is written only if requested by a field of the ESTIMATION control record (or, with NM-TRAN, an option of the $ESTIMATION record) for that problem. NONMEM can use the information in the MSF in a later run, either to resume the parameter search or to perform other tasks based on the final parameter estimates.
MSF files should be written to disk and saved carefully for future use because they can eliminate needless duplication of computing time.
The Model Specification File is opened by NONMEM using the file name found in the Model Specification Output (MSFO) record of the file control stream. In a multi-problem run, each problem using such a file should specify a different name for it. The MSF output is connected to the FORTRAN unit specified by BLKDAT array element UN(4) (default: 4).
For CMS, a FILEDEF should be provided connecting the file name (a ddname) to a disk file. If none is provided, CMS will give the disk file the name FILE ddname A.
For IBM batch operating systems it is necessary to include a data definition for each MSF. The following information may be helpful for this purpose, and may also be helpful with other systems.
The ddname is the file name specified on the MSFO record of the file control stream (or, with NM-TRAN, the file name specified using the MSFO option of the $ESTIMATION record). The DCB subparameters of a Model Specification File should include: RECFM=VBS and BLKSIZE=63596 for double precision and 40196 for single precision. The BLKSIZE values are based on values for NONMEM buffer sizes set in file SIZES. The primary and secondary space allocations should be 3 and 3 blocks, respectively.
An existing Model Specification File can be made available to NONMEM for input by specifying its name on a Model Specification Input (MSFI) record of the file control stream. (With NM-TRAN, this is done by specifying its name in an $MSFI record).
The MSF is opened by NONMEM using the name supplied for it. In a multi-problem run, each problem has its own MSFI record (or none at all), each of which may specify a different MSF. The MSF input is connected to the FORTRAN unit specified by BLKDAT array element UN(3) (default: 3).
For CMS, a FILEDEF should be provided connecting the file name (a ddname) to a disk file. If none is provided, CMS will give the disk file the name FILE ddname A.
In the case of an IBM batch operating system, the data definition statement should include the same DCB parameters that were used when the file was written.
NONMEM can be requested to generate tables as part of its output. Each table can be written to the output report file, to a disk file called a Table File for use by programs such as NONMEM and graphics packages, or to both. A given problem may write more than one table to a given Table File. A Table File is a sequential file with maximum record length 648 bytes.
When a table is to be written to a disk file, the name of the file is made available to NONMEM by specifying its name on a TABLE record of the file control stream. Each time a Table File is opened it is rewound by default, but alternatively, the user may request that the file be positioned at its end-of-file (with NM-TRAN, using the FORWARD option of the $TABLE record). If two different TABLE records in the file control stream name the same file and are contiguous, even "across two problems," the file is not reopened when the second table is output onto the file. If the two TABLE records are not contiguous, the file is reopened.
The Table File is opened by NONMEM using the name supplied for it. It is connected to the FORTRAN unit specified by BLKDAT array element UN(9) (default: 9).
For CMS, a FILEDEF must be provided connecting the file name (a ddname) to a disk file and including the option LRECL 132 (or larger).
A Table File does not include FORTRAN carriage control characters. Each table normally has two header lines similar to those appearing in the printed report. The first line of the nth. table starts ’TABLE NO. n’ and has format (A9,I3). The second line contains labels for the data items and has format (54(8X,A4)). Note that all header lines can be suppressed with an option of the NONMEM TABLE record (or, if NM-TRAN is used, the NOHEADER option of the $TABLE record).
Every line in the table containing data values has format (54(1X,1PE11.4)). Unlike the printed table, the lines are not numbered.
When there are more than 900 data records in a table, the table appears in 900-record sections, just as in the printed report. If there are 1488 records, for example, the first line of the first section is:
TABLE NO. 1 DATA RECS. 1 THROUGH 900
The first line of the second section is:
TABLE NO. 1 DATA RECS. 901 THROUGH 1488
The format of these lines is (A9,I3,6X,A10,I6,A8,I6). Each section contains a second header line with data labels. Note that header lines for the second and subsequent sections can be suppressed with an option of the NONMEM TABLE record (or, if NM-TRAN is used, the ONEHEADER option of the $TABLE record).
The File Control Stream is contained in a file whose name is given on the first control record (FILE) of the control stream. It contains the names of the data files if the data are not embedded in the control stream and the optional files used in the run. It is connected to the FORTRAN unit specified by BLKDAT array element UN(8) (default: 8).
User-supplied subroutines that are included in a NONMEM executable may also perform I/O to their own files.
The NM-TRAN Library Subroutines read a file (FLIB) that is written by NM-TRAN. File FLIB must remain in the current directory to be read during the NONMEM run. FORTRAN unit 41 is normally used for this file. To change the unit number, see Chapter VI, Section 2.2.
A user might supply a subroutine that requires I/O. FORTRAN logical units in the range 41-99 may be used. However, if NM-TRAN Library subroutines are included in the executable, unit 41 should not be used. If user files are output, it can be important to close them properly before the NONMEM run terminates. Use of the NONMEM utility FILES can help perform this function.
Whenever a FORTRAN OPEN statement or a CLOSE statement is executed in a user-supplied routine, NONMEM should be informed. This should be done as follows. Immediately after the OPEN or CLOSE statement is executed, a call should be issued to a NONMEM utility subroutine called FILES. The form of the call is simply:
CALL FILES (IUNIT)
where IUNIT is the number of the logical unit involved in the OPEN or CLOSE statement. When this is done, if a file is open when NONMEM terminates, the file is properly closed.
If reads or writes are issued to a given unit, but no OPEN statement for this unit is executed, then when ICALL is 0, a call to FILES should be issued (before any I/O statement involving this file is executed), where IUNIT is the number of the logical unit. However, reads and writes to a unit which has not been opened (connected) may not be allowed by some operating systems.
Many operating systems support the FORTRAN 77 capability of connecting different files to the same FORTRAN I/O unit. This capability is not essential for using NONMEM; however, it is a capability of which NONMEM can take advantage. An operating system that does not support this capability is referred to as a non file-dynamic operating system. Users of such an operating system must be aware of a few items.
First, the user is reminded that of the four types of file control records used in the file control stream, only one record of each type may appear in the entire stream.
Second, if a STOP message (as described in Chapter III, Section 2.3) appears at the end of the output report, there is no way to direct it to another file. Even if the NONMEM subroutine CFILES is changed to close and re-open unit 6 prior to the STOP statement, as described in that section, this will have no effect because the same file must be re-connected to the unit.
TOP
TABLE OF CONTENTS
NEXT CHAPTER ...