Why NONMEM Results Require More Than One File
A NONMEM run can produce several output files, and each answers a different question. The listing file is usually the main human-readable record: it shows estimation messages and commonly includes final estimates, standard errors, and covariance information. Other files may record estimates across iterations or hold individual-level results. Reading them together helps prevent a common error: treating a model’s estimated variability, the uncertainty in its parameter estimates, and a subject’s individual estimate as if they were the same quantity.
File names and the exact contents depend on the NONMEM version, run configuration, and control stream. A file that is customary in one workflow may be absent in another. In particular, do not assume that an individual-estimate file exists unless the run requested or produced those results. The goal is to locate and interpret the output that a run actually contains, not to change its estimation settings.
Where to Look in a NONMEM Run
Start with the run’s .lst listing file. Search for the minimization termination message and the final parameter-estimate section. The listing commonly presents estimates by parameter label: THETA elements for fixed-effect parameters, OMEGA elements for interindividual random-effect covariance parameters, and SIGMA elements for residual-error parameters. The labels alone do not tell you the scientific meaning; use the control stream to map each element to the model definition and its units.
If a covariance step was requested, the listing may also report whether it succeeded, standard errors, and a covariance matrix for the estimated parameters. Read the status messages as well as the numbers. A minimization marked successful does not by itself establish that standard errors are available or reliable: the covariance step has its own outcome. Conversely, a failed covariance step does not erase the point estimates, but it means that the reported uncertainty calculations may be missing or unsuitable for interpretation.
The .ext file commonly records parameter estimates and objective-function values across estimation iterations, with the final record corresponding to the last reported iteration. It is useful for checking the trajectory and locating the final values in a structured file. It is not a replacement for checking the listing’s termination messages and final report. Depending on the run and software version, covariance and correlation outputs may also be written to separate files, commonly with .cov and .cor extensions. Confirm their contents rather than inferring meaning from the extension alone.
Individual-level results are often available through an output table or a file such as .phi, when requested or produced by the run. Check the table specification and column headings: an ETA column is not the same thing as a subject-specific clearance column. If the output contains ETAs, the model’s parameterization is needed to translate them into individual parameter values.
| Output location | Common use | Important check |
|---|---|---|
| .lst listing | Termination messages, final estimates, and often standard errors and covariance results | Confirm minimization and covariance-step status; map labels to the control stream |
| .ext file | Estimates and objective-function values across iterations | Identify the final record and compare it with the listing |
| .cov or .cor, when present | Covariance or correlation information written separately | Check headings, parameter order, and whether the matrix is for estimates |
| .phi or an individual-level table, when present | Subject-specific ETA or other individual-level estimates | Check the requested columns, subject identifiers, and parameterization |
Reading Estimates, Standard Errors, and Covariance
The parameter estimate is the fitted value under the model and estimation procedure used in the run. A standard error is a measure of uncertainty in that estimate, not a measure of between-subject variability. When the covariance step provides a covariance matrix \(C\) for the estimated parameters, the standard error for parameter \(j\) is the square root of its diagonal element:
An off-diagonal element \(C_{jk}\) describes the estimated covariance between two parameter estimates. It is not an additional estimate of biological variability. When both diagonal elements are positive, the corresponding estimated correlation is \(C_{jk}/\sqrt{C_{jj}C_{kk}}\). The matrix can reveal strong dependence between estimates, but it does not by itself show that the model is scientifically appropriate.
A brief justification clarifies why the covariance matrix is tied to uncertainty. Near a well-behaved optimum, the objective function can be approximated locally by a quadratic: its curvature describes how rapidly the objective worsens as parameters move away from the optimum. Under the usual local, large-sample approximation, inverting the curvature information gives an approximate covariance matrix for the estimates. Thus, a covariance step that cannot obtain a suitable matrix can prevent standard errors from being calculated. This approximation depends on local model behavior and does not guarantee that the model, data, or estimates are otherwise adequate.
Keep this matrix separate from OMEGA and SIGMA. OMEGA represents the modeled covariance of interindividual random effects, while SIGMA represents the modeled residual-error covariance. The covariance matrix of estimates instead describes uncertainty and dependence among fitted parameters. For example, an OMEGA diagonal element is a random-effect variance parameter; its square root is the random-effect standard deviation on the scale defined by the model. It is not the standard error of that OMEGA estimate.
Worked Example: Finding Population Estimates in the Listing
Consider a hypothetical one-compartment oral model with typical apparent clearance \(CL/F\), apparent volume \(V/F\), and absorption rate constant \(k_a\). Suppose the listing reports final estimates of 5.20 L/h, 42.0 L, and 1.10 h\(^{-1}\), respectively, and gives standard errors of 0.62 L/h, 5.4 L, and 0.22 h\(^{-1}\). Assume the listing identifies minimization as successful and the covariance step as successful.
The parameter labels and model definition identify which estimate is which: \(CL/F=5.20\) L/h, \(V/F=42.0\) L, and \(k_a=1.10\) h\(^{-1}\). The standard errors are read alongside their matching parameters, not inferred from OMEGA or SIGMA. For example, the estimated standard error of \(CL/F\) is 0.62 L/h.
A rough relative scale for that uncertainty is \(0.62/5.20=0.119\), or about 11.9% of the estimate. This ratio is a descriptive comparison, not a confidence interval and not a probability statement. The successful messages support reading the reported estimates and covariance-based standard errors, but they do not prove that the parameter estimates are unbiased or that the model is adequate.
Worked Example: Interpreting a Covariance Matrix
Suppose a hypothetical listing gives this portion of the covariance matrix for estimates of \(CL/F\) and \(V/F\), in that order:
The standard error of \(CL/F\) is \(\sqrt{0.3844}=0.6200\) L/h. The standard error of \(V/F\) is \(\sqrt{29.16}=5.400\) L. The off-diagonal value, 1.080, is the estimated covariance between their estimates. Its units are \((\mathrm{L/h})(\mathrm{L})\), not a clearance variance or volume estimate.
The estimated correlation is \(1.080/\sqrt{0.3844\times29.16}=1.080/(0.6200\times5.400)=0.3226\). This indicates a positive, moderate estimated association between the two parameter estimates under this local uncertainty approximation. It does not mean that clearance causes volume to increase, nor does it describe interindividual covariance in the model. The positive covariance also does not change either parameter’s reported point estimate.
Individual Estimates and Their Interpretation
An ETA estimate is a subject-level estimate of a random effect under the fitted model. In a log-normal parameterization, for example, an individual clearance may be defined as \(CL_i=TVCL\exp(\eta_{CL,i})\), where \(TVCL\) is typical clearance and \(\eta_{CL,i}\) is that subject’s estimated ETA. The transformation is model-specific: read the structural and random-effects definitions before turning an ETA into a parameter value.
Individual estimates are generally informed by both the population model and that individual’s observations. They are not direct, error-free measurements of a person’s true parameter. In sparse data, the information for an individual may be limited, so the population model can have substantial influence. Do not interpret an ETA column as an independently estimated population effect, or attach the population standard error to each person’s ETA as if it were the ETA’s individual uncertainty.
Worked Example: Translating ETA Estimates into Individual Clearance
Suppose a hypothetical output table gives ETA estimates for clearance of \(-0.12\) for subject 101 and \(0.08\) for subject 102. The control stream defines \(CL_i=TVCL\exp(\eta_{CL,i})\), and the fitted typical clearance is \(TVCL=5.20\) L/h.
For subject 101, \(CL_{101}=5.20\exp(-0.12)=5.20\times0.8869=4.612\) L/h. For subject 102, \(CL_{102}=5.20\exp(0.08)=5.20\times1.0833=5.633\) L/h. The signs and magnitudes are consistent with the parameterization: a negative ETA gives clearance below typical, while a positive ETA gives clearance above typical.
These are model-based individual estimates under the stated model, rounded here to 4.61 L/h and 5.63 L/h. They are not direct observations, and the calculation alone provides no interval expressing their uncertainty.
Checks, Comparisons, and Common Failure Modes
A practical reading sequence is to verify that you have the correct run, inspect the termination messages, locate the final estimates, and then check whether standard errors and covariance information were successfully reported. Compare the final parameter values in the listing with the final record in the .ext file when both are available. Then map each parameter to the control stream and verify the units, transformations, and random-effects structure. For individual estimates, verify the identifier and confirm exactly what each column contains.
The listing and the structured output files serve complementary purposes. The listing is usually better for understanding status and the context of reported results; the .ext file can make it easier to compare values across iterations. Separate matrix files may be useful for programmatic inspection, while individual-level tables are needed for subject-specific results. None should be read without checking its labels and the run configuration. A numerical value in an output file is not self-interpreting.
- Confusing covariance matrices. The wrong reasoning is, “OMEGA is a covariance matrix, so its diagonal is the uncertainty in the estimates.” The correction is to distinguish OMEGA, a model for random effects, from the covariance matrix of parameter estimates.
- Treating successful minimization as a complete diagnostic. The wrong reasoning is, “The minimization succeeded, so all standard errors must be trustworthy.” Check the covariance-step status separately and consider whether the estimates and model are sensible.
- Assuming every output file has a fixed content. The wrong reasoning is, “A .phi file must contain individual clearances.” Check its headers and the table specification; it may report ETAs or other requested quantities.
- Ignoring parameterization and units. The wrong reasoning is, “ETA is clearance.” ETA is a random effect; its relationship to clearance depends on the model equation. Use the defined transformation and report the resulting units.
- Reading an iteration record as the final answer. Check that the record is the final one and compare it with the listing’s final estimate section. Intermediate values may differ because estimation was still progressing.
Standard errors and covariance estimates are conditional on the fitted model and the method used to obtain them; local approximations can be poor when the objective function is irregular or parameters are weakly identified. A missing or unsuccessful covariance result therefore matters, but a successful result is not a general certificate of model validity. This tutorial concerns reading the output as produced: changing estimation settings is not a substitute for first accurately identifying what the current run reported.
Check Your Understanding
Answer each question from the output information described, then compare with the solutions.
- A listing reports OMEGA(1,1) = 0.16 and a covariance-matrix diagonal element for the estimate of OMEGA(1,1) equal to 0.0025. What is the standard error of the OMEGA estimate, and what does 0.16 represent?
- A covariance step failed, but the minimization was marked successful. Which result can you still identify, and what uncertainty information needs caution?
- A subject has \(\eta=-0.10\) under \(CL_i=6.0\exp(\eta_i)\) L/h. Calculate the individual clearance.
- Why is the covariance between clearance and volume estimates not the same quantity as an OMEGA off-diagonal element?
- An .ext file contains several parameter records. What must you check before calling one record the final estimate?
Solutions. (1) The standard error is \(\sqrt{0.0025}=0.0500\) in the units of the OMEGA estimate. The value 0.16 is the modeled random-effect variance, not its estimate’s standard error. (2) The final point estimates may still be identified in the listing, but covariance-based standard errors and related uncertainty summaries need caution or may be unavailable. (3) \(6.0\exp(-0.10)=6.0\times0.9048=5.429\) L/h. (4) The first is dependence between parameter estimates; the OMEGA element describes covariance in the modeled interindividual random effects. (5) Check the iteration order, identify the last record, and compare it with the listing’s final estimate section and termination messages.