12 Multiple Problems
1 Introduction
The possibility for multiple problem specifications to be processed in a single NONMEM run is discussed in this section. A single problem specification is just a sequence of control records (possibly with embedded FORTRAN records that generate a data set) that completely specify one problem. It consists of a single problem record, one or more (contiguous) Data Set Specification records, one or more (contiguous) Model Specification records, and one or more (contiguous) Task Specification records. A multiple problem specification (MPS) is simply the concatenation of two or more single problem specifications. Each of the single problem specifications comprising a multiple problem specification is also called an individual problem specification (IPS). If one individual problem specification immediately follows another in the MPS, these two individual problem specifications are called contiguous. If in a sequence of individual problem specifications, \(A_1, A_2, \ldots, A_n\) for each \(i < n\), \(A_i\) and \(A_{i+1}\) are contiguous, the sequence is called contiguous. Essentially, all that is necessary to process a multiple problem specification is to have the control stream (i.e. the input file containing the control records) consist of the MPS. Each IPS is processed in the order it appears in the MPS. Simple as all this may be, there still are aspects of the MPS that must be described, and there are certain features that a user may find advantageous. These matters are discussed in the subsequent sections.
2 Sharing a Data Set
In a MPS situation, the FORTRAN records generating data sets may be placed in a sequential input file separate from the control stream. If the first n FORTRAN records of this file generate a data set to be used with two or more individual problem specifications, then the user will want to rewind the FORTRAN unit containing this file. As mentioned in section 3.5 of NONMEM Users Guide, Part I, this can be done by placing a 1 in field 2 of the DATA record of any IPS with which the rewind is to occur.
An alternative way to use the same data set with two or more individual problem specifications is the following way. Suppose that a particular data set is used with one individual problem specification and that this data set is to be used with one or more succeeding individual problem specifications that, together with the first one, form a contiguous sequence of individual problem specifications. The data set is established with the first individual problem specification, and it need not be reestablished with the other problem specifications of the sequence. It has a representation internal to NONMEM that may be used with these other problem specifications. To refer NONMEM to this representation, in each of these other problem specifications it is only necessary to place a -1 in field 1 of the DATA records of each of them. In this case a FORMAT record need not and should not appear, and, of course, embedded data should not appear also, in any of the problem specifications of the sequence except the first one. In addition, all values placed in other fields of a DATA record with a -1 in field 1 are ignored. The number of data items per data record in each problem specification of the sequence is the same as the number of data items per record in the first one. (However, it is explained below how data items themselves can actually be made to vary between problems.) The complete format of the DATA record is given in Table 1.
| Field No. | Value | Function |
|---|---|---|
| 1 | -1 | Data set same as that for previous problem specification |
| 0 or blank | Data file embedded in the control stream | |
| between 20 & 99 | FORTRAN unit number for data file |
If the value is -1, the subsequent fields may be ignored.
| Field No. | Value | Function |
|---|---|---|
| 2 | 0 or blank | FORTRAN unit not to be rewound |
| 1 | FORTRAN unit to be rewound | |
| 3 | 0 or blank | FINISH record used |
| positive integer | number of data records | |
| 4 | between 1 & 20 | number of data items per data record |
The reader will recall that a data set may be modified with the use of the NONMEM utility PASS at either PRED initialization or finalization (see Section 11.2). At such a time, PRED can also write the modified data set onto a peripheral file so that this file may be read as the input data file in a subsequent problem in the same NONMEM run. Use of field 1 as just described will accomplish the same end when the subsequent problem immediately follows the current problem in the same run. The data set, as it exists at the end of PRED finalization, is “passed on” to the next problem. All data items may be modified by PRED at PRED initialization and/or finalization of the current problem, except for the ID and MDV data items. The ID and MDV data items may not be modified at any time. However, the indices of the DV, MDV and L2 data items may vary between problem specifications referring to the “same” data set. So, in particular, the MDV data items may differ between problem specifications referring to the “same” data set.
3 Model Specification Files
(See Help Items in Guide VIII, March 2008 for current information.)
Recall that the Model Specification File is physically one logical record of a sequential data set. Different individual problem specifications may specify different Model Specification Files be output onto the same data set (in which case in the data definition statement of the data set the disposition should be MOD.) Likewise, different individual problem specifications may specify different Model Specification Files be input from the same data set. If the Model Specification Files to be input, \(A_1, A_2, \ldots, A_n\), appear in the data set in the indicated order (with possibly other Model Specification Files between them), and this order is the one in which they are to be input, then simply specifying their identifiers on the FIND records allows them to be retrieved. However, if \(A_1\), is to be input after \(A_2\), say, then the FORTRAN unit containing the data set should be rewound after \(A_2\) is input and before \(A_1\) is input. The unit will be rewound before the Model Specification File is input if a 1 is placed in field 3 of the FIND record for that Model Specification File. Table 2 gives the format for the FIND record through this third field.
| Field No. | Value | Function |
|---|---|---|
| 1 | between 1 & 9999 | identifier for (existing) Model Specification File |
| 2 | between 20 & 99 | FORTRAN unit number for (existing) Model Specification File |
| 3 | 3 or blank | FORTRAN unit not to be rewound |
| 1 | FORTRAN unit to be rewound |
4 Embedding Files Into the Control Stream
The control stream is a sequential input file comprised essentially of the control records. However, sequential files of other types of records may be embedded in the control stream. For example, an input data file may be embedded. In addition though, two user supplied routines, PRED and CRIT, may require some sequential input files, and any of these files may also be embedded. Call the files for PRED to be embedded, PRED embedded files, and call the files for CRIT to be embedded, CRIT embedded files. Suppose F is a file to be embedded. To embed F in the control stream means to insert the records of F, altogether and in sequence, after either a control record or the last record of another embedded file. This means that the records of F, like the control records, must be 80 character records. If one file, \(F_2\), is inserted farther down the control stream than another file, \(F_1\), then \(F_2\) is said to be below \(F_1\). As explained below, files must be embedded only at particular places in the control stream.
An input data file for a given problem should be embedded after the FORMAT record for that problem.
The control stream is sequential and is read once only. Therefore, each PRED or CRIT embedded file, F, must be read entirely before any record of any other such file below F is read. Also therefore, F can be read once only.
It is now explained where the PRED and CRIT embedded data sets should be embedded in the control stream. Consider first a given problem, but not the first one. The situation for the first problem is a little more complicated and is described below. All CRIT embedded files for the problem (i.e. files read by CRIT when ICALL is 1 for the problem) must be below all PRED embedded files for the problem (i.e. files read by PRED when ICALL is either 1 or 3 for the problem). The first of the PRED and CRIT embedded files for the problem should be embedded after the last SCATTERPLOT record of the problem specification. There must be no control records between any of the PRED or CRIT embedded files for the problem. These PRED and CRIT embedded files are regarded as part of the problem specification.
For the purpose of this description then, all the PRED embedded files for the kth problem may be regarded as a single PRED embedded file, P(k). This file could be empty. Similarly, all CRIT embedded files for the kth problem may be regarded as a single CRIT embedded file, C(k). This file, too, could be empty. From the above it follows that when \(k \ge 2\), \(C(k)\) should occur below \(P(k)\) without any intervening control records, and that \(P(k)\) should be embedded after the last SCATTERPLOT record of the problem specification.
Now similarly, the PRED embedded files for NONMEM initialization (i.e. files read by PRED when ICALL is 0) should be regarded as a single PRED embedded file, P(0). Also, the CRIT embedded files for NONMEM initialization (i.e. files read by CRIT when ICALL is 0) should be regarded as a single CRIT embedded file, C(0). Then C(1) should occur below C(0), C(0) below P(1), P(1) below P(0), without any intervening control records, and P(0) should be embedded after the last SCATTERPLOT record of the first problem specification. The foregoing is summarized in Listing 1.
PROBLEM record
...
FORMAT record
<--------[input data set]
STRUCTURE record
...
SCATTERPLOT record
<--------[P(0)]
<--------[P(1)]
<--------[C(0)]
<--------[C(1)]
PROBLEM record
...
FORMAT record
<--------[input data set]
STRUCTURE record
...
SCATTERPLOT record
<--------[P(2)]
<--------[C(2)]
PROBLEM record
...5 Embedding Files into the Print Stream
NONMEM printed output is placed in a print file, PF. Print files generated by PRED or CRIT may be embedded in PF. Call the files from PRED to be embedded, PRED embedded files, and those from CRIT to be embedded, CRIT embedded files. Suppose F is a print file to be embedded, to embed F in PF means to input the records of F altogether after either a page of NONMEM print records or the last page of another embedded print file. (It is the responsibility of PRED (or CRIT) to insert a print control character that begins a new page of a PRED (or CRIT) embedded file when a new page is to begin.) If one file, \(F_2\) is inserted further down the PF than another file \(F_1\), then \(F_2\) is said to be below \(F_1\).
PF is, of course, sequential. Therefore, each PRED or CRIT embedded file, F, should be written entirely before any record of any other such file below F is written.
It is now explained where the PRED and CRIT embedded files are embedded in PP. Consider first a given problem, but not the first one. The situation for the first problem is a little more complicated, and is described below. There are two types of PRED embedded files for the problem. The first type is generated at problem initialization (i.e. when ICALL is 1), and the second type is generated at problem finalization (i.e. when ICALL is 3). There is only one type of CRIT embedded file, the type generated at problem initialization (i.e. when ICALL is 1). All type two PRED embedded files for the problem are below all CRIT embedded files, and all CRIT embedded files are below all type one PRED embedded files. The first of the PRED and CRIT embedded files for the problem is embedded after the last of the problem summary pages generated by NONMEM for the problem. There are no NONMEM print records dispersed among the records of the PRED or CRIT embedded files for the problem, provided no summarization of iterations from the Estimation Step is printed. If the summarization is printed, then these intermediate pages of output occur between the last page of the last CRIT embedded file (if this file exists, otherwise the last type one PRED embedded file) and the first page of the first type two PRED embedded file (if this file exists). In the event that error message R is issued from the Covariance Step (see section 6.4 of NONMEM Users Guide, Part I), no type two PRED embedded files are printed.
For the purpose of this description then, all type one (two) PRED embedded files for the kth problem may be regarded as a single type one (two) PRED embedded file P1(k) (P2(k)). This file could be empty. Similarly, all CRIT embedded files for the kth problem may be regarded as a single CRIT embedded file, C(k). This file too could be empty. From the above it follows that when \(k \ge 2\), \(P2(k)\) occurs below \(C(k)\), \(C(k)\) occurs below \(P1(k)\), \(P1(k)\) is embedded after the last of the problem summary pages for problem k, and \(P2(k)\) is embedded immediately before the first page of output from the Estimation Step for problem k.
Now similarly, the PRED embedded files for NONMEM initialization (i.e. files generated by PRED when ICALL is 0) should be regarded as a single PRED embedded file, P(0). Also, the CRIT embedded files for NONMEM initialization (i.e. files generated by CRIT when ICALL is 0) should be regarded as a single CRIT embedded file, C(0). Then P2(1) occurs below C(1), C(1) occurs below C(0), C(0) occurs below P1(1), and P1(1) occurs below P(0). Summarization of the iterations from the Estimation Step of the first problem occurs between C(1) and P2(1), if the summarization is output; otherwise there are no NONMEM print records dispersed among the records of these PRED and CRIT embedded files. P(0) is embedded after the last of the problem summary pages of the first problem. If error message R is issued from the Covariance Step, P2(1) is not printed. All of the foregoing is summarized in Listing 2.
PROBLEM Summary
<--------[P(0)]
<--------[P1(1)]
<--------[C(0)]
<--------[C(1)]
[ITERATION Summary]
...
<--------[P2(1)] only if message R does not occur
Estimation Step Summary
...
PROBLEM Summary
<--------[P1(2)]
<--------[C(2)]
[ITERATION Summary]
...
<--------[P2(2)] only if message R does not occur
Estimation Step Summary
...
PROBLEM Summary
...