55  Output Report

Items appearing in the NONMEM output report.

1 CORRELATION MATRIX OF ESTIMATE

MEANING: Part of NONMEM’s estimate of the precision of its parameter estimates

CONTEXT: NONMEM output

DISCUSSION:

Asymptotic statistical theory applied to extended least-squares estimation (as used in NONMEM) says that the distribution of the parameter estimators is multivariate normal, with variance-covariance matrix that can be estimated from the data. NONMEM supplies such an estimate of the variance-covariance matrix of the parameter estimates (See Section 55.2). The correlation matrix is the variance-covariance matrix in correlation form. If the correlation between two parameters is large (e.g., >.95), then one may conclude that a considerable portion of the uncertainty in each parameter is due to the inability of the data to distinguish between the two. The problem can be avoided by getting additional data or by using a simpler (fewer parameters) model.

**************** CORRELATION MATRIX OF ESTIMATE ********************

      TH 1             TH 2  OM11         OM12  OM22         SG11

TH 1         1.01E+00

TH 2  -2.85E-01 2.55E-02

OM11         8.87E-01 -6.77E-01 1.67E+01

OM12  ......... ......... ......... .........

OM22         2.81E-01 -9.96E-01 6.72E-01 ......... 1.31E-03

SG11  -4.83E-01 3.10E-01 -5.44E-01 ......... -2.67E-01 1.60E-01

The matrix (which is symmetric) is given in lower triangular form. In this example, the 2x2 matrix, OMEGA, was constrained to be diagonal; the omitted entries above (………) indicate that omega(2,1) is not estimated, and consequently has no corresponding row/column in the correlation matrix of the estimates.

With NONMEM 7.2 and higher, the diagonal elements are equal to the square root of the diagonal elements of the covariance matrix (standard error); with previous versions they were 1.0.

When the size of the array exceeds 75x75, a compressed form is printed in which the omitted entries (………) are not printed. The compressed form may also be requested for arrays smaller than 75x75 (See Section 50.8).

REFERENCES: Guide I, section C.3.5.2; Guide V, section 5.4

2 COVARIANCE MATRIX OF ESTIMATE

MEANING: NONMEM’s estimate of the precision of its parameter estimates

CONTEXT: NONMEM output

DISCUSSION:

From asymptotic statistical theory, the distribution of the parameter estimates is multivariate normal, with a variance-covariance matrix that can be estimated from the data. Such an estimate forms the basic output of NONMEM’s Covariance Step. The variance-covariance matrix is not to be confused with either SIGMA, the covariance matrix for the second level random effects, or with OMEGA, the covariance matrix for the first level random effects. These two matrices describe the variability of epsilons or etas, respectively, about their means. The variance-covariance matrix of the (distribution of) parameter estimates, on the other hand, describes the variability under the assumed model of the parameter estimates across (imagined) replicated data sets, using the design of the real data set. The following is an example of the NONMEM output giving the estimate of the variance-covariance matrix.

**************** COVARIANCE MATRIX OF ESTIMATE ********************

            TH 1      TH 2      OM11     OM12        OM22   SG11

TH 1        1.02E+00

TH 2        -7.34E-03 6.50E-04

OM11        1.50E+01 -2.88E-01 2.78E+02

OM12        ......... ......... ......... .........

OM22        3.73E-04 -3.33E-05 1.47E-02 ......... 1.72E-06

SG11        -7.79E-02 1.26E-03 -1.45E+00 ......... -5.59E-05 2.55E-02

The matrix (which is symmetric) is given in lower triangular form. In this example, the 2x2 matrix, OMEGA, was constrained to be diagonal; the omitted entries above (………) indicate that OM12 is not estimated, and consequently has no corresponding row/column in the variance-covariance matrix. When the size of the array exceeds 75x75, a compressed form is printed in which the omitted entries (………) are not printed. The compressed form may also be requested for arrays smaller than 75x75 (See Section 50.8).

The (estimated) variance-covariance matrix is computed from the R and S matrices; it is \(R^{-1} S R^{-1}\), where \(R^{-1}\) is the inverse of the R matrix. The R matrix is the Hessian matrix of the objective function, evaluated at the parameter estimates. The S matrix is obtained by summing the cross-product gradient vectors of the individual-based objective functions, evaluated at the parameter estimates. The individual-based objective functions are the separate terms contributed by each individual’s data to the overall objective function, and the cross-product gradient vectors are summed across the individuals in the data set.

The inverse variance-covariance matrix \(R S^{-1} R\) is also output (labeled as the Inverse Covariance Matrix), where \(S^{-1}\) is the inverse of the S matrix. If S is judged to be singular, a pseudo-inverse of S is used, and since a pseudo-inverse is not unique, the inverse variance-covariance matrix is really not unique. In either case, the inverse variance-covariance matrix can be used to develop a joint confidence region for the complete set of population parameters. As we usually develop a confidence region for a very limited set of population parameters, this use of the inverse variance-covariance matrix is somewhat limited.

An error message from the Covariance Step stating that the R matrix is not positive semi-definite suggests that the parameter estimate does not correspond to a true (local) minimum and is not to be trusted. (It may be a saddle point.) An error message stating that the R matrix is positive semidefinite, but singular, indicates that the objective function is flat in a neighborhood of the parameter estimate, and so the minimum is not really unique, and there is probably some overparametrization. With both error messages, neither a variance-covariance matrix nor inverse variance-covariance matrix is output. An error message stating that the S matrix is singular indicates strong overparameterization. However, provided the R matrix is judged to be positive semidefnite and nonsingular (i.e. positive definite), both the variance-covariance and inverse variance-covariance matrices are output.

When the R matrix is judged to be singular, but positive semidefinite, then the T matrix, \(R S^{-1} R\), where \(S^{-1}\) is the inverse (or a pseudo-inverse) of the S matrix, is output. This cannot be called the inverse covariance matrix, as the covariance matrix does not exist. However, as with the inverse variance-covariance matrix, T can be used to develop a joint confidence region for the complete set of population parameters.

There are options that allow the variance-covariance matrix to be computed as either \(2R^{-1}\) or \(4S^{-1}\). Asymptotic statistical theory suggests that these matrices are appropriate under the additional assumption that the objective function is indeed additively proportional to minus twice the log likelihood function for the data.

Unless the reported number of significant digits in the final parameter estimate is at least as large as the requested number of significant digits, the Covariance Step will not be implemented. (See sig digits). Sometimes, the number of significant digits is not reportable. However, when it is and the user thinks this number to be adequate, and a model specification file was output (See Section 52.2), NONMEM may be run again where the Covariance Step is implemented, while the Estimation step is is not repeated (i.e. the MAXEVAL option is set to 0). With the subsequent run, the model specification file should be input, and the requested number of significant digits should be set to a value less than the reported number of significant digits from the first run (presumably, this value would be the reported number rounded down to the highest integral value).

(See standard error, Section 55.1).

REFERENCES: Guide I, section C.3.5.2; Guide II, section D.2.5; Guide V, section 5.4, 13.3

3 DISPLAYED PRED-DEFINED ITEMS

MEANING: Displayed values of PRED-Defined Items

CONTEXT: NONMEM output

DISCUSSION:

PRED-defined items can be displayed in tables and scatterplots. (This includes PK-defined and ERROR-defined items.) These items are computed and recomputed many times during a NONMEM run, with various values of theta and eta. It is important to know which values are used in the computation of the items as displayed.

Consider this fragment of an NM-TRAN control stream:

$PK
CL = THETA(1) * EXP(ETA(1))
$TABLE CL ETA(1)

The values of ETA(1) and the PRED-defined item CL that are displayed depend on which task specification records are present.

Task specification records THETA Displayed values

none initial ETA(1) CL
$EST (or $MSFI) METH = 0 final
$EST (or $MSFI) METH = 1 or POSTHOC final 0 typical

$SIMULATION initial 0 typical
$SIMULATION ... ONLYSIM initial
$NONPARAMETRIC ETAS final conditional conditional

(CPE) (CPE)

0 typical

simulated simulated

nonparametric nonparametric

(CNPE) (CNPE)

Displayed etas are the simulated etas if the simulated etas are stored in common NMPRD7. This is the case when NM-TRAN is used. If they are not stored in NMPRD7, displayed etas are all 0.

Displayed values of PRED, RES, and WRES are always computed with typical values of parameters, except as noted below.

Displayed values of DV are simulated values when $SIMULATION is present.

With NONMEM 7, Additional types of PRED, RES, and WRES values may be requested than the usual set available in NONMEM VI. They may be specified at any $TABLE command or $SCATTER command, as one would request PRED, RES, or WRES items. Such items are supplied internally by NONMEM, and in the case of L2 data, more accurately. An example of their use is in Example #4a, below.

Every NONMEM output report contains the line:

THE FOLLOWING LABELS ARE EQUIVALENT

Subsequent lines show the relationship of such items for the current Estimation method. (See Section 50.46, $scatter). (See Section 53.79, Section 55.16, Section 55.16). See INTRODUCTION TO NONMEM 7, $TABLE: Additional Statistical Diagnostics, Associated Parameters, and Output Format.

Suppose that marginal items appear. If this item is 1 or 2 on a given record, the values of PRED and any PRED-defined displayed item D (assuming D is not in the SAVE region (See Section 53.13) associated with this record) are determined as follows:

  • If the Simulation Step is implemented, and ONLYSIMULATION is specified, the PRED item is the simulation expectation of F, over the simulated values of eta for all the individuals in the data set (including those individuals with no observation records), and the D item is the simulation expectation of the variable D.
  • If conditional estimates are obtained (e.g. with the use of the POSTHOC option), the PRED item is the posterior expectation of F, over the conditional estimates of eta for all individuals in the data set (that have some observation records), and the D item is the posterior expectation of the variable D.
  • Otherwise, the PRED and D items are the same as with a marginal item of 0 (See description above).

Suppose that the raw-data items appear. If this is 1 on a given record, the values of the DV, RES, and any PRED-defined displayed item D (assuming D is in the SAVE region (See Section 53.13) associated with this record) are determined as follows:

The data record serves as a template record. The DV item appearing in a table or scatterplot is the raw-data-average of the values of DV in observation records matching the template record. The RES item is the difference between the PRED item and this average. A PRED-defined item D is the average of the values of D obtained with observation records matching the template.

(See mrg, raw, template).

Several examples will illustrate techniques for displaying (subject-specific) conditional values, (non-subject-specific) typical values, and simulated values.

#1 Display typical and conditional values using different variables:

$PK
...
TVCL = THETA(1)
CL = TVCL * EXP(ETA(1))
$ESTIM ... POSTHOC ...
$TABLE TVCL CL

TVCL is a typical value by definition. CL is a conditional value.

#2 Display typical and conditional values of the same variable:

$PK
...
CL = THETA(1) * EXP(ETA(1))
IF (COMACT == 1) TVCL = CL
$ESTIM ... POSTHOC ...
$TABLE TVCL CL

TVCL is a SAVE variable because it is defined in a copying block. During the copying pass with COMACT=1, it is set to the typical value of CL, because when COMACT=1, etas are 0. Were the values of TVCL not stored in the SAVE region, then during the copying pass to obtain values for tables and with COMACT=2, TVCL would retain its value set with the previous data record.

The first column of the table is labelled TVCL and contains the typical value of CL, and the second column contains the conditional value.

#3 Display typical and conditional values of the prediction, and the individual residual and weighted residual values:

$ERROR
IPRED = F
IRES = DV - IPRED
IWRES = IRES / IPRED
Y = F + EPS(1)
$ESTIM ... POSTHOC ...
$TABLE IPRED IRES IWRES

The IPRED column contains the conditional value of F (“individual prediction”). (F is not a left-hand quantity and cannot be specified in a $TABLE or $SCATTERPLOT record.) The PRED column contains the typical value. The IRES column contains the “individual residual”. The IWRES column contains a value which is proportional to (but not equal to) the “individual weighted residual”.

If predicted values of F may be zero, then division by zero can be avoided by code such as the following.

$ERROR
IPRED = F
IRES = DV - IPRED
DEL = 0
IF (IPRED == 0) DEL = 1
IWRES = (1 - DEL) * IRES / (IPRED + DEL)
Y = F + EPS(1)

#4 Display intra-individual weighted residual:

This uses the constant CV intraindividual error model, and allows one to display the weighted intra-individual residual that is used during Estimation when the FOCE method without interaction is used.

$ERROR
Y = F + F * EPS(1)
IPRED = F
IF (COMACT == 1) FT = F
IF (FT /= 0) WR = (DV - IPRED) / FT / SQRT(SIGMA(1,1))
IF (IPRED /= 0) WR2 = (DV - IPRED) / IPRED / SQRT(SIGMA(1,1))
$ESTIM METHOD = COND
$TABLE FT IPRED WR WR2

IPRED is the conditional estimate of F. FT is a SAVE variable because it is defined in a copying block. During the copying pass with COMACT=1, it is set to the typical value of F, because when COMACT=1, etas are 0. Were the values of FT not stored in the SAVE region, then during the copying pass to obtain values for tables and with COMACT=2, FT would retain its value set with the previous data record.

WR is the weighted intraindividual residual with no eta-eps interaction. It is defined in a conditional assignment since it is possible that the typical value of F is zero with some non-observation record. (With previous versions of the help guide the SIGMA term was omitted and the WR was proportional to the weighted intraindividual residual.) It is a no-interaction residual because the denominator term, the residual standard deviation FT*SQRT(SIGMA(1,1)), represents the epsilon error, and uses the predicted value (FT) evaluated with eta=0, that is, eta does not interact with the epsilon error. WR2 is the conditional intra-individual weighted residual with eta-eps interaction. It is an eta-eps interaction residual because the denominator term, the residual standard deviation IPRED*SQRT(SIGMA(1,1)), represents the epsilon error, and uses the predicted value (IPRED) evaluated with a non-zero eta, that is, eta interacts with the epsilon error.

#4a Display intra-individual weighted residual using reserved variables

With NONMEM 7, It is possible to obtain the same table more easily, as follows, using the reserved residual variables CIWRES (=WR) and CIWRESI(=WR2):

$ERROR
Y = F + F * EPS(1)
$ESTIM METHOD = COND
$TABLE IPRD CIPRED CIWRES CIWRESI

#5 Display simulated values:

$PK
...
CL = THETA(1) * EXP(ETA(1))
...
$SIMULATION (seed) ONLYSIM
$TABLE ETA(1) CL

ETA(1) and CL are simulated values.

#6 Display simulated and estimated values:

$INPUT .... CLSM E1SM ...
$PK
...
CL = THETA(1) * EXP(ETA(1))
IF (ICALL == 4) THEN
 CLSM = CL
 E1SM = ETA(1)
ENDIF
$SIMULATION (seed)
$ESTIM
$TABLE CLSM E1SM CL ETA(1)

Modification of the data record during the simulation pass is the only way to save the simulated values in the absence of ONLYSIM. Column 1 and 2 of the table are the simulated values. Column 3 and 4 are the typical values.

#7 Display conditional values of a variable in each of two mixture subpopulations:

$PK
...
IF (MIXNUM == 1) CL = ...
IF (MIXNUM == 2) CL = ...
IF (COMACT == 2) THEN
 IF (MIXNUM == 1) CL1 = CL
 IF (MIXNUM == 2) CL2 = CL
ENDIF
$ESTIM ... POSTHOC ...
$TABLE CL1 CL2

CL1 (and CL2) is a SAVE variable because it is defined in a copying block. Were the values for CL1 not stored in the SAVE region, during the copying pass to obtain values for tables and with MIXNUM=2, CL1 would retain its value set with the previous data record.

#8 Display conditional values of a variable in the subpopulation into which the individual is classified:

$PK
...

IF (MIXNUM == 1) CL = ...
IF (MIXNUM == 2) CL = ...
IF (COMACT == 2 .AND. MIXNUM == MIXEST) CLE = CL
$ESTIM ... POSTHOC ...
$TABLE CLE

CLE is a SAVE variable because it is defined in a copying block. Were the values for CLE not stored in the SAVE region, during the copying pass to obtain values for tables and with MIXNUM>MIXEST, CLE would retain its value set with the previous data record.

REFERENCES: Guide IV, section III.B.7, IV.E.2; Guide VI, section III.J, IV.E; Guide Introduction_7

4 ETABAR

MEANING: NONMEM’s estimate of the bias in the underlying assumption about eta.

CONTEXT: NONMEM output

DISCUSSION:

ETABAR is printed when a conditional population estimation method is used. The following is an example.

 ETABAR IS THE ARITHMETIC MEAN OF THE ETA-ESTIMATES,
 AND THE P-VALUE IS GIVEN FOR THE NULL HYPOTHESIS THAT THE TRUE MEAN IS 0.

ETABAR:   -3.5224E-02 -7.1437E-05 2.5095E-03
SE:
N:        3.4060E-01 3.1223E-03 1.9001E-01

            12       12            12

P VAL.:   9.1763E-01 9.8175E-01 9.8946E-01

The ith number listed after “ETABAR” is the sample average (across individuals) of the conditional estimates of the ith eta, and the ith number listed after “SE” is the standard error for this average. Under the assumed model, the population average of the the conditional estimates is approximately zero. If the model is well-specified, the sample average should be near 0. (but see below for a mixture model). The P-value helps one assess whether the sample average is “far” from 0. A value under 0.05, for example, indicates such an average (notice the value 0.32E-02).

With a mixture model, the ith eta is understood to have a different distribution for each subpopulation of the mixture. Accordingly, different instances of the above output will appear, one for each of the different subpopulations. Using a standard Bayesian-type computation, each individual is classified into one of the subpopulations, and the conditional estimate of the ith eta under the model for this subpopulation is used in the sample average for that subpopulation. If under the mth submodel, the ith eta does not influence the data from any individual, but it does influence the data from some individual under some other submodel, then the sample average for the ith eta for the mth submodel will be 0. If the ith eta does not influence the data from any individual under any model, then the sample average for the ith eta for the mth submodel will usually be 0, but it will not be if (i) the ith eta is correlated with an eta that influences some individual’s data under the mth submodel, and (ii) that individual is classified to be in the mth subpopulation.

The population average of the conditional estimates is only approximately zero because a conditional estimate is a (Bayesian) posterior mode, and not a posterior expectation. However with a mixture model, with the estimate for a given individual, the posterior distribution is that for the subpopulation into which the individual is classified, and due to possible missclassification the expectation of the estimate may be even “further from” zero than with a nonmixture model. For this reason too, the centered FOCE method may not work well with a mixture model.

With a mixture model, or with a nonmixture model, one may implement a second Estimation Step (in a subsequent problem), and then a second ETABAR estimate (EB2) can be obtained, with which the first ETABAR estimate (EB1) can be compared. If the data-analytic model is well-specified, the two estimates should represent nearly the same quantity. Using an option on the $ESTIMATION record, the second P-value assesses the magnitude of the difference between EB1 and EB2, and a P-value under 0.05 would suggest that the data-analytic model is not well-specifed. To obtain EB2, a data set is simulated under the fitted model, and EB2 is obtained using this data set. Both EB1 and EB2 are (univariate) measures of central tendency of the distribution of interindividual “residuals”, i.e. the distribution of the conditional estimates of the etas. In both cases the residuals are defined in terms of the data-analytic model. But for EB1, the distribution is governed by the true (unknown) model, and for EB2, the distribution is governed by the fitted model. If the two models are “close”, EB1 and EB2 will be close. The conditional estimates of the etas from the simulated data should be based on the population parameter estimates from these data. It may cost considerable CPU time to obtain this second set of parameter estimates, and so it may not always be feasible to compute EB2.

One proceeds by constructing a problem specification that

  1. includes the same $INPUT record as was used with a previous problem wherein EB1 was obtained

  2. includes an $MSFI record specifying a model specification file from that previous problem, so that in particular, EB1 is available

  3. includes a $SIMULATION record with the option TRUE=FINAL, so that a data set will be simulated using the final parameter estimate from that previous problem.

  4. includes a $ESTIMATION record with the option ETABARCHECK (and either the option METHOD=COND or METHOD=HYBRID).

A data set will be simulated, and EB2 will be obtained. With the ETABARCHECK option, the P-value for the difference EB2-EB1 will be computed. Otherwise, if the model is a nonmixture model, EB1 is ignored, and the P-value will be simply that for EB2, and if the model is a mixture model, no P-value will be output (only the standard error for EB2 will be output). The numbers of data and/or individual records in the simulated data set may differ from those for the previous problem; so if desired, this data set can be much larger than the real data set.

REFERENCES: Guide VII, section II.A, III.D

5 FINAL PARAMETER ESTIMATE

MEANING: Final estimates of parameters THETA, OMEGA, SIGMA

CONTEXT: NONMEM output

DISCUSSION:

A page with the title FINAL PARAMETER ESTIMATE is printed as part of every NONMEM output.

If the Estimation Step was NOT run, then the values printed are the initial parameter estimates specified for the problem.

If the Estimation Step WAS run, then the values printed are the final parameter estimates.

These estimates of parameters are used by NONMEM to compute the objective function value printed on the page with title “MINIMUM VALUE OF OBJECTIVE FUNCTION” and to compute predicted values for Tables and Scatterplots.

********************  FINAL PARAMETER ESTIMATE ***************
THETA - VECTOR OF FIXED EFFECTS PARAMETERS   *******

        TH 1      TH 2      TH 3
        1.94E+00  1.02E-01  3.20E+01

OMEGA - COV MATRIX FOR RANDOM EFFECTS - ETAS ********

         ETA1
ETA1   8.99E-01

OMEGA - CORR MATRIX FOR RANDOM EFFECTS - ETAS *******

         ETA1
ETA1   9.48E-01

This example is from a run involving single-subject data, so there is no SIGMA matrix.

With NONMEM 7.2 and higher, the correlation matrix is included. It is computed from the covariance matrix, whether or not the Estimation step is not run.

(See initial parameter estimate).

With NONMEM 7.3 and higher, the $THETAR record may be used to transform final estimates of THETA before they are reported in the NONMEM output. (See Section 50.50).

REFERENCES: Guide V, section 10.5

6 FNLETA

MEANING: FNLETA subroutine

CONTEXT: NONMEM routine

DISCUSSION:

FNLETA is a NONMEM routine. An error message from FNLETA indicates that NONMEM has experienced difficulties obtaining posthoc etas.

REFERENCES: None.

7 HESSIAN

MEANING: A matrix computed by NONMEM

CONTEXT: NONMEM output

DISCUSSION:

The Hessian matrix is the second derivative matrix of the objective function with respect to the parameters of the model. NONMEM computes Hessian matrices for several purposes.

Estimation Step
A rough numerical approximation to the Hessian is maintained during the minimization search. The following message in the intermediate output refers to this matrix: 
RESET HESSIAN

Explanation: The search starts with the Hessian set to the identity matrix. The Hessian is updated after each iteration, using a rank 1 update procedure. When there is no longer a sensible direction to take, but convergence has not been achieved, this may be due to inadequacy of the updated Hessian. Then the Hessian is reset to a certain positive semi-definite diagonal matrix, and a new direction computed from this matrix (and the gradient vector) is tried.

The appearance of the message indicates why an unusually large number of function evaluations were used for the iteration (extra ones were needed to compute the new Hessian and perform a line search along the new direction) and why an unusually long CPU time was needed for the iteration (if intermediate output is being monitored). Its appearance suggests that the search is not going easily, and perhaps (not necessarily) something is wrong.

Covariance Step
A good numerical approximation to the Hessian is computed at the final parameter estimates. It is referred to as the R matrix.
Obtaining Conditional Estimates
In this case, the Hessian matrix is the second derivative matrix of the conditional objective function. The following error messages refer to this matrix: 
HESSIAN OF OBJ. FUNCT. FOR COMPUTING CONDITIONAL ESTIMATE IS
NON POSITIVE DEFINITE

NUMERICAL HESSIAN OF OBJ. FUNC. ...

REFERENCES: Guide IV, section III.B.15

REFERENCES: Guide V, section 12.4.6

REFERENCES: Guide VII, section II.A

8 INFERENTIAL STATISTICS

MEANING: Inferential statistics

CONTEXT: NONMEM output

DISCUSSION:

NONMEM provides estimates of the precision of its parameter estimates.

Confidence intervals for parameters, hypothesis tests on parameter values, and model-building all require determination of plausible bounds on parameters. These can be assigned if the distribution of the estimates (upon imagined replication of the data set) can be estimated. Asymptotic statistical theory applied to extended least-squares estimation (as used in NONMEM) says that the distribution of the parameter estimators is multivariate normal, with variance-covariance matrix that can be estimated from the data. NONMEM supplies such an estimate of the variance-covariance matrix of the parameter estimates (See Section 55.2). The square roots of the diagonal elements of that matrix are the estimated standard errors of the corresponding parameter estimators (See Section 55.19), while the off-diagonal elements can be transformed into correlation coefficients, and are presented in the correlation matrix of the parameter estimates (See Section 55.1). The inverse of the covariance matrix and the eigenvalues of the correlation matrix are also available (See Section 50.8).

REFERENCES: Guide V, section 5.4

9 INITIAL ESTIMATE (INITIAL EST)

MEANING: Initial estimates of parameters THETA, OMEGA, SIGMA

CONTEXT: NONMEM output

DISCUSSION:

Initial estimates of parameters are required by NONMEM. They are used, for example, to compute the initial value of the objective function (before NONMEM begins its search for final estimates). The user may provide initial estimates. Alternatively, he may request that NONMEM provide initial estimates.

(NONMEM may also use as initial estimates the final estimates from a previous run, by means of a Model Specification File; (See Section 52.2). When an MSFI is used, the outputs described here do not appear.)

NONMEM output reflects initial estimates provided by the user on its problem summary page as in this example:

INITIAL ESTIMATE OF THETA:

LOWER BOUND INITIAL EST     UPPER BOUND
                            0.1000E+07
0.0000E+00  0.1500E+03      0.0000E+00
                            0.1000E+02
0.0000E+00  0.0000E+00      0.1000E+07

0.1000E+00  0.3000E+00

-0.1000E+07 -0.1000E-01

INITIAL ESTIMATE OF OMEGA:

0.2500E+00

0.0000E+00 0.2500E+00

INITIAL ESTIMATE OF SIGMA:

0.2500E+00

The above states that:

  1. The initial estimate of theta(1) is 150, and the parameter is constrained to be greater than zero (no upper bound).
  2. Theta(1) is fixed at zero.
  3. The initial estimate of theta(3) is .3, and the parameter is constrained to lie between .1 and 10.
  4. The initial estimate of theta(4) is -.01, and the parameter is unconstrained.
  5. OMEGA is 2x2 and constrained to be diagonal (signified by the 0 value of the initial estimate of omega(2,1); the initial estimates of omega(1,1) and omega(2,2) are .25.
  6. SIGMA is 1x1 (a scalar), with initial estimate .25.

If the initial estimate of an element of THETA is left blank, this indicates that the user has requested that NONMEM provide the initial estimate, as in this example:

INITIAL ESTIMATE OF THETA:  UPPER BOUND
LOWER BOUND INITIAL EST     0.1000E+02
0.1000E+00

Similarly, if the initial estimate of all or part of OMEGA and/or SIGMA is not printed, this indicates that the user has requested that NONMEM provide the missing initial estimate(s).

NONMEM performs a search for missing initial estimates as its first task. With NONMEM 7.4, when initial thetas are to be estimated, evaluations can now be done for FOCE and Laplace, not just for FO. The complete set of initial estimates (including those provided by the user and those provided by NONMEM) are printed on a separate page under the heading “INITIAL PARAMETER ESTIMATE”, as in the following example. The format is identical to that of the “FINAL PARAMETER ESTIMATE” page. If all initial parameter estimates are provided by the user, this page does not appear.

******************** INITIAL PARAMETER ESTIMATE ***

THETA - VECTOR OF FIXED EFFECTS PARAMETERS **********

            TH 1                 TH 2  TH 3

            1.50E+00 1.02E-01 2.90E+01

OMEGA - COV MATRIX FOR RANDOM EFFECTS - ETAS ********

            ETA1

ETA1 1.50E+00

This example is from a run involving single-subject data, so there is no SIGMA matrix.

(See Section 55.5).

REFERENCES: Guide IV, section III.B.9, III.B.10, III.B.11

10 MINIMUM VALUE OF OBJ. FUNCTION

MEANING: The value of the objective function

CONTEXT: NONMEM output

DISCUSSION:

The NONMEM OBJECTIVE FUNCTION is a goodness of fit statistic; the lower the value, the better the fit. Negative values are possible and have no special significance. Under certain assumptions, the (default) objective function value is minus twice the log likelihood.

A page with the title MINIMUM VALUE OF OBJECTIVE FUNCTION” is printed as part of every NONMEM output, as in this example.

******   MINIMUM VALUE OF OBJECTIVE FUNCTION       ***********

*****************  11.570             ******************************

If the Estimation Step was NOT run, then the value printed is the value of the objective function using the initial parameter estimates specified for the problem.

If the Estimation Step WAS run, then the value printed is the value of the objective function with the final parameter estimates.

Differences in the objective function of fits of the same data to hierarchical models can often be used to test approximately the plausibility of the smaller (fewer free parameters) model by referencing the difference to a chi-square distribution with degrees of freedom equal to the difference in the number of free model parameters between models (hypothesis tests).

Sometimes NM-TRAN may generate this warning message:

(WARNING 68) THE INTEGER FUNCTION IS BEING USED OUTSIDE OF A SIMULATION
 BLOCK. IF THE INTEGER VALUE AFFECTS THE VALUE OF THE OBJECTIVE FUNCTION,
 THEN AN ERROR WILL PROBABLY OCCUR.

In general, any code that affects the value of the prediction F (with $PRED) or Y (with $ERROR), or their eta and eps partials, affects the value of the objective function. Such code must be continuous, e.g., must not use functions such as INT or MOD, and must not involve conditional statements that introduce discontinuities. The following examples use Model Event Time parameters (MTIME) to avoid discontinuities in differential equations:

  • Model Time examples
  • Examples Using MTIME to Model Periodic Discontinuities in $DES
  • Enterhepatic circulation examples

(See mtime, Section 60.39).

(See Circadian Example: Examples Using MTIME to Model Periodic Discontinuities in $DES)

(See Section 60.25).

REFERENCES: Guide I, section C.3.5.1

REFERENCES: Guide V, section 5.5

12 NONMEM ERROR MESSAGES

MEANING: Error messages

CONTEXT: NONMEM output

USAGE:

DISCUSSION:

This is not a complete list. It includes only commonly seen error messages.

Section I. Errors in the control stream

FILE RECORD MISSING

There is something wrong with the NONMEM control file. Probably it is an NM-TRAN control file (starting with $PROBLEM), rather than the FCON file produced by NM-TRAN.

TOT. NO. OF OBSERVATIONS IN INDIVIDUAL REC NO.  1 (IN
INDIVIDUAL REC ORDERING) EXCEEDS 50
SEE INSTALLATION GUIDE

There are too many observation records in some individual record. To increase the limit beyond 50, NONMEM must be recompiled. See Guide III, Section 2.7.

INITIAL ESTIMATE OF `OMEGA` HAS A NONZERO BLOCK WHICH IS
NUMERICALLY NOT POSITIVE DEFINITE

Possible cause: initial estimates of the variance and covariance terms in a block of OMEGA are not appropriate. Try other initial estimates. (Hint: it helps if the covariance estimates are small relative to the variance estimates.)

USER CCONTR ROUTINE NOT USED, BUT THERE ARE NO EPSILONS, AND
ETAS ARE TO BE ESTIMATED

This can happen when POSTHOC etas are requested, but the data are single-subject data. The user may have included the POSTHOC option in error.

UNABLE TO OBTAIN A SATISFACTORY INITIAL ESTIMATE OF VARIANCE-COVARIANCE COMPONENTS
BLOCKS IN BLOCK SET 2 OF `OMEGA` ARE NUMERICALLY NOT POSITIVE DEFINITE

This message is from the Initial Estimates Step. It identifies certain parameters whose initial estimates could not be obtained.

Part II. Error in NONMEM tasks

NUMBER OF CALLS TO SIMETA EXCEEDS NO. OF DATA RECORDS FOR
INDIVIDUAL 1 (IN INDIVIDUAL RECORD ORDERING)

During the Simulation Step, an excessive number of calls to SIMETA have occurred. It may be that the user’s PRED is attempting to obtain ETA from a truncated distribution but, due to some error, is rejecting all or virtually all values. (Possibly, the NEW option was omitted from the random source.)

Some messages are preceded by lines such as the following that identify the NONMEM routine that has detected the error:

PROGRAM TERMINATED BY OBJ
PROGRAM TERMINATED BY OBJ, ERROR IN CELS
PROGRAM TERMINATED BY OBJ, ERROR IN ELS
PROGRAM TERMINATED BY PRRES, ERROR IN ELS
PROGRAM TERMINATED BY FNLETA
  • OBJ computes the objective function;
  • ELS computes Extended Least-Squares contribution to the objective function from the data from a single individual (“L1”) record.
  • CELS computes the conditional contribution to the ELS objective function;
  • PRRES prints final results.
  • FNLETA computes subject-specific (posthoc) eta values.
WITH INDIVIDUAL 1 (IN INDIVIDUAL RECORD ORDERING)

A line such as this identifies the record.

Here are some commonly seen error messages.

INTRAINDIVIDUAL VARIANCE OF DATA FROM OBS RECORD 1 ESTIMATED TO BE 0
VAR-COV OF DATA FROM INDIVIDUAL RECORD ESTIMATED TO BE SINGULAR

A possible cause is the use of a proportional intra-individual error model while some predicted values for actual observations are zero or close to zero. (For example, if the first dose is an infusion and there is a “base-line” observation at the start of the infusion, the predicted level will be zero.)

MINIMIZATION TERMINATED DUE TO PROXIMITY OF NEXT ITERATION
EST. TO A VALUE AT WHICH THE OBJ. FUNC. IS INFINITE

NONMEM Theta-recovery has failed.

OCCURS DURING SEARCH FOR ETA AT A NONZERO VALUE OF ETA

An error occurred while NONMEM was obtaining conditional estimates of eta.

Section III. Errors in PREDPP

Errors in LSODA

As of NONMEM 7, A differential equation solver has been introduced, called LSODA, and is accessed using ADVAN=13 or ADVAN13. The code to the differential equation solver is found in source\LSODA.f90. On occasion, coded errors will be displayed if the algorithm is having trouble integrating the equations. These errors may usually be ignored, unless the error shows up frequently, and ultimately results in failure for the problem to complete. Typically the remedy is to increase or decrease TOL, but for those who desire to understand what the error codes mean, there are well documented comments on these at the beginning of LSODA.f90. They are printed here for convenience:

ISTATE=An index used for input and output to specify the state of the calculation.

On input, the values of istate are as follows.
1 Means this is the first call for the problem (initializations will be done).
  See note below.
2 Means this is not the first call, and the calculation is to continue
  normally, with no change in any input parameters except possibly TOUT
  and ITASK. (If ITOL,`RTOL`,and/or `ATOL` are changed between calls with
  ISTATE=2, the new values will be used but not tested for legality.)
3 Means this is not the first call, and the calculation is to continue
  normally, but with a change in input parameters other than TOUT and ITASK.
  changes are allowed in NEQ,ITOL,`RTOL`,`ATOL`,IOPT,LRW,LIW,JT,ML,MU and any
  optional inputs except H0,MXORDN,AND MXORDS.
  (See IWORK description for ML and MU.)
Note: A preliminary call with TOUT=T is not counted as a first call here, as
no initialization or checking of input is done. (Such a call is sometimes
useful for the purpose of outputting the initial conditions.) Thus the first
call for which TOUT /= T requires ISTATE=1 on input.

On output, istate has the following values and meanings.
 1 Means nothing was done; TOUT=T and ISTATE=1 on input.
 2 Means the integration was performed successfully.
-1 Means an excessive amount of work (more than MXSTEP steps) was done on
   this call, before completing the requested task, but the integration was
   otherwise successful as far as T. (MXSTEP is an optional input and is
   normally 500.) To continue, the user may simply reset ISTATE to a value > 1
   and call again (the excess work step counter will be reset to 0).
   In addition, the user may increase MXSTEP to avoid this error return
   (See below on optional inputs).
-2 Means too much accuracy was requested for the precision of the machine
   being used. This was detected before completing the requested task, but
   the integration was successful as far as T. To continue, the tolerance
   parameters must be reset, and ISTATE must be set to 3. The optional output
   TOLSF may be used for this purpose. (Note: If this condition is detected
   before taking any steps, then an illegal input return (ISTATE=-3) occurs
   instead.)
-3 Means illegal input was detected, before taking any integration steps.
   See written message for details.
   Note: If the solver detects an infinite loop of calls to the solver with
   illegal input, it will cause the run to stop.
-4 Means there were repeated error test failures on one attempted step, before
   completing the requested task, but the integration was successful as far as T.
   The problem may have a singularity, or the input may be inappropriate.
-5 Means there were repeated convergence test failures on one attempted step,
   before completing the requested task, but the integration was successful as
   far as T. This may be caused by an inaccurate jacobian matrix, if one is
   being used.
-6 Means EWT(I) became zero for some I during the integration. Pure relative
   error control (`ATOL`(I)=0.0) was requested on a variable which has now
   vanished. The integration was successful as far as T.
-7 Means the length of RWORK and/or IWORK was too small to proceed, but the
   integration was successful as far as T. This happens when DLSODA chooses
   to switch methods but LRW and/or LIw is too small for the new method.

Note: Since the normal output value of ISTATE is 2, it does not need to be
reset for normal continuation. Also, since a negative input value of ISTATE
will be regarded as illegal, a negative output value requires the user to
change it, and possibly other inputs, before calling the solver again.

REFERENCES: Guide I, section G; Guide V, section 13

13 NONMEM STEPS

MEANING: Sequence of events in a NONMEM problem

CONTEXT: NONMEM output

DISCUSSION:

NONMEM loads information from a model specification file, if $MSFI is present. NONMEM makes a single call to PRED (with ICALL=0), at the beginning of the run, to allow PRED to undertake run initialization (INITL).

NONMEM makes a single call to PRED (with ICALL=1), at the beginning of every problem, to allow PRED to undertake problem initialization (INITL).

SIMULATION STEP
NONMEM inputs initial fixed effects parameters from file specified by $CHAIN, if record is present. NONMEM performs simulation (with ICALL=4) (if $SIMULATION present).
INITIAL ESTIMATE STEP (with ICALL=2)
NONMEM obtains initial estimates for theta, omega, sigma (if the control stream does not provide all initial estimates).
ESTIMATION STEP (with ICALL=2)
NONMEM inputs initial etas from file specified by $ETAS/$PHIS, if record is present. NONMEM searches for parameter values that minimize the objective function (if $ESTIMATION present). With NONMEM 7, multiple Estimation Steps can be implemented in a single problem. A sequence of two or more Estimation Steps will result in the sequential execution of each.
COVARIANCE STEP (with ICALL=2)
NONMEM obtains a variance-covariance matrix of the estimator and related information such as standard errors (if $COVARIANCE present).
FINALIZATION STEP (with ICALL=2,5,6)
NONMEM obtains the following as needed:
  • Classification into subpopulations (if a MIXTURE model is used)(FNLMOD).
  • Posthoc estimates of eta (FNLETA).
  • Nonparametric step (NONPAR, with ICALL=2): NONMEM obtains either marginal cumulatives or conditional (nonparametric) estimates of etas (if $NONPARAMETRIC present).
  • PRED-defined values from NMPRD4 (NP4F) (for tables and scatterplots).

NONMEM computes WRES and other diagnostics if they are to be displayed in tables or scatters. (PRRES)

NONMEM makes a single call to PRED (with ICALL=3), at the end of every problem (and subproblem), to allow PRED to undertake problem finalization.

TABLE STEP
NONMEM constructs tables (if $TABLE present).
SCATTERPLOT STEP
NONMEM constructs scatterplots (if $SCATTERPLOT present).

REFERENCES: Guide I, section A.4, G

14 OBJ

MEANING: OBJ subroutine

CONTEXT: NONMEM routine

DISCUSSION:

OBJ is a NONMEM routine. It computes the objective function. Error messages from OBJ may indicate some difficulty in this computation.

REFERENCES: None.

15 OBSERVATION RECORDS

MEANING: Those data records containing observation information

CONTEXT: NONMEM input/output

DISCUSSION:

A data record may contain an observation, in which case the missing dependent variable (MDV) data item (which may be specified by the user, or created for him by NM-TRAN when PREDPP is used) should be zero, and the dependent variable (DV) data item should be the observation. If a data record does not contain an observation, the MDV data item should be 1 or 101, and the DV data item may be any value. NONMEM counts observation records. It also must know in what position (column) of a data record the DV data item appears. It reports its information about these things as a check to the user, as in this example:

DEP VARIABLE IS DATA ITEM NO.: 4
.
.
TOT. NO. OF OBS RECS:  394

(See dv, mdv).

REFERENCES: Guide III, section V.3.2; Guide IV, section II.C.4.1; Guide V, section 6; Guide VI, section II

16 PRED, RES, WRES

MEANING: NONMEM read-only global variables

CONTEXT: User-supplied PRED and INFN routines

USAGE:

USE ROCM_REAL, ONLY:                                                                    &
PRED_=>APPND(001),RES_=>APPND(002),WRES_=>APPND(003)                                      &
IWRS_=>APPND(004),IPRD_=>APPND(005),IRS_=>APPND(006)                                      &
NPRED_=>APPND(007),NRES_=>APPND(008),NWRES_=>APPND(009)                                   &
NIWRES_=>APPND(010),NIPRED_=>APPND(011),NIRES_=>APPND(012) &
CPRED_=>APPND(013),CRES_=>APPND(014),CWRES_=>APPND(015)                                   &
CIWRES_=>APPND(016),CIPRED_=>APPND(017),CIRES_=>APPND(018) &
PREDI_=>APPND(019),RESI_=>APPND(020),WRESI_=>APPND(021)                                   &
IWRESI_=>APPND(022),IPREDI_=>APPND(023),IRESI_=>APPND(024) &
CPREDI_=>APPND(025),CRESI_=>APPND(026),CWRESI_=>APPND(027) &
CIWRESI_=>APPND(028),CIPREDI_=>APPND(029),CIRESI_=>APPND(030) &
EPRED_=>APPND(031),ERES_=>APPND(032),EWRES_=>APPND(033)                                   &
EIWRES_=>APPND(034),EIPRED_=>APPND(035),EIRES_=>APPND(036) &
NPDE_=>APPND(037),ECWRES_=>APPND(038),NPD_=>APPND(039)                                    &
OBJI_=>APPND(040)

GLOBAL DECLARATION:

USE SIZES, ONLY: DPSIZE
REAL(KIND=DPSIZE) :: APPND(MAXXNAME)

DISCUSSION:

The PRED_, RES_, WRES_ items are the same as PRED, RES and WRES items.

The CPRED_, CRES_, CWRES_ are calculated as if the estimation was performed using a CONDITIONAL method without INTERACTION. (conditional, non-interactive in the manner of Hooker et al.)

The PREDI_, RESI_, WRESI_ are calculated as if the estimation was performed using the FO method with INTERACTION (non-conditional, interactive).

The CPREDI_, CRESI_, CWRESI_ are calculated as if the estimation was performed using a CONDITIONAL method with INTERACTION (conditional, interactive).

EPRED_, ERES_, EWRES_ are Monte-Carlo generated pred, res, and wres values, and are not linearized approximations like the other weighted residual types.

NPDE_ is the normalized prediction distribution error (takes into account within-subject correlations).

NPD_ is the correlated normalized prediction distribution error (does not take into account within-subject correlations).

EWRES_ and NPDE_ and NPD_ are evaluated using predicted function and residual variances evaluated over a Monte Carlo sampled range of etas with population variance Omega.

ECWRES_ is evaluated with only the predicted function evaluated over a Monte Carlo sampled range of etas with population variance Omega, while residual variance is always evaluated at conditional mode or mean. Thus, ECWRES is the Monte Carlo version of CWRES, while EWRES is the Monte Carlo version of CWRESI.

The EPRED_, ERES_, EWRES_, NPD_, NPDE_, ECWRES_ items are calculated by the Table Step. When EPRED_, ERES_, EWRES_, NPD_, NPDE_, ECWRES_ items are displayed, the options ESAMPLE and SEED of the $TABLE record are of interest. (See Section 50.46).

The PRED_, RES_, WRES_ (PRED, RES, WRES) items behave as they did with NONMEM VI. Consequently, if FO or a CONDITIONAL method without INTERACTION is used, NPRED_, NRES_, NWRES_ and PRED_, RES_, WRES_ are equivalent. If FO or a CONDITIONAL method with INTERACTION is used, IPRED_, IRES_, IWRES and PRED_, RES_, WRES_ are equivalent.

These items are available with passes through the data set during problem finalization (i.e. ICALL=3), in a data record specific way.

These items may be used as right-hand quantities in $PRED and $INFN during problem finalization. They can also be output in table files by specifying their names (without the underscore) on a $TABLE statement.

(See pred res, Section 55.16).

Location prior to NONMEM 7: rocm49.

For other variables, see the INTRODUCTION TO NONMEM 7.

REFERENCES: Guide I, section C.3.5.3, C.3.5.4; Guide IV, section III.B.16, III.B.17; Guide V, section 9.5, 10.7, 11.4.4.2; Guide Introduction_7

17 PRRES

MEANING: PRRES subroutine

CONTEXT: NONMEM routine

DISCUSSION:

PRRES is a NONMEM routine. It is called with final parameter estimates. An error message may indicate that NONMEM has experienced difficulties in PRRES with the final parameter estimates. (When the Estimation Step is not implemented, these are the same as the initial parameter estimates.)

PRRES may not be called by user-written code.

REFERENCES: None.

18 SHRINKAGE

MEANING: NONMEM’s estimate of inter-subject variance shrinkage

CONTEXT: NONMEM output

DISCUSSION:

Shrinkage data are included in the results between #TERM and #TERE.

With NONMEM 7.3, these are

  • ETAshrink
  • EBVshrink
  • EPSshrink

For details, see the NONMEM 7 guide.

With NONMEM 7.4, these are

  • ETAshrinkSD (called ETAshrink in NM73)
  • ETAshrinkVR
  • EBVshrinkSD (called EBVshrink in NM73)
  • EBVshrinkVR
  • EPSshrinkSD (called EPSshrink in NM73)
  • EPSshrinkVR

For details, see the NONMEM 7.4 guide

With NM73 and later, option ETASTYPE=1 in the $EST record, will average shrinkage information only among individuals that provided a non-zero derivative of their data likelihood with respect to that eta, and will not include subjects with a non-influential eta, that is in which the derivative of the data likelihood is zero.

Furthermore, you may specify eta i of particular subjects to be excluded or included using reserved variable ETASXI(i). (ETASXI stands for eta shrinkage exclude/include). (See Section 53.38).

Shrinkage data are also given in file root.shk File root.shm is a shrinkage map describing which etas were included or excluded in the eta shrinkage assessment.

REFERENCES: Guide Introduction_7

19 STANDARD ERROR OF ESTIMATE

MEANING: NONMEM’s estimate of the precision of its parameter estimates

CONTEXT: NONMEM output

DISCUSSION:

Asymptotic statistical theory applied to extended least-squares estimation (as used in NONMEM) says that the distribution of the parameter estimators is multivariate normal, with variance-covariance matrix that can be estimated from the data. NONMEM supplies such an estimate (See Section 55.2). The square root of the ith diagonal element of the matrix is the standard error of the ith parameter estimate. NONMEM output presents standard errors as in this example.

 ****** STANDARD ERROR OF ESTIMATE ********************

`THETA` - VECTOR OF FIXED EFFECTS PARAMETERS **********

          TH 1  TH 2

      6.27E+00 1.92E+01

`OMEGA` - COV MATRIX FOR RANDOM EFFECTS - ETAS ********

          ETA1  ETA2

ETA1  1.71E-02
ETA2
      ......... 1.12E-01

`SIGMA` - COV MATRIX FOR RANDOM EFFECTS - EPSILONS ****

                     EPS1
   EPS1 5.57E-03

Note that standard errors are given for all types of population parameters: THETA, the vector of fixed effects parameters, and OMEGA and SIGMA, the matrices of random effects parameters. In this example, the 2x2 matrix, OMEGA, was constrained to be diagonal; the omitted entry (………) indicates that the element omega(2,1) is not estimated, and consequently has no standard error.

REFERENCES: Guide I, section C.3.5.2 REFERENCES: Guide V, section 5.4.2.1

20 SUMMARY

MEANING: A utility to provide summary statistics of a series of table outputs (NM751)

CONTEXT: NONMEM table file

After creating a series of table outputs generated by a $SIML statement, it may be desired to obtain summary statistics of the the table items. The summary utility program can probide these summary statistics. For example, suppose you generate the table outputs from a control stream as follows:

$SIM (4442223) SUBPROB = 1000
...
$TABLE ID TIME ... IPRED ... NOPRINT NOAPPEND FILE = table.tab

You may want to obtain quantile values of these 1000 generated samples of each table item. The syntax of executing this program is as follows:

USAGE: summary table.tab summary.tab "1X,1PG15.8"
Inputfile
Table file generated from a NONMEM control stream.
Outputfile
Output summary statistics file produced by the utility program.
FORTRAN style format
optional.

In the above example, the resulting summary.tab file will contain quantile position values for each of the table items, for example

TIME:     STD          RSTD     2.50%     97.50%
Row Mean    0.0000       0.0000
            5.09463E-02           0.0000    0.0000
 1 0.0000   1.7673        36.563
 2 0.13934  1.7673       24.814   6.32440E-02 0.26127
 3 7.1222   1.7673       24.814
 4 7.1222   37.671       24.814   4.0921    11.134
 5 7.1222                24.177
 6 155.81                         4.0921    11.134

                                  4.0921    11.134

                                  82.548    199.97

IPRED:     STD         RSTD        2.50%  97.50%
Row Mean     0.0000      0.0000    0.0000   0.0000
            0.13800      12.732   0.84534   1.3868
 1 0.0000    2.1256      26.708    4.5215   12.773
 2 1.0839    2.1256      26.708    4.5215   12.773
 3 7.9587    2.1256      26.708    4.5215   12.773
 4 7.9587   0.20825      39.702   0.37273   1.1902
 5 7.9587
 6 0.52453

See INTRODUCTION TO NONMEM 7, A utility to provide summary statistics of a series of table outputs (NM751)

REFERENCES: Guide Introduction_7

21 USERS GUIDE

MEANING: NONMEM Users Guide

CONTEXT: Documentation

The following documents are collectively called the NONMEM Users Guide.

  • Part I - Users Basic Guide
  • Part II - Users Supplemental Guide
  • Part III - NONMEM Installation Guide
  • Part IV - NM-TRAN Guide
  • Part V - NONMEM-PREDPP Introductory Guide
  • Part VI - PREDPP Guide
  • Part VII - Conditional Estimation Methods
  • Part VIII - Help Guide
  • NONMEM V Supplemental Guide
  • Introduction to Version VI
  • Introduction to NONMEM 7

They are distributed as PDF files on the NONMEM distribution media. They are also present in HTML format as part of the HTML version of On-line help (Hyper-NMhelp).

REFERENCES: Guide I, Guide II, Guide III, Guide IV, Guide V, Guide VI, Guide VII, Guide VIII, Guide Supplemental_V, Guide Introduction_VI, Guide Introduction_7

22 VARIANCE-COVARIANCE

MEANING: Variance-covariance matrix

CONTEXT: NONMEM output

DISCUSSION:

NONMEM output refers to “VARIANCE-COVARIANCE” (or “COVARIANCE”) matrices in three contexts:

OPTIONS:

OMEGA and SIGMA
OMEGA is the variance-covariance matrix for the first level random effects ETA. SIGMA is the variance-covariance matrix for the second-level random effects EPSILON.

Error messages referring to “VARIANCE-COVARIANCE COMPONENTS” arise from difficulties with the initial estimates of OMEGA and/or SIGMA, either those supplied by the user, or when no estimates are supplied, with those obtained in NONMEM’s Initial Estimates Step. Initial estimates of both OMEGA and SIGMA must be positive definite.

With NONMEM 7.3 and higher, if the initial estimate of a block is not positive definite because of rounding errors, a value will be added to the diagonal elements to make it positive definite. A message in the NONMEM report file will indicate that this was done. E.g.,

DIAGONAL SHIFT OF 1.1000E-03 WAS IMPOSED TO ENSURE POSITIVE DEFINITENESS
VAR-COV
Error messages referring to “VAR-COV” (in particular, “ESTIMATED TO BE SINGULAR” or “ESTIMATED TO BE 0”) arise when the variance-covariance matrix for an individual’s data is non-positive definite. For example, with the error model 
Y = F + F * EPS(1)

predicted values for some observations (i.e. values of F) may be zero or close to 0. Then variances for these observations (which are proportional to \(F^2\)) are also zero, and this gives rise to such an error message.

COVARIANCE MATRIX OF ESTIMATE
This variance-covariance matrix refers to an estimate of the variability and covariability of the parameter estimates. It is computed in the Covariance Step, from the R and S matrices. An error message from the Covariance Step, stating that one of these two matrices is non-positive definite, indicates that the minimization procedure did not find a true or unique minimum (See Section 50.8).

REFERENCES: Guide I, section C.3.5.2

REFERENCES: Guide IV, section III.B.10, III.B.11

REFERENCES: Guide V, section 5.4, 13.4.3