Tutorials › Pharmacometric Workflows and Reproducible Modeling › Comparing Covariance Outputs Across Tools

Software Landscape and Interoperability · Tutorial 221 of 399

Comparing Covariance Outputs Across Tools

Learn a reliable workflow for interpreting and converting random-effect covariance outputs across NONMEM, Monolix, and nlmixr2.

Intermediate 11 min read

What You'll Learn

  • Distinguish a random-effect covariance matrix from uncertainty in estimated parameters.
  • Convert between variances, standard deviations, correlations, and covariances.
  • Identify which representation a NONMEM, Monolix, or nlmixr2 output reports.
  • Check units, random-effect ordering, scale, and matrix validity before comparing tools.
  • Recognize when rounding or mismatched model definitions make a comparison misleading.

Why Covariance Outputs Need Translation

Two tools can describe the same random-effects distribution using different numerical quantities. One report may show variances and covariances, another standard deviations and correlations, and a third may expose a matrix whose entries need interpretation. Comparing the printed numbers directly can therefore make matching models look different—or make genuinely different models look alike.

The central task is to identify what each output represents, then express every result in the same form. This tutorial focuses on the covariance matrix of the model’s random effects, not on the uncertainty of the estimated population parameters. The latter is a different covariance object, often called a parameter-estimate covariance matrix.

Definition: For a vector of random effects \(\eta=(\eta_1,\ldots,\eta_q)^\mathsf{T}\), the random-effect covariance matrix is \(\Omega\), where \(\Omega_{ij}=\operatorname{Cov}(\eta_i,\eta_j)\). Its diagonal entries are variances, \(\Omega_{ii}=\operatorname{Var}(\eta_i)\); its off-diagonal entries are covariances. If the standard deviations are positive, the correlation is \(\rho_{ij}=\Omega_{ij}/\sqrt{\Omega_{ii}\Omega_{jj}}\).

In a common model, \(\eta\) has mean zero and a multivariate normal distribution with covariance matrix \(\Omega\). Normality is a model assumption, not a requirement for the algebraic conversions below: variance, covariance, and correlation are defined for any random effects with finite second moments. To calculate correlations, both variances must be positive. A covariance has units equal to the product of the units of its two random effects; a correlation is dimensionless.

One Matrix, Several Representations

Let \(s_i=\sqrt{\Omega_{ii}}\) be the standard deviation of random effect \(i\). Let \(D\) be the diagonal matrix with entries \(s_1,\ldots,s_q\), and let \(R\) be the correlation matrix. Then the equivalent representations satisfy:

$$ \Omega = D R D,\qquad \Omega_{ii}=s_i^2,\qquad \Omega_{ij}=\rho_{ij}s_i s_j,\qquad \rho_{ij}=\frac{\Omega_{ij}}{s_i s_j}. $$

The distinction matters even when the entries look similar. A diagonal value of \(0.09\) is a variance, so its standard deviation is \(0.30\), not \(0.09\). An off-diagonal value of \(0.012\) is a covariance, not a correlation; its corresponding correlation depends on both diagonal variances.

For a valid covariance matrix, \(\Omega\) must be symmetric and positive semidefinite. In two dimensions, this requires nonnegative diagonal entries and \(\Omega_{12}^2\leq\Omega_{11}\Omega_{22}\). When both variances are positive, this is equivalent to \(-1\leq\rho_{12}\leq1\). Higher-dimensional matrices must satisfy the positive-semidefinite condition as a whole; checking each pairwise correlation alone is not sufficient.

Worked Example: Converting a NONMEM-Style OMEGA Matrix

Suppose a hypothetical NONMEM output gives the following block for random effects on log clearance and log volume:

$$ \Omega = \begin{pmatrix} 0.0900 & 0.0120\\ 0.0120 & 0.250 \end{pmatrix}. $$

Treat the displayed entries as variances on the diagonal and a covariance off the diagonal. The standard deviations are \(s_1=\sqrt{0.0900}=0.300\) and \(s_2=\sqrt{0.250}=0.500\). The correlation is:

$$ \rho_{12}=\frac{0.0120}{(0.300)(0.500)} =\frac{0.0120}{0.150}=0.0800. $$

Thus the equivalent standard-deviation/correlation representation is \(s_1=0.300\), \(s_2=0.500\), and \(\rho_{12}=0.0800\). The covariance matrix is symmetric, and the two-dimensional validity check gives \(0.0120^2=0.000144\leq(0.0900)(0.250)=0.0225\). The matrix is admissible by this check. Because both effects are on log scales, these standard deviations and the covariance are on those log-effect scales; they are not directly standard deviations or covariances of clearance and volume in their original units.

Extract First, Convert Second

There is no safe rule that every file or results table from a particular tool always uses one representation. The report, export, estimation method, and software version can affect what is displayed. Read the parameter labels and the relevant output documentation, and confirm the meaning against the model specification. The following are practical starting points, not substitutes for that check.

ToolWhere to beginWhat to establish before comparing
NONMEMInspect the OMEGA specification and the corresponding estimation output, including whether a block is used.Determine whether each reported diagonal is a variance and each block off-diagonal is a covariance; confirm the order of the random effects.
MonolixInspect the random-effects distribution settings and the parameter results or exported results table.Check whether the reported quantities are standard deviations, correlations, variances, or matrix entries; confirm parameter names and ordering.
nlmixr2Inspect the fitted object and its reported or extracted omega information, along with the model parameterization.Check the object’s documented meaning, matrix dimension, random-effect order, and whether values are transformed or displayed in another representation.

A robust comparison uses the same canonical representation on both sides, commonly the full covariance matrix \(\Omega\). Alternatively, standard deviations plus correlations are useful when that is what a tool reports. Record the mapping from each matrix position to its random effect; matching entries by row and column number without checking that mapping can silently compare different effects.

1
Identify the object.
Confirm that the output concerns random-effect variability, rather than the covariance or correlation of estimated parameters.
2
Record the model definition.
Write down the random effects, their order, their scale, and the distribution structure used for each fit.
3
Read the representation.
Use labels, model syntax, and software documentation to classify each entry as variance, standard deviation, covariance, or correlation.
4
Convert to a common form.
Use \(\Omega_{ii}=s_i^2\) and \(\Omega_{ij}=\rho_{ij}s_i s_j\), or recover standard deviations and correlations from \(\Omega\).
5
Check and compare.
Check symmetry, positive semidefiniteness, units, ordering, and numerical precision before interpreting discrepancies.

Worked Example: Converting Standard Deviations and Correlation

Suppose a hypothetical Monolix results export reports random-effect standard deviations of \(0.200\) for log clearance and \(0.400\) for log volume, with a correlation of \(-0.350\). To compare with a covariance-matrix output, calculate the diagonal variances and off-diagonal covariance:

$$ \Omega_{11}=(0.200)^2=0.0400,\qquad \Omega_{22}=(0.400)^2=0.160, $$
$$ \Omega_{12}=\Omega_{21}=(-0.350)(0.200)(0.400)=-0.0280. $$

The resulting matrix is:

$$ \Omega = \begin{pmatrix} 0.0400 & -0.0280\\ -0.0280 & 0.160 \end{pmatrix}. $$

As a check, \((-0.0280)^2=0.000784\leq(0.0400)(0.160)=0.00640\), so the two-dimensional matrix satisfies the covariance bound. The negative sign indicates that larger-than-typical values of one random effect tend to occur with smaller-than-typical values of the other under the model. It does not by itself establish a causal relationship.

Justification of the Conversion

The formulas follow directly from the definitions. Variance is the square of standard deviation, so \(\Omega_{ii}=s_i^2\). For two random effects with positive standard deviations, correlation is their covariance divided by the product of their standard deviations:

$$ \rho_{ij} =\frac{\operatorname{Cov}(\eta_i,\eta_j)} {\sqrt{\operatorname{Var}(\eta_i)}\sqrt{\operatorname{Var}(\eta_j)}} =\frac{\Omega_{ij}}{s_i s_j}. $$

Rearranging gives \(\Omega_{ij}=\rho_{ij}s_i s_j\). For every pair of indices, these relationships produce \(\Omega=DRD\), since the \((i,j)\) entry of \(DRD\) is \(s_i\rho_{ij}s_j\). The conversion is exact when the inputs refer to the same random effects on the same scales. It cannot, by itself, make two differently specified random-effects models equivalent.

Worked Example: Putting an nlmixr2 Matrix in Comparable Form

Consider a hypothetical nlmixr2 result whose documented covariance matrix for random effects on log clearance and log volume is:

$$ \Omega = \begin{pmatrix} 0.160 & -0.0240\\ -0.0240 & 0.0900 \end{pmatrix}. $$

The diagonal entries are variances, so the standard deviations are \(s_1=\sqrt{0.160}=0.400\) and \(s_2=\sqrt{0.0900}=0.300\). The correlation is:

$$ \rho_{12}=\frac{-0.0240}{(0.400)(0.300)} =\frac{-0.0240}{0.120}=-0.200. $$

The equivalent correlation matrix is therefore:

$$ R = \begin{pmatrix} 1 & -0.200\\ -0.200 & 1 \end{pmatrix}. $$

This can be compared with a tool that reports standard deviations and correlations, provided its first random effect is also log clearance and its second is log volume. The matrix passes the pairwise check because \((-0.0240)^2=0.000576\leq(0.160)(0.0900)=0.0144\). The check confirms admissibility for this two-effect example; it does not prove that another tool used the same model.

Diagnostics, Alternatives, and Limitations

Useful diagnostics are simple but essential. Check that the matrix is symmetric to the precision shown, that diagonal entries are nonnegative, and that the matrix is positive semidefinite. If the output gives standard deviations and correlations, check that standard deviations are nonnegative and correlations lie between \(-1\) and \(1\). If converting gives an impossible correlation or a matrix that is not positive semidefinite, revisit the representation, ordering, transcription, and rounding before concluding that the model itself is invalid.

Rounding can cause apparent failures. A matrix printed to a few decimal places may not remain exactly positive semidefinite after its entries are rounded independently. Small violations close to the displayed precision should be checked using full-precision estimates where available. A substantial violation may instead indicate that an entry was misread, that a standard deviation was mistaken for a variance, or that outputs from different model components were combined.

The main alternative representations have different practical strengths. Covariance matrices give the complete second-moment description in one object and are convenient for direct matrix operations. Standard deviations and correlations are often easier to interpret because each standard deviation is tied to one effect and correlations are bounded and unitless. Neither form is inherently more comparable: the appropriate choice is the one both outputs can be converted to without losing information. Reporting only standard deviations discards relationships between effects if off-diagonal correlations are omitted.

A valid numerical conversion is not sufficient evidence that two fits match. Check that the effects use the same transformations and scales: a random effect on log clearance is not the same quantity as one defined additively on clearance. Also check the included random effects, fixed or estimated covariance terms, and the order of effects. In addition, estimates can differ because fits, data handling, or estimation settings differ; covariance conversion does not diagnose those differences.

A frequent mistake is to treat every item labelled “covariance” as \(\Omega\). A covariance matrix for estimated parameter uncertainty describes uncertainty in estimates, whereas \(\Omega\) describes between-individual random-effect variation in the model. The correction is to identify the object’s role and indices before interpreting its entries. Another common error is comparing a variance from one output directly with a standard deviation from another. Square the standard deviation—or take the square root of the variance—before making the comparison.

Key takeaway: Compare like with like. Identify the random effects and their scales, establish whether each output reports variances, standard deviations, covariances, or correlations, and convert to a common representation before drawing conclusions.

Check Your Understanding

Answer each question, then check the solutions below.

  1. A tool reports a variance of \(0.0625\) for a random effect on log clearance. What is its standard deviation?
  2. Two random effects have standard deviations \(0.30\) and \(0.50\), with correlation \(0.20\). What is their covariance?
  3. A reported covariance is \(-0.018\), and the two standard deviations are \(0.30\) and \(0.40\). What is the correlation?
  4. Why is it not enough to match two tools’ matrix entries by position?
  5. What does a random-effect covariance matrix describe, and how does it differ from covariance among estimated parameters?

Solutions. (1) The standard deviation is \(\sqrt{0.0625}=0.250\), on the log-clearance effect scale. (2) The covariance is \((0.20)(0.30)(0.50)=0.0300\). (3) The correlation is \(-0.018/[(0.30)(0.40)]=-0.150\). (4) The random-effect ordering may differ, so the same matrix position may refer to different effects; confirm names, ordering, and scales first. (5) The random-effect matrix describes variability and dependence among model random effects. Covariance among estimated parameters instead describes uncertainty and dependence in the parameter estimates; the two matrices answer different questions.

Clinical Biostats