121 NONMEM
NONMEM V Supplemental Guide
1 General
2 More Etas, Epsilons, Thetas
The maximum number of θ’s allowable is set at 40. (☞)
The maximum number of η’s + ε’s allowable is set at 30. (☞)
The maximum number of parameters that may be estimated (not fixed in some way) is set to 70.
The maximum number of η’s allowable when the Laplacian estimation method is used with analytic second derivatives is set to 10.
These maxima may be increased.
See Guide III III.2.9.1
2.1 Changes to NONMEM Inputs
3 Band Symmetric Matrices
An initial estimate of a diagonal block of ether the OMEGA or SIGMA matrices may have a band symmetric form, in which case the final estimate has the same form.
4 Superproblems
A superproblem is a sequence of problems within a NONMEM run that can be iterated. With every iteration each problem is run exactly as was specified for the first iteration. Differences in the results from a given problem between iterations are due to differences to input files that have been made by later problems within the superproblem or, when the problem involves simulation, to different random numbers being used. There can be a one-level nesting of superproblems, one superproblem within another.
With NM-TRAN a superproblem is specified by including the record
$SUPERPROBLEM SCOPE=n ITERATION=mbefore the first $PROBLEM record of the superproblem.
See Guide VIII $super
5 COVARIANCE Record
Field 1 of the NONMEM COVARIANCE record may no longer have the value 1 (Covariance Step unconditionally implemented). It may have only values 0 (Conditionally implemented) or 2 (omitted).
The option UNCONDITIONAL of the NM-TRAN $COVARIANCE record is obsolete and is ignored; the Covariance Step cannot be implemented if the Estimation Step terminates unsuccessfully.
See Guide VIII $covariance
6 TABLE Record
Options PRINT, NOPRINT, HEADER, NOHEADER, and FILE of the NM-TRAN $TABLE record apply to the table defined by the record, and only to this table. They must be re-specified for each table to which they apply.
Tables may be written to the same or to different table files.
The list of labels may be as long as 50 with the NOPRINT option.
See Guide VIII $table
7 Large Data Files
NONMEM no longer needs a FINISH record when there are 10,000 or more records and when the NONMEM data set coincides with the NM-TRAN data set. If there is no FINISH record, the data are read to end-of-file.
8 Marginal (MRG_) Data Item
The marginal data item is a new NONMEM data item type. It identifies records for which NONMEM computes and displays marginal quantities (expectations). MRG_ is a reserved label for this data item.
See Guide VIII mrg_, expectation
9 Raw-Data (RAW_) Data Item
The raw-data data item is a new NONMEM data item type. It identifies template records for which NONMEM computes and displays raw-data averages. RAW_ is a reserved label for this data item.
See Guide VIII raw_, data_average_block, data_average_example
10 Model Specification Files
When intermediate output is requested in the Estimation Step, and a Model Specification File is also requested, NONMEM updates the MSF with every iteration summary. Thus, a run can be efficiently continued after it has been interrupted.
With previous versions of NONMEM it was not possible to input a MSF to repeat the Estimation Step using a method other than the one used to write the MSF. This is possible with NONMEM V, as long as the MSF contains the results of a search that terminated successfully.
10.1 Changes to NONMEM Output Files
11 New Output File INTER
It is now possible to see the iteration estimates in the original parameterization for those iterations whose summaries appear in intermediate printout, providing a MSFO is used. The estimates may be found in file INTER, which will exist only during the duration of the run.
See Guide VIII $estimation, monitoring_of_search
12 NONMEM Report
Minor changes have been made to the wording of certain lines in the NONMEM and PREDPP output. In addition, it is possible that the results of the Estimation and Covariance Steps may be slightly different than with earlier versions of NONMEM.
When a population conditional estimation method is used, for each element of η, the average conditional estimate of this element across individuals conditional on the final population parameter estimates (η̄) is output (ETABAR), along with a P-value (P VAL.) indicating how far the average is from 0.
The labels for η’s appearing in the output are ETA1, ETA2, … ETA9, ET10, ET11, … ET70 and ETA(1), ETA(2), etc.
Output from the Covariance Step will look the same as before, except that when the sizes of the arrays that are printed exceed the largest size that can occur with NONMEM version IV (i.e. 75x75), an alternative form of output for these arrays is used. This is a compressed form that may be advantageous to view, even if the sizes of the array do not exceed 75x75. With this form, all zero values due to a parameter being fixed in some way are not printed. Compressed format is obtainable for arrays of all sizes by including the option COMPRESS on the $COVARIANCE record.
See Guide VIII $covariance
The range of data records contributing to a scatterplot is printed in the header of the scatterplot when the user has explicitly specified this range or when the range doesn’t include all the records that one might want to examine. (☞)
Simulated η values are displayable in tables and scatterplots provided that the ETA array is defined in common NMPRD7 (which is automatic when abbreviated code is used) and provided the option ONLYSIMULATION appears on the $SIMULATION record.
See Guide VIII nmprd7
12.1 Changes to User-Written Code
13 PRED Routine Declarations
User-written PRED routines 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 an old $PRED block, however.)
See Guide VIII pred
14 ICALL
ICALL is an input argument of PRED, PK and other user-written routines. ICALL may now take values 5 and 6. These occur when NONMEM is computing expectations and raw data averages, which are new features of NONMEM V.
See Guide VIII data_average_block, mrg_, raw_
15 NEWIND
NEWIND is an argument of PRED and INFN and is available to PK and ERROR routines. The values of NEWIND have changed slightly.
NEWIND=0: First record of the data set. THETA value may differ from value at last call with this record.
NEWIND=1: First record of the data set, THETA value does not differ from value at last call with this record, and PRED is nonrecursive (with previous versions of NONMEM, this record would have had NEWIND=0).
NEWIND=1: First record of a subsequent individual record.
NEWIND=2: Subsequent data record of an individual record.
See Guide VIII pred, $pred, procm1
16 F
With the Simulation Step, PRED may return the simulated observation as the DV data item, rather than in the argument F. With odd-type data the simulated observation must be returned as the DV data item.
See below 23 (Likelihood)
17 NONMEM Read-Only Commons
There are new NONMEM read-only commons and changes to certain existing commons (in particular, ROCM6).
See Guide VIII NONMEM commons as well as separate entries for each common.
18 NONMEM-PRED Commons
There are new NONMEM-PRED commons and changes to certain existing commons.
See Guide VIII NONMEM commons as well as separate entries for each common.
User-written PRED routines that are recursive should signal this fact to NONMEM using COMMON NMPRD8. (☞)
19 The PASS Routine
PASS now stores the data record as PASSRC in common NMPRD9, as well as in PRED’s argument DATREC. It stores the NEWIND value as NEWND in common ROCM34, as well as in PRED’s argument NEWIND.
When PASS is used, any PRED-defined items that are displayed are now available in common NMPRD4 with each data record. If one is using $PRED, one may simply refer to these items by name as one is “passing through the data”. If one is using PREDPP and an INFN routine, and the items are computed in $PK or $ERROR, then one should store the items in the reserved region of NMPRD4 so that, if the INFN uses PASS, the INFN routine can know where to refer to these items.
See Guide VIII rocm34, nmprd9
20 The MIX Routine
A MIX routine need only set NSPOP once, at the problem initialization call (ICALL=1). This number may no longer change between individuals. However, if for a given individual, the second (for example) subpopulation doesn’t apply, then set P(2)=0 when MIX is called for that individual.
With earlier versions of NONMEM, a displayed value of an η was obtained under the subpopulation estimated as most probable. On the other hand, the displayed value of a PRED-defined variable was obtained using the estimate of η obtained under the highest-numbered of the subpopulations. With NONMEM V, the displayed value is obtained using the displayed value of η (i.e., under the most probable subpopulation). Values of the PRED-defined variable obtained using estimates of η under different subpopulations may be obtained and displayed as usual (by storing these values in COM variables allocated from the save region of common NMPRD4).
With the FO method, it has been possible to use a common η with two submodels. When conditional estimates are used, this has heretofore not been possible. Now it is possible. The conditional estimates of a common η will differ between the two submodels.
See Guide VII
20.1 New Methods of Estimation
21 METHOD=HYBRID ZERO=list
The Hybrid method is a hybrid between the FO and FOCE methods. The first-order expansion in η is made about a vector some of whose elements are 0 and others of which are a type of conditional estimate.
This method may be specified with $NM-TRAN, using the options METHOD=HYBRID and ZERO=list on the $ESTIMATION record.
See Guide VII
See Guide VIII $estimation
22 CENTERING, FO
A conditional estimation method may use centering, which constrains the average conditional estimate of η to be nearly 0. This is useful when the amount of data per individual is large and when there is a large degree of model misspecification. A better fit (albeit perhaps not a very good fit, as the model is misspecified) can result. This method should not be used during model development.
This method may be specified with $NM-TRAN, using the options METHOD=COND and CENTERING on the $ESTIMATION record. The option LAPLACIAN can also be used.
With centering, the First-Order model, obtained by using the first-order expansion in η about the zero vector, may be used.
This method may be specified with $NM-TRAN, using the options METHOD=COND, CENTERING, and FO on the $ESTIMATION record. The option LAPLACIAN cannot be used (because the model is linear in η).
See Guide VII
See Guide VIII estimation
23 NUMERICAL
The Laplacian method may be implemented using numerical second derivatives. Use of analytical second derivatives is preferable, but there are situations where it may be useful to try using numerical second derivatives. Use of numerical derivatives may result in significantly longer computation time.
Numerical second derivatives may be specified with $NM-TRAN, using the options METHOD=COND, LAPLACIAN, and NUMERICAL on the $ESTIMATION record.
See Guide VII
See Guide VIII $estimation
24 LIKELIHOOD, -2LOGLIKELIHOOD
By default, objective functions used with NONMEM are least-squares type functions, and as such, need not be considered to be related to likelihood functions. However, NONMEM allows data to be analyzed with an objective function equal to -2log likelihood for the data, and this is particularly necessary when the intraindividual distributions of the data are discrete and/or very asymmetrical. (For the purposes of this discussion, such data are called “odd-type” data.) To accomplish this, the value of F returned by the PRED routine with an observation may be set to the value of the conditional likelihood of η for the observation, given the values of the model parameters θ, rather than set to a prediction for the observation. The matrices G and H should be the usual derivatives of the expression used for F.
This different use of F is signaled by using the option LIKELIHOOD on the $ESTIMATION record. It is assumed that first-order type approximations are not being used, and so the LAPLACIAN option should also appear.
Alternatively, F may be set to the value of -2log conditional likelihood of η for the observation. This is signaled by using the option -2LOGLIKELIHOOD (or simply -2LL) in the $ESTIMATION record.
Odd-type data may also be simulated. For this purpose, PRED must return the value of a simulated observation as the DV data item (rather than in the argument F, as with standard-type data), a technique that will work even when the data are of standard-type.
See below 59 (Generated ID Data Items)
See Guide VIII $estimation, logistic_regression_example
25 CONTR, CCONTR
With earlier versions of NONMEM, odd-type data have been analyzed using special routines CONTR and CCONTR, which are not supported by the NONMEM Project Group. All versions of CONTR and CCONTR that have been used for this purpose with earlier versions of NONMEM should not be used with version V. The option LIKELIHOOD should be used instead.