Why Result Objects Need Careful Reading
An nlmixr2 fit is more than a printed table. It is an R object containing estimates and other information about the fit, accessible through summary methods, accessor functions, and object components. Reading it well means knowing which quantity is being retrieved, the scale on which it is expressed, and how the model’s parameter definitions give its label meaning. This matters when preparing a report, checking a fit, or passing estimates into another workflow.
The most reliable starting point is the object’s documented presentation and accessor methods, not an assumption that every internal component has a fixed name or structure. Object details can depend on the nlmixr2 version, estimation method, and fitted model. The examples below use hypothetical results; the R commands illustrate a workflow, while displayed values are illustrative rather than output from an actual study.
A Reliable Inspection Workflow
Begin by looking at the fit’s printed summary and the result of summary(fit). These provide a human-readable overview of the fitted model and its reported estimates. Then use accessor functions such as fixef(fit) for fixed-effect estimates and ranef(fit) for individual random-effect estimates, where those methods are available for the fitted object. The omega(fit) accessor can be used to retrieve the random-effects covariance information when supported by the fit.
For unfamiliar objects, inspect their structure and names before selecting a component: use str(fit) and names(fit). These are diagnostic tools, not guarantees that any particular internal field is a stable interface. Prefer documented accessors and summary methods for routine extraction. If a script must use a model-specific component, verify that component in the installed package version and make the dependency explicit.
Identify the estimated parameter names and how each is defined, including any log transformation or covariate relationship.
Check the reported parameter table, model-level information, warnings, and convergence information before extracting selected values.
Use fixed-effect accessors for population parameters and random-effect accessors for individual deviations; do not treat one as a substitute for the other.
Relate each reported label to the model code, and record whether the value is a transformed parameter or a value on the natural scale.
A parameter label is not a complete definition by itself. For example, a label such as lCL might denote \(\log(CL)\) if that is how the model was written, but another model could use the same letters differently. Confirm the model definition before interpreting a label or back-transforming a value. The earlier material on translating clearance and rate parameterizations is useful context for recognizing why different expressions can represent related quantities without being numerically interchangeable.
Worked Example: Extracting a Population Estimate and Its Uncertainty
Suppose a hypothetical one-compartment model defines the population parameter \(lCL=\log(CL)\), with \(CL\) measured in L/h. Its summary reports an estimate of 1.650 and standard error 0.120 for \(lCL\). The goal is to state the estimate and a Wald confidence interval for clearance on its natural scale.
First, identify the scale. The reported estimate is for \(lCL\), not for clearance in L/h. Under the stated definition, the point estimate on the clearance scale is:
Then calculate the interval on the estimated scale. A two-sided 95% Wald interval uses the estimate plus or minus 1.96 standard errors. This approximation assumes the estimator is sufficiently close to normally distributed on the \(lCL\) scale and that the reported standard error is an appropriate estimate of its sampling variability.
Exponentiate both endpoints to express the interval for \(CL\):
Thus, under the Wald approximation and the stated model definition, the estimated typical clearance is 5.207 L/h, with an approximate 95% confidence interval of 4.116 to 6.588 L/h. The interval is not a statement that there is a 95% probability that this fixed parameter lies between these endpoints. It is produced by a procedure that, under its assumptions, would cover the fixed parameter in about 95% of repeated samples.
Population Estimates and Uncertainty Summaries
Fixed effects represent population-level parameters in the model. Depending on how the model was specified, these may include typical values, covariate effects, residual-error parameters, or other estimated quantities. Read the parameter name together with the model code; do not assume that every row in a fixed-effect table has the same units or transformation.
A standard error describes estimated sampling variability on the scale of the reported estimate. A relative standard error, when provided, is commonly calculated as \(100\times SE/|\text{estimate}|\), expressed as a percentage. It is scale-dependent: a relative standard error for a log parameter is not automatically a relative standard error for the corresponding natural-scale parameter. Confidence intervals also depend on how they were constructed. A symmetric Wald interval on a log scale becomes asymmetric after exponentiation.
Tables may report columns with labels such as estimate, standard error, relative standard error, confidence limits, or back-transformed estimate. Check the table’s own labeling and documentation before interpreting a column. In particular, distinguish a confidence interval for a parameter from an interval describing individual variability, a prediction interval, or uncertainty in a simulated outcome.
Worked Example: Reading a Fixed-Effect Table
Suppose a hypothetical summary reports the fixed-effect row lCL with estimate 1.650, standard error 0.120, and relative standard error 7.27%. The model definition says \(lCL=\log(CL)\), with clearance in L/h. Verify the relative standard error and interpret these entries.
Calculation: Using the reported estimate and standard error on the same scale,
The 7.27% is relative to the magnitude of the log-scale estimate; it is not a claim that clearance itself has 7.27% uncertainty. The natural-scale point estimate is \(\exp(1.650)=5.207\) L/h. To present uncertainty for clearance, transform an interval for \(lCL\), as in the previous calculation, or use another explicitly justified interval method. Reporting the estimate as “1.650 L/h” would be incorrect because 1.650 is on the log-clearance scale.
Individual Estimates and Random Effects
In a common parameterization, an individual parameter is related to a population typical value through an individual random effect. For example, if \(CL_i=\exp(lCL+\eta_{CL,i})\), then \(lCL\) is the population log-clearance parameter and \(\eta_{CL,i}\) is an individual deviation on the log scale. The individual estimate is obtained by combining them and transforming back. The exact formula depends on the model; an additive parameterization or a different transformation requires a different interpretation.
Random-effect estimates are often conditional estimates based on an individual’s observations and the fitted population model. They are not direct measurements of an individual’s true random effect. Their precision depends on the amount and informativeness of that individual’s data and on the model. A random-effect estimate and an individual parameter estimate are therefore distinct quantities: one is a deviation on its defined scale, while the other may be a transformed parameter value.
Worked Example: From an Individual Random Effect to Clearance
For a hypothetical fit, let \(lCL=1.650\), and suppose the estimated random effect for individual 1 is \(\eta_{CL,1}=-0.182\). The model specifies \(CL_i=\exp(lCL+\eta_{CL,i})\). Calculate the individual clearance estimate and interpret the role of the random effect.
The negative random effect places this individual’s estimated clearance below the population typical value of \(\exp(1.650)=5.207\) L/h under this model. It does not mean that clearance is negative, and it should not be reported as an individual clearance of \(-0.182\) L/h: \(-0.182\) is a log-scale deviation. The interpretation is conditional on the stated model and does not establish that the estimate is the individual’s error-free or directly observed clearance.
Model-Level Summaries and Checks
The fit summary can also report model-level information such as the number of observations or individuals, objective-function information, and convergence or covariance diagnostics. Which items appear depends on the estimation method and the fitted object. Read the printed labels literally, and consult the method’s documentation if a quantity’s definition is unclear. A compact summary does not replace checking warnings or whether the estimates and uncertainty calculations are usable.
For example, AIC is defined as \(-2\ell+2k\), where \(\ell\) is the maximized log likelihood and \(k\) is the number of estimated parameters under the relevant convention. Do not treat an objective-function value as \(-2\ell\) unless that is its documented meaning for the fit. Comparisons of criteria require compatible likelihood definitions and the same data and outcome basis; a smaller printed number alone does not establish that one model is scientifically preferable.
Worked Example: Checking a Criterion Calculation
Suppose a hypothetical summary explicitly identifies an objective value as \(-2\ell=482.6\), and the model has \(k=6\) estimated parameters for the criterion being calculated. Compute AIC and state the scope of the result.
The arithmetic gives AIC 494.6 under the stated definition and parameter count. This number can support a relative comparison only with a suitably comparable model fit to the same data under a compatible likelihood and AIC convention. It is not an absolute measure of goodness of fit, and by itself it does not show that the model’s structure is appropriate.
Diagnostics, Alternatives, and Common Pitfalls
A robust workflow checks whether values are finite, whether labels match the model definition, and whether the requested quantities are actually available. Review warnings and convergence or covariance messages rather than relying on a clean-looking table. If a standard error or interval is missing, do not silently treat the estimate as precise; determine why the summary could not provide it. If a transformed estimate seems implausible, check the parameterization, units, and whether the transformation was applied to the correct quantity.
There are three practical ways to access results: the printed fit summary, accessor functions, and direct inspection of the object. The printed summary is convenient for review but is not ideal as a machine-readable data source. Accessors are generally preferable for programmatic extraction of defined quantities. Direct component access can be useful for investigation or specialized work, but it is more vulnerable to internal changes and should be checked against the installed version. Save the fitted object and record package and model versions when reproducibility matters.
- Confusing a label with a definition. A name such as lCL only means log clearance if the model defines it that way. Check the model code and transformation.
- Mixing scales. A log-scale estimate and its standard error are not quantities in L/h. Transform both interval endpoints when reporting a natural-scale interval.
- Confusing random effects with individual parameters. An eta estimate is generally a deviation on the model’s random-effect scale, not the individual parameter itself.
- Assuming internal fields are stable. Avoid hard-coding undocumented object paths without inspecting and validating them for the relevant package version.
- Over-interpreting summaries. A reported estimate, standard error, or model criterion does not by itself establish convergence, model adequacy, or clinical relevance.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions.
- A model defines \(lV=\log(V)\), where \(V\) is in L, and reports \(lV=2.00\). What is the natural-scale estimate, and what units does it have?
- A reported random effect is \(\eta_{CL,i}=0.10\). Under \(CL_i=\exp(lCL+\eta_{CL,i})\), is 0.10 the individual clearance in L/h? Explain.
- A fixed-effect estimate is 2.00 with standard error 0.20. Calculate the relative standard error using the usual estimate-based formula, and state what scale it describes.
- Why should a script generally prefer a documented accessor over an assumed internal object path?
- A summary reports an objective value of 500 but does not identify its relationship to the log likelihood. Can you calculate AIC from this value alone? Explain.
Solutions. (1) \(V=\exp(2.00)\approx 7.389\) L. The estimate is in liters because exponentiating the log-scale parameter returns \(V\) on its natural scale. (2) No. The value 0.10 is the individual random-effect deviation on the model’s log scale. The individual clearance estimate would require \(lCL\) as well: \(CL_i=\exp(lCL+0.10)\) L/h. (3) \(100(0.20/|2.00|)=10.0\%\). It describes relative standard error on the scale of the reported estimate, not automatically on a transformed natural scale. (4) Documented accessors provide a defined interface and are less dependent on internal implementation details; assumed paths may change across versions or object types. (5) No. AIC requires \(-2\ell\) under the relevant convention and the parameter count \(k\). Without knowing what 500 represents, it cannot be substituted safely into the AIC formula.