Individual \(\phi\) (PHI) parameters (recall \(\phi=\mu+\eta\)) and their variances PHC(,). For parameters not MU referenced PHI(i)=ETA(i), for i'th parameter. When a classical method is performed (FOCE, Laplace), then mode of posterior ETA(i) are printed out, along with their Fisher information (first order expected value for FOCE, second order for Laplace) assessed variances ETC(,). For ITS, these parameters are the modes of the posterior density, with first-order approximated expected variances (or second order variances if

1

$EST METHOD=ITS LAPLCE

is used). For IMP, IMPMAP, SAEM methods, they are the Monte Carlo evaluated conditional mean parameters and variances of the parameters under the posterior density. For MCMC Bayesian, they are random single samples of PHI(), as of the last position. Their variances are zero. Individual objective function values (obji) are also produced. As of NONMEM 7.4, if

1

$EST PHITYPE=1

is specified, then conditional mean ETAs are reported in the PHI table. regardless of the analysis method.

As of nm75, samples of PHI/ETA are collected at each BAYES iteration, and summarized to provide conditional mean PHI and PHC() in the .phi table, as described above. By default, the individual PHI values from each iteration are not stored. However, if you set

1

  $EST ... BAYES_PHI_STORE=1

then PHI and ETA values from each BAYES iteration will be stored in .iph. For non-mixture problems, only records of SUBP=0 are recorded, as there are no sub-population divisions. For mixture problems, the SUBP=0 records contain the composite phis and ETAs (the average of these across all non-negative iterations are in the .phi table), and the SUBP>0 records contain the phis and ETAs appropriate to each sub-population SUBP (the average of these across all non- negative iterations are in the .phm table). The .iph file can become quite large, so it should be used only on the final analysis.

These vaues have similar meaning as the results in .phi, but individual phi/eta/obji parameters per sub-population are recorded. This file is only produced in $MIXTURE problems.

The PHITYPE option also acts on this file.

As of nm75, for MCMC Bayesian analysis, the items listed in this table consist of the average values among all the iterations during the stationary distribution phase. Before nm75, the values consisted of values from the last MCMC iteration.

The conditional variances in the .phi and .phm files can represent the information content provided by a subject for a given eta or phi. For example, if data supplied by the subject is rich, then the variance tends to be smaller. If little data is supplied by the subject for that eta, then the conditional variance will approach its omega. In fact, a subject’s shrinkage can be evaluated as follows:

In accordance with the SD formula (index i for subject ID, j for ETA/PHI numbering): $$ \text{ETA shrinkage}=1-\sqrt{1-\text{PHC}_i(j, j)/\Omega(j, j)}, $$ or by the variance formula: $$ \text{ETA shrinkage}=\text{PHC}_i(j, j)/\Omega(j, j). $$

File .shk (NM72) presents composite eta shrinkage and epsilon shrinkage information, the same as given in the NONMEM report file between the #TERM: and #TERE: tags, but in rows/column format, and with adjustable formatting.

File .shm (NM73) is a shrinkage map describing which ETAS were included or excluded in the eta shrinkage assessment. (See shrinkage below).

An XML markup version of the contents of the NONMEM report file. The rules by which it is constructed can be found in output.xsd and output.dtd.

Full variance-covariance error matrix of THETAs, SIGMAs, and OMEGAs. Same as "COVARIANCE MATRIX OF ESTIMATE" in the NONMEM report except that it is full (NONMEM displays only the lower triangle), elements that are fixed or not estimated are displayed as 0 (NONMEM displays them as …..), and, when the data are individual, sigma is displayed as 0 (NONMEM does not display sigma at all.) Only generated if the $COVARIANCE record is present. The same applies to the .cor file (full correlation matrix of THETAs, SIGMAs, and OMEGAs; same as "CORRELATION MATRIX OF ESTIMATE").

(See correlation matrix of estimate, covariance matrix of estimate below.)

(See ORDER option).

File .clt (NM74) contains the lower-triangular portion of the variance-covariance of the parameter estimates reported in .cov. This is provided for easier pasting of the information as theta priors for a subsequent analysis. Only generated if the $COVARIANCE record is present.

File ".coi" contains full inverse covariance matrix (Fischer information matrix) for THETAs, SIGMAs, and OMEGAs. Same as "INVERSE COVARIANCE MATRIX OF ESTIMATE" except as described for ".cov".

File ".smt" (NM72) contains the S matrix, if $COV step failed.

File ".rmt" (NM72) Contains the R matrix, if $COV step failed.

Convergence information for the Monte Carlo/EM methods, if CTYPE>0. (See raw Output File above).

Produced if the user selects importance sampling with option IACCEPT=0.0. Contains the final IACCEPT and DF values that NONMEM selected for each subject.

For NONPARAMETRIC method. Each row of ".npd" contains information about a support point: the support point number, the ID from which the support point was obtained as an EBE of that subject (ID is -1 if this support point was randomly generated because NSUPP/NSUPPE was greater than number of subjects). The eta values of the support point are listed, followed by the cumulative probability (CUM) associated with each eta, followed by the joint density probability of that support point, if default or MARGINALS was selected. If ETAS was selected, then instead of cumulative probabilities, the support point eta vector that best fits that subject (ETM) is listed.

".npe" contains the expected value ETAs and expected value ETA covariances (ETC) for each problem or sub-problem. Because only one line is written per problem or sub-problem, the column header is displayed (unless NOLABEL=1) only once for the entire NONMEM run. However, each line contains information of table number, problem number, sub-problem number, super problem and iteration number.

".npi" (NM73) contains the individual probabilities. The header line (unless NOLABEL=1) is written only once, at the beginning of the file, per NONMEM run. Each line contains information of table number, problem number, sub-problem number, super problem, iteration number, subject number, and ID. This is followed by the individual probabilities at each support point (of which there are NSUPP/NSUPPE or NIND of them, whichever is greater). The line with Subject number=0 contains the sum of the probabilities of all the subjects, and is similar or exactly equal to the joint probability of each support point listed in .npd under the column PROBABILITY. That they are not equal is due to the convergence limit of the non-parametric analysis. Row of subject number I, column of support K, contains the individual probability IPROB(I,K). The sum of the individual probabilities over all support points for any given line (subject), is equal to 1/NIND. Thus, the sum of all items across rows and columns (not including subject 0) sums to 1. The format of the file is fixed at (,1PE22.15), and cannot be changed. It is intended for use in further analysis by analytical software, and is designed to report the full double-precision information of each probability.

".npl" contains the individual data likelihoods (not including the parameter density). The header line (unless NOLABEL=1) is written only once, at the beginning of the file, per NONMEM run. Each line contains information of table number, problem number, sub-problem number, super problem, iteration number, subject number, and ID. This is followed by the individual likelihoods at each support point (of which there are NSUPP/NSUPPE or NIND of them, whichever is greater). Unlike the .npi file, there is no line with Subject number=0. The row of subject number I, column of support K, contains the individual likelihood LIK(I,K). The format of the file is fixed at (,1PE22.15), and cannot be changed. It is intended for use in further analysis by analytical software, and is designed to report the full double-precision information of each probability.

The LIK(i, k) of the .npl file and the IPROB(i, k) are related to each other as follows: $$ \text{IPROB}(i, k)=\text{PI}(k)\text{LIK}(i, k)/\exp(-1/2\text{OBJ}(i))/N. $$ where \(N\) is number of subjects, PI(k) is the probability of a support point (found as item PROBABILITY in the .npd file), and OBJ((I) is the objective function contribution of subject i (found under OBJ column of the .npl or .npi file).

This file is produced if the user selects $EST NUMDER=1 or NUMDER=3. The file lists the numerically evaluated derivatives of Y with respect to eta, where

1
2
3
4
5

  F        = Y the prediction
  G(I,1)   = partial Y with respect to ETA(i)
  G(I,J+1) = Second derivatives of Y with respect to ETA(i),ETA(j)
  H(I,1)   = partial Y with respect to EPS(i)
  H(i,j+1) = partial Y with respect to EPS(i),ETA(j)

The values are those used in the Estimation Step. Values of F are computed by PRED with eta=0 if METHOD=0 is used; otherwise they are computed with non-zero ETAs: the Conditional (CPE) ETAs, empirical bayes estimates (EBE), mode a posteriori (MAP) estimates) or conditional mean ETAs, depending on the Estimation Method. Values of G are computed by NONMEM via finite differences using these values of F and eta. Values of H are computed by NONMEM with the same values of F and eta if INTERACTION is specified; otherwise, they are computed with eta=0.

This file is produced if the user selects $EST NUMDER=2 or NUMDER=3. The file lists the analytically evaluated derivatives of Y with respect to eta. The format and order is the same as file .fgh. The values are those returned by subroutine PRED in arguments F, G, and H. These are 0 if not computed by PRED. (E.g. second derivatves are not computed analytically with a method other than LAPLACIAN.) Values in .agh correspond exactly to those in .fgh. That is, values of F and G are from calls to PRED with ETA=0 or with non-zero ETAs, as described above. Values of H are from calls to PRED with the same values of eta if INTERACTION is specified; otherwise, they are from calls to PRED with ETA=0, regardless of the Estimation method.

".vpd" is produced if the $TABLE VARCALC=1 or VARCALC=2 option is used. It is the full variances-covariances among all user-defined and PREDPP parameters. The FORMAT used for this file is that defined in the $EST record.

".vpt" contains variance-covariance among user-defined parameters and PREDPP parameters, associated with conditional individual variances of the .phi file, as well as the variance-covariance of the fixed effects parameters (THETAS, SIGMAS, OMEGAS) of the .cov file. The COMACT column value is 1 to indicate the record contains the values during a COMACT=1 pass, that is with ETAs set to 0. Thus, an individual predicted value (IPRED) on this record would in fact by the population predicted value (PRED). The subsequent columns contain the values of user-defined table items, followed by variance-covariance of these items (labled VAR1_VAR2, wher VAR1 and VAR2 are the particular table items). The variance IPRED_IPRED for a record with COMACT=1 would then have essentially the statistical error associated with the variance-covariance of the appropriate THETAs. When COMACT=2, table variables are evaluated having the ETAs set to the empirical bayes estimates (depending on the last estimation method used, and what the FNLETA value is set to), variance-covariance of these items are evaluated based on conditional individual variances of the .phi table, and variance-covariance of the appropriate THETAs, SIGMAs, and OMEGAs, as applicable. If COMACT=3, then non-parametric estimated ETAs are used.

As of NM74, one can obtain random samples of individual ETAs, and uses these for covariate and model diagnostics. $EST ETASAMPLES=1 option causes individual ISAMPLE random ETA samples per subject, to be written to .ets. See also SAEM method.

With $DESIGN OFVTYPE=8 the progress of average individual conditional variances (average empirical Bayes conditional variance) are shown in the .bfm file , and the final one on the -1000000000 line, during an optimization. The RAW file (by default named .ext) which shows only the starting, and final values of the standard errors of population parameters, as extra information.

Let "root" be the input file stem. When MSF or MSFO option is used to specify an MSFO file in the $EST record:

1

$EST … MSFO=msfroot.msf

then in addition to the main MSF file msfroot.msf, file msfroot_ETAS.msf containing individual ETAs and phis generated during estimation (except FO, which does not generate non-zero ETAs during estimation), will also be produced, and provide additional information when a $MSFI record is used in a subsequent problem or control stream. In addition, this files stores information useful for resuming an interrupted EM/BAYES estimation. The _ETAS file does not contain POSTHOC evaluated ETAs, only estimated (during $EST) evaluated ETAs. Also, ensure that the ordering of subjects in the present problem matches that of the problem when the msf file was generated (for example, do not change the data file structure or IGNORE/ACCEPT filtering between the two problems).

When MSF or MSFO option is used to specify an MSFO file in the $EST record:

1

$EST … MSFO=msfroot.msf

then in addition to the main MSF file msfroot.msf and msfroot_ETAS.msf, files msfroot_RMAT.msf and msfroot_SMAT.msf containing intermediate information on the R matrix and S matrix will also be produced if a $COV record was implemented. These files provide information when a $MSFI record along with $COV … RESUME is used in a subsequent problem or control stream.

PRED-defined items, including PK-defined and ERROR-defined items can be displayed in tables and scatterplots. They are computed 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:

1
2
3

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

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

• 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:

  1 2 3

  THE FOLLOWING LABELS ARE EQUIVALENT Subsequent lines show the relationship of such items for the current Estimation method.

  (See $TABLE, $SCATTER).

  (See PRED,RES,WRES).

• 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 COMSAV) 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 COMSAV) 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).

• Example 1: output typical and conditional values using different variables.

  1 2 3 4 5 6

  $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.

• Example 2: output typical and conditional values of the same variables.

  1 2 3 4 5 6

  $PK ... CL=THETA(1)*EXP(ETA(1)) IF (COMACT.EQ.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.

• Example 3: output typical and conditional values of the prediction, and the individual residual and weighted residual values.

  1 2 3 4 5 6 7

  $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.

  1 2 3 4 5 6 7

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

• Example 4: output intra-individual weighted residual. Assume constant CV intraindividual error model, to output weighted intra-individual residual that is used during Estimation when the FOCE method without interaction is used.

  1 2 3 4 5 6 7 8

  $ERROR Y=F+F*EPS(1) IPRED=F IF (COMACT.EQ.1) FT=F IF (FT.NE.0) WR=(DV-IPRED)/FT/SQRT(SIGMA(1,1)) IF (IPRED.NE.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. 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 interac- tion. 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.

  With NONMEM 7, alternatively one can use reserved residual variables CIWRES(=WR) and CIWRESI(=WR2):

  1 2 3 4

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

• Example 5: output simulated values:

  1 2 3 4 5 6

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

  ETA(1) and CL are simulated values.

• Example 6: output simulated and estimated values:

  1 2 3 4 5 6 7 8 9 10 11

  $INPUT .... CLSM E1SM ... $PK ... CL=THETA(1)*EXP(ETA(1)) IF (ICALL.EQ.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.

• Example 7: output conditional values of a variable in each of two mixture subpopulations.

  1 2 3 4 5 6 7 8 9 10

  $PK ... IF (MIXNUM.EQ.1) CL= ... IF (MIXNUM.EQ.2) CL= ... IF (COMACT.EQ.2) THEN IF (MIXNUM.EQ.1) CL1=CL IF (MIXNUM.EQ.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.

• Example 8: output conditional values of a variable in the subpopulation into which the individual is classified.

  1 2 3 4 5 6 7

  $PK ... IF (MIXNUM.EQ.1) CL= ... IF (MIXNUM.EQ.2) CL= ... IF (COMACT.EQ.2.AND.MIXNUM.EQ.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.

Summary of data used in the analysis is listed, e.g.

1
2
3
4
5
6

 DATA SET LOCATED ON UNIT NO.:    2
 THIS UNIT TO BE REWOUND:        NO
 NO. OF DATA RECS IN DATA SET:  394
 NO. OF DATA ITEMS IN DATA SET:   8
 ID DATA ITEM IS DATA ITEM NO.:   1
 DEP VARIABLE IS DATA ITEM NO.:   4

In FORTRAN terms, the summary shows file I/O unit, the REWIND (necessary only with multiple runs using the data).

See also $INPUT control record.

NONMEM output includes a report of the history of the search undertaken in the Estimation Step for parameter estimates. This report is called the intermediate output from the Estimation Step, because it consists of summaries of the progress of the search, from iteration to iteration, and because it may be viewed as the search progresses, provided the NONMEM output file may be viewed as the search progresses. This report can also be viewed in a special (unbuffered) file.

The search is for parameter values that minimize the value of the OBJECTIVE FUNCTION. It entails the following steps.

1. The search is carried out in a different parameter space. The parameters are transformed to unconstrained parameters (UCP). In the transformation process a scaling occurs so that the initial estimate of each of the UCP is 0.1 ².

2. At the current parameter estimate the GRADIENT vector (the vector of first partial derivatives of the objective function with respect to the UCP) is computed. An approximate Hessian matrix) is also computed. An ITERATION SUMMARY, including the current parameter estimate and the gradient vector, may placed into the intermediate output.

   With NONMEM 7, the parameter estimates are also displayed in their natural (unscaled) space. These lines are identified as NPARAMETR and precede the PARAMETER lines, which display the UCP values. Note that when OMEGA (or SIGMA) have block structure, the values in NPARAMETR are listed in upper triangular order, whereas elsewhere in NONMEM output they are displayed in lower triangular order. For example, suppose the NONMEM output displays a 3x3 OMEGA matrix as

   1 2 3

   OMEGA(1,1) OMEGA(2,1) OMEGA(2,2) OMEGA(3,1) OMEGA(3,2) OMEGA(3,3)

   It will be listed in NPARAMTR in row-major order:

   1	OMEGA(1,1) OMEGA(2,1) OMEGA(3,1) OMEGA(2,2) OMEGA(3,2) OMEGA(3,3)

   Note that $ESTIMATION's ORDER option does not affect the order.

3. Using the gradient vector and Hessian matrix, a direction in parameter space, emananting from the current parameter estimate, is computed, and a search is undertaken along this direction for an approximate minimum point. When this point is found, NONMEM returns to step 2. (An ITERATION consists of the computation of the direction, the search along the direction, and the computation of the gradient vector and Hessian matrix at the approximate minimum point.)

4. Iteration stops when meeting one of the following conditions:

   • A successful (local) minimum point has been found.
   • The maximum number of FUNCTION EVALUATIONS specified in the $ESTIM MAXEVALS option is exceeded.
   • It was not possible to successfully locate a minimum point due to ROUNDING ERRORS.

   Here is an example of intermediate output from the Estimation Step:

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45

   MONITORING OF SEARCH: ITERATION NO.: 0 OBJECTIVE VALUE: 110.244034784025 NO. OF FUNC. EVALS.: 6 CUMULATIVE NO. OF FUNC. EVALS.: 6 NPARAMETR: 3.0000E+00 8.0000E-02 4.0000E-02 6.0000E+00 5.0000E-03 3.0000E-01 2.0000E-04 6.0000E-03 4.0000E-01 4.0008E-01 PARAMETER: 1.0000E-01 1.0000E-01 1.0000E-01 1.0000E-01 1.0000E-01 1.0000E-01 1.0000E-01 1.0000E-01 1.0000E-01 1.0000E-01 GRADIENT: 1.4640E+01 -1.6691E+01 5.6460E+01 -9.4129E+00 -1.1699E+01 1.0623E+01 -6.3485E-01 -4.7803E+01 -9.6457E+00 5.2414E+00 ITERATION NO.: 5 OBJECTIVE VALUE: 105.453694506861 NO. OF FUNC. EVALS.: 7 CUMULATIVE NO. OF FUNC. EVALS.: 45 NPARAMETR: 2.8166E+00 8.0433E-02 3.8563E-02 6.6123E+00 9.7862E-03 -3.9509E-02 2.3438E-04 8.1375E-03 4.9657E-01 4.0355E-01 PARAMETER: -5.3055E-02 1.0703E-01 5.7598E-02 1.4858E-01 1.8644E-01 -1.2545E-02 1.5794E-01 1.3452E-01 3.7714E-02 1.0431E-01 GRADIENT: 3.5103E-01 -1.3214E+01 2.8003E+01 1.1115E+00 1.9193E+00 -5.3252E+00 7.1533E-02 -2.2091E+01 -1.4424E+00 8.2329E+00 ITERATION NO.: 10 OBJECTIVE VALUE: 104.747695563098 NO. OF FUNC. EVALS.: 7 CUMULATIVE NO. OF FUNC. EVALS.: 80 NPARAMETR: 2.7362E+00 7.6935E-02 3.5982E-02 5.7362E+00 1.0840E-03 -2.9208E-01 2.3701E-04 9.4013E-03 5.1805E-01 3.8858E-01 PARAMETER: -1.1928E-01 4.9234E-02 -2.3022E-02 7.7517E-02 2.2174E-02 -9.9574E-02 1.9498E-01 1.4956E-01 -1.7173E-01 8.5414E-02 GRADIENT: -1.3933E+00 -7.4632E+00 9.3144E+00 1.0280E+00 9.6395E-01 -3.1313E+00 1.0212E+00 -5.3784E+00 -2.0828E+00 -9.1477E-01 ITERATION NO.: 15 OBJECTIVE VALUE: 104.561086502423 NO. OF FUNC. EVALS.: 7 CUMULATIVE NO. OF FUNC. EVALS.: 116 NPARAMETR: 2.7735E+00 7.8097E-02 3.6292E-02 5.5466E+00 5.1735E-03 -1.2911E-01 2.3941E-04 9.0947E-03 5.1461E-01 3.8760E-01 PARAMETER: -8.8567E-02 6.8686E-02 -1.2994E-02 6.0711E-02 1.0762E-01 -4.4762E-02 1.9028E-01 1.4643E-01 -8.4016E-02 8.4157E-02 GRADIENT: 7.7937E-03 5.7189E-03 3.0426E-02 -5.1648E-03 -1.2939E-02 1.4490E-02 7.4602E-04 -2.5227E-02 -3.1443E-03 1.5799E-02 ITERATION NO.: 19 OBJECTIVE VALUE: 104.561067398632 NO. OF FUNC. EVALS.: 0 CUMULATIVE NO. OF FUNC. EVALS.: 149 NPARAMETR: 2.7739E+00 7.8129E-02 3.6307E-02 5.5498E+00 5.2393E-03 -1.2767E-01 2.3985E-04 9.1064E-03 5.1521E-01 3.8742E-01 PARAMETER: -8.8304E-02 6.9219E-02 -1.2510E-02 6.0998E-02 1.0895E-01 -4.4249E-02 1.9095E-01 1.4652E-01 -8.3269E-02 8.4127E-02 GRADIENT: 1.2144E-04 -1.4883E-04 -6.6257E-06 -7.5745E-05 -1.6157E-05 1.1307E-04 6.4128E-05 1.1193E-04 -1.7655E-05 4.2676E-05

   Note that the values of the PARAMETERs are the values of the UCP, so that at the 0th iteration, all the PARAMETERs have the value 0.1.

   The first parameter (and gradient) elements correspond to the THETA elements which are not fixed. The remaining elements correspond to the OMEGA and SIGMA elements which are not fixed, but not in a simple 1-1 manner unless OMEGA and SIGMA are constrained to be diagonal.

   $ESTIMATION PRINT option determines how often iteration summaries are printed: not at all (with PRINT=0); only for the 0th and last iterations (with PRINT=9999); for the 0th iteration, for every 10th iteration thereafter, and for the last iteration (with PRINT=10, as illustrated above).

   If a model specification file is output, then the estimates may also be seen in the original parameterization for those iterations whose summaries appear in intermediate output. These estimates may be found in file INTER in the same order and format as elsewhere in the NONMEM output. With NONMEM 7, INTER exists after the run is finished.

   When the Estimation Step terminates, it reports its outcome:

   1 2 3

   MINIMIZATION SUCCESSFUL NO. OF FUNCTION EVALUATIONS USED: 149 NO. OF SIG. DIGITS IN FINAL EST.: 4.7

   Each UCP element of the mimimum point is determined to a number of significant digits. The number of significant digits reported is the number of significant digits in the least-well-determined element. The report "MINIMIZATION SUCCESSFUL" is issued when this number is no less than the number of significant digits requested using the $ESTIMATION SIGDIGITS option. Note that this report alone does not assure that a global (or even a local) minimum point has been located; what appears to be a minimum point may be a saddle point. Nor, if a minimum point has been located, does the report alone assure that the objective function is not "flat" in a region of the point. For such assurances, one also needs to implement the Covariance Step.

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 the final estimates from a previous run as initial estimates, by means of a Model Specification File. The outputs will be different in that case (See Model Specification File).

NONMEM output reflects initial estimates provided by the user on its problem summary page, such as

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

      INITIAL ESTIMATE OF THETA:
      LOWER BOUND    INITIAL EST    UPPER BOUND
      0.0000E+00     0.1500E+03     0.1000E+07
      0.0000E+00     0.0000E+00     0.0000E+00
      0.1000E+00     0.3000E+00     0.1000E+02
      -0.1000E+07    -0.1000E-01    0.1000E+07
      INITIAL ESTIMATE OF OMEGA:
      0.2500E+00
      0.0000E+00   0.2500E+00
      INITIAL ESTIMATE OF SIGMA:
      0.2500E+00

indicating:

• The initial estimate of THETA(1) is 150, and the parameter is constrained to be greater than zero (no upper bound).
• THETA(1) is fixed at zero.
• The initial estimate of THETA(3) is .3, and the parameter is constrained to lie between .1 and 10.
• The initial estimate of theta(4) is -.01, and the parameter is unconstrained.
• 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.
• SIGMA is 1x1 (a scalar), with initial estimate .25.

Not specifying the initial estimate of an element of THETA prompts NONMEM to provide the initial estimate, as in this example:

1
2
3

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

Similar for OMEGA and SIGMA elements.

In those cases, NONMEM search for initial estimates and output them along with user-specified ones under the heading "INITIAL PARAMETER ESTIMATE". This output is omitted if all initial parameter estimates are provided by the user.

1
2
3
4
5
6
7

	********************  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

(See Final Parameter Estimate).

See also control record $THETA, $OMEGA, and $SIMGA.

The second derivative matrix of the objective function with respect to the parameters of the model are utilized in NONMEM.

• Estimation Step: a crude numerical approximation to the Hessian is maintained during the minimization search. The following message in the intermediate output refers to this matrix:

  1	RESET HESSIAN

  Internally, 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 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). It suggests difficulties in searching, and possible modeling error.

• 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:

  1 2 3 4

  HESSIAN OF OBJ. FUNCT. FOR COMPUTING CONDITIONAL ESTIMATE IS NON POSITIVE DEFINITE NUMERICAL HESSIAN OF OBJ. FUNC. ...

See also $COVARIANCE control record.

parameter estimators follow multivariate normal distribution asymptotically, with variance-covariance matrix that can be estimated from the data. They are computed and reported by NONMEM in a Covariance Step. The matrix describes the variability under the assumed model of the parameter estimates. It is not SIGMA (the covariance matrix for the second level random effects) or OMEGA (the covariance matrix for the first level random effects).

An example of the NONMEM output giving the estimate of the variance-covariance matrix.

1
2
3
4
5
6
7
8

 **************** 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 is symmetric and is given in lower triangular form. Here the 2x2 OMEGA matrix is constrained to be diagonal, therefore entries related to OM12 are not available omitted. (a compressed form is used when the dimension exceeds 75x75. One can also requested this format manually. See $COVARIANCE).

The estimated variance-covariance matrix is computed as \(R^{-1}SR^{-1}\). Here \(R\) is the Hessian matrix of the objective function, , and \(S\) the summation of the cross-product gradient vectors of the individual-based objective functions. Both are 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 Covariance Matrix \(T=RS^{-1}R\), is also output. A pseudo-inverse of \(S\) is used when \(S\) is (near) singular. One can potentially use this Inverse Covariance Matrix to estimate a joint confidence region for the complete set of population parameters.

• An error message stating that the R matrix is not positive semidefinite suggests that the parameter estimation did not reach a local minimum and warrants further investigation. In this case, no covarance matrix (or its inverse) will be output.
• An error message stating that \(R\) is positive semidefinite but singular suggests that the objective function minimum reached is not unique, probably due to overparametrization. In this case, no covarance matrix (or its inverse) will be output.
• An error message stating that \(S\) is singular suggests overparameterization. This still allows estimating and ouptut of the covariance matrix when \(R\) is positive semidefnite and nonsingular.
• When \(R\) is singular but positive semidefinite, matrix \(T\) is output. In this case \(T\) is not the inverse covariance matrix, but still can be used to develop a joint confidence region for the complete set of population parameters.
• Alternatively, $COVAR MATRIX option allows the variance-covariance matrix to be calculated as \(2R^{-1}\) or \(4S^{-1}\). They are asymptotically equivalent to \(R^{-1}SR^{-1}\) under the assumption that the objective function is additively proportional to \(LL\), the log likelihood of the data.
• The Covariance Step will not be executed when the requested number of significant digits is greater than the reported number of significant digits in the final parameter estimate (See SIGDIGITS). When the model specification file is used as input the Covariance Step can be run without the Estimation step (MAXEVAL=0). In that case one should ensure the requested number of significant digits is less than the reported number of significant digits from the previous run.

See also the error message section below.

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 unidentifiability. The problem can be alleviated with additional data or using a simpler model with fewer parameters.

Output example:

1
2
3
4
5
6
7
8

 **************** 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 is symmetric and is given in lower triangular form. Here the 2x2 OMEGA matrix is constrained to be diagonal, therefore entries related to OM12 are not available omitted. (a compressed form is used when the dimension exceeds 75x75. One can also requested this format manually. See $COVARIANCE).

With NONMEM 7.2 and higher, the diagonal elements are the standard error (the square root of the diagonal elements of the covariance matrix. Earlier versions they were 1.0.

See also the error message section below.

ETABAR (\(\bar{\eta}\)) is output from a conditional population estimation method.

1
2
3
4
5
6
7
8

  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:             3.4060E-01  3.1223E-03  1.9001E-01
  N:                      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 wellspecified, 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 Pvalue 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.

NONMEM output always include FINAL PARAMETER ESTIMATE. When the Estimation Step was not run, then output are the initial parameter estimates specified for the problem.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

  ********************  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

The example above 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.

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.

1
2

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

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

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).

NM-TRAN may generate the following warning message:

1
2
3

 (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.

(See MTIME, model time examples).

Confidence intervals for parameters, testing hypotheses about parameters, and building models all need reasonable ranges for parameter values. These ranges can be found if we can estimate the distribution of the parameter estimates based on asymptotic theory, used in NONMEM's extended least-squares method. The parameter estimates follow a multivariate normal distribution, and their variance and covariance can be estimated from the data.

NONMEM provides this variance-covariance matrix for the estimates. The square roots of the diagonal elements of this matrix are the estimated standard errors for each parameter. The off-diagonal elements can be converted into correlation coefficients, which are shown in the correlation matrix of the parameter estimates. Additionally, the inverse of the covariance matrix and the eigenvalues of the correlation matrix are also available for use.

NONMEM output usually include special items: prediction, residual, and weighted residual, which are generated by NONMEM. The default labels for these items are PRED, RES, and WRES, respectively. Synonyms may be specified on the $TABLE record for one or more of these labels. With the NOAPPEND option on this record, the three items are not included in a table unless explicity listed on the $TABLE record. With the use of the user-routine SPTWO, the values of the RES and WRES items can be defined differently from the values described below.

These items may also be displayed in scatterplots.

• PRED Prediction items are the predictions computed by the PRED subroutine. For population data, prediction items are always population predictions, i.e., they are computed at the mean value of eta (0).
• RES The residual is defined as DV - PRED; that is, the observed value minus the prediction item.
• WRES The weighted residuals for an individual are formed by transforming the individual's residuals so that under the model, assuming the true values of the parameters are given by the estimates of those parameters, all weighted residuals have mean 0, unit variance and are uncorrelated. For population data, the "weights" are computed at eta = 0.

For discrete data ³, the prediction items are likelihoods (for population data, using the estimated values of the parameters, and computed at ETA = 0). These may not be of much interest. The RES and WRES items are 0.

With a mixture model, each individual is classified into one of the subpopulations of the mixture according to a computation based on the individual's data and on the final parameter estimates. For a data record from the individual record, the prediction, residual, and weighted residual items in the corresponding row of a table (or point on a scatterplot) are based on the submodel defining the subpopulation into which the individual is classified.

If the Marginal data item (MRG_) is 1 or 2 for a given data record, then PRED is an expected prediction, rather than the prediction at the mean value of eta. When the Raw-data data item (RAW_) is 1, then DV is a raw-data average and RES is the difference between the PRED item and this average.

(See PRED-defined items output).

Shrinkage are output between #TERM and #TERE entries. Inter-subject shrinkage for each \(\eta\) is calculated as: $$ \text{ETASHRINKSD}=1-\frac{\text{sd}(\eta(j))}{\Omega(j, j)},\quad \text{(NM73)} $$

$$ \text{ETASHRINKVR}=1-\frac{\text{var}(\eta(j))}{\Omega(j, j)}.\quad \text{(NM74)} $$ Here \(\eta(j)=\eta_j\) is individual's empirical Bayes estimate (FORCE/Laplace/ITS) or sampled conditional mean (IMP/SAEM).

In addition, the ETA shrikage based on the average empirical Bayes variance (EBV), the etc(j, j) (from .phi file) or phc(j, j) (from .phm) file, are available. $$ \text{EBVSHRINKSD}=1-\sqrt{1-\frac{\text{etc}_{\text{ave}}(j, j)}{\Omega(j, j)}},\quad \text{(NM73)} $$

$$ \text{EBVSHRINKSD}=1-\sqrt{1-\frac{\text{phc}_{\text{ave}}(j, j)}{\Omega(j, j)}},\quad \text{(NM73)} $$

$$ \text{EBVSHRINKVR}=\frac{\text{etc}_{\text{ave}}(j, j)}{\Omega(j, j)},\quad \text{(NM74)} $$

$$ \text{EBVSHRINKVR}=\frac{\text{phc}_{\text{ave}}(j, j)}{\Omega(j, j)},\quad \text{(NM74)} $$

In the above the average is taken among included subjects, for ETA(j) or PHI(j). Again, etc/phc is evaluated as first order approximation of the posterior variance around the mode (FOCE/ITS), second order approximation around the mode (LAPLACE), or Monte Carlo assessed posterior variance around the conditional mean (IMP/SAEM).

In summary,

• With NONMEM 7.3, shrinkage output are

  1 2 3

  ETAshrink EBVshrink EPSshrink

• With NONMEM 7.4, shrinkage output are

  1 2 3 4 5 6

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

• NONMEM v7.3+ provides $EST ETASTYPE=1 option to average shrinkage information only among individuals with non-zero derivative of their data likelihood with respect to ETA, and will not include subjects with a non-influential ETAs that have zero derivative.
• One may request include/exclude ETA output using ETASXI. Shrinkage map for included/exlucded ETAs is documented in .shm.
• Shrinkage data are reported in file .shk.

As of nm73, if the eta shrinkage is less than 0, it will reported as a value of 1.0E-10. Less than 0 shrinkage can occur due to limited precision evaluations, and/or sometimes with classical NONMEM methods.

ETA shrinkage is averaged for all individuals if ETASTYPE=0. As of nm73, should you wish to correct for some individuals not contributing at all to one or more ETAs (this may or may not be desirable, depending on your needs), the shrinkage can be calculated by NONMEM to not include these ETAs by setting $EST ETASTYPE=1. This 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 of particular subjects to be excluded, by setting a reserved variable ETASXI(i) to 1 in $PK or $PRED, or specify eta i of certain subjects to be included, by setting ETASXI(i)=2 (ETASXI stands for eta shrinkage exclude/include):

1
2

IF(ID==3)  ETASXI(1)=1
IF(ID==23) ETASXI(3)=2

The results in the NONMEM report file refer to average ETA shrinkage.

Residual error shrinkage standard deviation version for each residual error is evaluated for simple problems as (EPSSHRINKSD is EPSSHRINK in NM73) $$ \text{EPSSHRINKSD}=1-\text{sd}(\text{WRES}),\quad (\text{NM73}) $$ $$ \text{EPSSHRINKVR}=1-\text{var}(\text{WRES}),\quad (\text{NM74}) $$

For more complicated problems, the data and individual predicted values that contribute to assessing the shrinkage for each epsilon is not as straight-forward. For example, if EPS(1) is proportional error to PK data, and EPS(2) is proportional error to PD, and they are not connected by an off-diagonal sigma, then EPS1 shrinkage pertains to PK data residuals, and EPS2 shrinkage pertains to PD data residuals. If they are related by an off-diagonal SIGMA, then their shrinkage is related, and they will have similar or identical shrinkage values.

If two EPSILONs pertain to the same data, such as proportional EPS and additive EPS for PK data: $$ y=f+f\epsilon(1)+\epsilon(2), $$ then the same epsilon shrinkage is associated with EPS(1) and EPS(2). However, if F=0 for some data, then such values contribute to EPS(2) shrinkage assessment, but not to EPS(1) shrinkage assessment. In such cases, shrinkage to EPS(1) and EPS(2) may differ slightly, where EPS(1) shrinkage incorporates only residuals to data with predicted values that are non-zero, and EPS(2) shrinkage incorporates residuals to all PK data.

See also ETASAMPLES=0 option for SAEM method for diagnostics.

The reported shrinkage information from an MCMC Bayesian analysis is based on the average of the shrinkage across all individuals across all stationary iterations (positive numbered iterations in the .ext file).

1

 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.

1
2
3

 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.

1
2

 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 of the covariance estimates are small relative to the variance estimates.)

1
2

 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.

1
2

 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.

1
2

 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 users'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:

1
2
3
4
5

 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.

1

WITH INDIVIDUAL    1 (IN INDIVIDUAL RECORD ORDERING)

A line such as this identifies the record.

Here are some commonly seen error messages.

1
2

 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 "baseline" observation at the start of the infusion, the predicted level will be zero.)

1
2

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

NONMEM THETA-recovery has failed.

1

 OCCURS DURING SEARCH FOR ETA AT A NONZERO VALUE OF ETA

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

  ;# error in R matrix calculation
  R MATRIX UNOBTAINABLE
  ...
  ERROR RMATX-n m

  ;# error in S matrix calculation
  S MATRIX UNOBTAINABLE
  ...
  ERROR SMATX-n m

  ;# The OFV could be nearly-flat over in the parameter space
  R MATRIX ALGORITHMICALLY SINGULAR

  ;# the final estimate is not a local minimum
  R MATRIX ALGORITHMICALLY SINGULAR
  AND ALGORITHMICALLY NON-POSITIVE SEMIDEFINITE


  ;# the final estimate is not a local minimum
  R MATRIX ALGORITHMICALLY NON-POSITIVE SEMIDEFINITE
  BUT NONSINGULAR

  ;# The OFV could be nearly-flat over in the parameter space
  S MATRIX ALGORITHMICALLY SINGULAR

  ;# The OFV could be nearly-flat over in the parameter space
  PSEUDO INVERSE OF S MATRIX UNOBTAINABLE

  ;# error in inverse covariance calculationa
  PSEUDO INVERSE OF COVARIANCE MATRIX UNOBTAINABLE

  ;# error in inverse covariance calculation
  EIGENVALUES NO. n AND GREATER UNOBTAINABLE

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

COVARIANCE MATRIX UNOBTAINABLE

INVERSE COVARIANCE MATRIX UNOBTAINABLE

COVARIANCE MATRIX SET EQUAL TO INVERSE OF R MATRIX

COVARIANCE MATRIX SET EQUAL TO INVERSE OF S MATRIX

INVERSE OF COVARIANCE MATRIX SET EQUAL TO R MATRIX

INVERSE OF COVARIANCE MATRIX SET EQUAL TO S MATRIX

1
2
3
4
5
6
7
8

  ;# The error can occur only when the final estimate is the initial estimate and only when
  ;#  either the Covariance Step is unconditionally implemented or a MSF is used.
  ;# If MSF is used, check that it is the correct one.
    PROGRAM TERMINATED BY OBJ, ERROR IN ELS
    VAR-COV WITH INDIVIDUAL n (IN INDIVIDUAL RECORD ORDERING)
    ESTIMATED TO BE ALGORITHMICALLY SINGULAR

    MESSAGE ISSUED FROM COVARIANCE STEP

1
2
3
4
5
6
7
8
9

  ;# CONTR is the user-supplied subprogram for computing the contribution made to the
  ;# objective function from a iven individual’s data. It has encountered a fatal
  ;# error with individual n, and it has
  ;# issued a return code m.
    PROGRAM TERMINATED BY OBJ, ERROR IN CONTR
    WITH INDIVIDUAL n (IN INDIVIDUAL RECORD ORDERING)
    RETURN CODE m

    MESSAGE ISSUED FROM COVARIANCE STEP