Why the Result Object Is Not the Parameterization
An nlmixr2 fit object contains estimated values, but those values do not by themselves specify how to use them in mrgsolve. The meaning of an estimate depends on how the model uses it. For example, an estimated fixed effect of 1.61 could be a log-clearance parameter that must be exponentiated, or it could be a clearance value in L/h. Those interpretations produce different simulation models.
The safe transfer is therefore not “copy every estimate into a parameter field.” It is: identify the estimate by name, read the expression in the fitted model that uses it, and supply mrgsolve with values and random-effect structure that reproduce that expression. The mapping material from earlier in the course helps establish which names correspond; here the emphasis is on extracting and using estimates from an nlmixr2 result object.
In an nlmixr2 model, the fixed effects are often initialized and estimated through named parameters in the model’s ini block, while the model expressions specify how those parameters enter the pharmacokinetic equations. An nlmixr2 result object commonly exposes fixed-effect estimates in fields such as parFixedDf and random-effect covariance estimates in omega. The exact available fields and table columns can depend on the object and software version. Inspect the fitted object and its summary, then select estimates by their parameter names; do not assume that a particular position or printed column always has the desired meaning.
In mrgsolve, fixed effects are supplied as model parameters, while random effects are generated according to the covariance structure declared for the model. The mrgsolve model’s code determines whether an eta is added to a parameter, added on a log scale, or used in another expression. The transferred values must agree with that code.
Read the Fitted Model Before Extracting Values
For each parameter, record four items before assigning anything: its estimate’s name in the fit, the expression that uses it in the nlmixr2 model, its scale and units, and the corresponding expression and parameter name in mrgsolve. For random effects, also record the eta order and whether the fitted covariance is diagonal or includes covariances.
Consider an nlmixr2 model with expressions equivalent to cl = exp(tcl + eta.cl), v = exp(tv + eta.v), and ka = exp(tka). Here the fixed effects tcl and tv are log parameters. The typical values on the original scale are \(\exp(tcl)\) and \(\exp(tv)\); the individual values include the additional eta terms. If the mrgsolve model instead defines CL = TVCL * exp(ETA(1)), its fixed parameter TVCL needs the natural-scale typical clearance, not the log of that clearance.
That conversion follows directly from the exponential identity:
Thus, the two implementations have the same individual clearance when TVCL = exp(tcl) and the corresponding eta has the same distribution. The equality depends on preserving both the fixed-effect transformation and the random-effect assignment.
Worked Example: Converting Log-Scale Fixed Effects
Suppose a hypothetical nlmixr2 fit uses cl = exp(tcl + eta.cl), v = exp(tv + eta.v), and ka = exp(tka). The named fixed-effect estimates are tcl = 1.6094, tv = 3.6889, and tka = 0.1823. Assume these correspond to clearance in L/h, volume in L, and absorption rate in 1/h.
Clearance. The natural-scale typical value is \(\exp(1.6094)\), which is approximately 5.000 L/h. This is the value to assign to an mrgsolve parameter such as TVCL if its model calculates individual clearance as TVCL * exp(ETA(1)).
Volume. The natural-scale typical value is \(\exp(3.6889)\), approximately 40.00 L. Assign 40.00 L to a parameter such as TVV if the mrgsolve expression multiplies it by an exponential eta.
Absorption rate. The natural-scale value is \(\exp(0.1823)\), approximately 1.200 1/h. If absorption has no random effect in the fitted model, it should be assigned as a fixed value rather than given an eta simply because other parameters have random effects.
The corresponding mrgsolve assignments would therefore supply TVCL = 5.000, TVV = 40.00, and KA = 1.200, assuming the mrgsolve model uses those names and units. Assigning 1.6094 directly to TVCL would make the model use a clearance of about 1.609 L/h before individual variation, not the fitted typical clearance of 5.000 L/h.
Transfer the Random-Effect Covariance, Not Just Its Diagonal
The nlmixr2 omega object represents the covariance matrix of the eta vector under the fitted model. Its diagonal entries are eta variances; its off-diagonal entries are covariances. They are not standard deviations. In a matching mrgsolve model, the omega matrix must describe the same eta distribution, in the same eta order, and the model expressions must use each eta for the corresponding parameter.
For an eta vector with covariance matrix \(\Omega\), the variance of eta \(j\) is the diagonal entry \(\Omega_{jj}\). If the model uses an exponential eta, that variance is on the log scale. For two eta values, the correlation is the covariance divided by the product of their standard deviations:
Consequently, replacing an omega variance with its square root changes the random-effect distribution. Dropping an off-diagonal entry also changes that distribution when the fitted model estimated a nonzero covariance.
Worked Example: Preserving Variances and Covariance
Suppose a hypothetical fit estimates eta values for log-clearance and log-volume, in that order, with the covariance matrix below. The diagonal entries are 0.09 and 0.16; the covariance is 0.03. The mrgsolve model uses CL = TVCL * exp(ETA(1)) and V = TVV * exp(ETA(2)).
The eta standard deviations are \(\sqrt{0.09}=0.3000\) and \(\sqrt{0.16}=0.4000\). The correlation is \(0.03/(0.3000 \times 0.4000)=0.2500\). These calculations check the scale and make clear that 0.3000 and 0.4000 are standard deviations, not the diagonal values to enter as variances.
The covariance matrix to transfer remains the displayed matrix, provided the mrgsolve model uses the same eta order and exponential expressions. In R, the fixed effects can be assigned by name with an expression such as mod <- param(mod, list(TVCL = 5, TVV = 40)), where the names are declared by the mrgsolve model. If the model’s named omega block is IIV, the corresponding assignment is omat(mod, "IIV") <- matrix(c(0.09, 0.03, 0.03, 0.16), nrow = 2). The matrix rows and columns must follow the model’s eta order; confirm that order rather than relying on the way a matrix happens to print.
If the mrgsolve model declares only diagonal omega values, it cannot represent this nonzero covariance as written. Replacing the matrix with diagonal entries would discard the fitted correlation. The model declaration and eta ordering must be checked before simulation.
Preserve the Random-Effect Expression
A variance cannot be transferred independently of the expression in which its eta is used. For example, an additive eta on clearance and an exponential eta on clearance have different meanings and units. If the fitted model uses cl = tcl + eta.cl, then eta.cl is additive on the clearance scale, and its variance has units \((\mathrm{L/h})^2\). If the fitted model uses cl = exp(tcl + eta.cl), the eta is dimensionless and acts on the log scale. These are not interchangeable descriptions of the same model.
The same caution applies to transformations such as a logit link for a fraction. A fixed effect on a link scale must be used with the matching transformation in mrgsolve; it should not be interpreted as a fraction unless the model applies the inverse link. For every eta, verify both the scale of its variance and the exact parameter expression before transferring it.
Worked Example: An Additive Eta Is Not a Log Eta
Suppose a hypothetical nlmixr2 model defines cl = tcl + eta.cl, with tcl = 5.0 L/h and an estimated eta variance of \(0.25\;(\mathrm{L/h})^2\). A matching mrgsolve expression is CL = TVCL + ETA(1), with TVCL = 5.0 L/h and omega variance 0.25. The eta standard deviation is \(\sqrt{0.25}=0.5000\) L/h.
If the variance were mistakenly treated as a log-scale variance and the mrgsolve expression changed to TVCL * exp(ETA(1)), the individual clearance would instead be positive and vary multiplicatively. In particular, setting eta to 0.5 gives an additive-model clearance of \(5.0+0.5=5.500\) L/h, whereas the exponential model gives \(5.0\exp(0.5)\), approximately 8.244 L/h. The difference is not a rounding issue: it is a different random-effects model. The correct transfer preserves the additive expression and the variance of 0.25 on the clearance scale.
A Practical Transfer and Verification Sequence
Use a short, explicit sequence to reduce errors. A result object is useful only when its estimates can be traced back to the fitted model and forward to the simulation expressions.
Review the result summary and relevant object fields, including the fixed-effect table and omega matrix. Confirm the exact parameter names, estimate values, and matrix dimensions.
Determine whether each fixed effect is already on the natural scale or is used through a transformation. Record the units and any eta expression associated with it.
Convert fixed effects only when required by the mrgsolve expression. Assign omega as a covariance matrix, maintaining its dimensions and eta ordering.
Confirm that mrgsolve declares every assigned parameter and that each eta enters the intended parameter with the fitted transformation. Check units and fixed versus random status.
Use a small, controlled simulation to inspect assigned values and the resulting individual parameters. Large discrepancies should prompt a check of names, transformations, units, eta order, and omega—not an automatic change to the estimates.
The last step is a diagnostic, not proof that two implementations are equivalent. It can reveal mistakes such as an untransformed log parameter, a variance entered as a standard deviation, or an eta attached to the wrong parameter. It does not establish that every model component or event is aligned.
Common Failure Modes and Alternatives
| Failure mode | Why it is wrong | Correction |
|---|---|---|
| Copying estimates by row position | Printed or stored order may differ from the model’s parameter order. | Match named estimates to model expressions, then verify the names in mrgsolve. |
| Copying a log-scale fixed effect directly | The simulation may use a natural-scale parameter and then treat the log estimate as its value. | Apply the transformation required by the mrgsolve expression, such as exponentiating a log typical value. |
| Entering square roots of omega diagonal elements | Omega stores variances; a square root is a standard deviation. | Supply the covariance matrix on the eta scale used by the model. |
| Dropping covariance or reordering etas | The resulting joint eta distribution or parameter assignments change. | Preserve matrix entries and dimensions, and verify the declared eta order. |
| Adding random effects to fixed-only parameters | This changes the fitted model’s variability structure. | Transfer random effects only where the fitted model specifies them. |
A common mistake is to reason, “The estimate is 1.61, so I will set the mrgsolve clearance parameter to 1.61.” That is correct only if the estimate is a clearance in the same units and the mrgsolve expression uses it directly. If it is tcl in an expression such as exp(tcl + eta.cl), the typical clearance is \(\exp(1.61)\), not 1.61. The correction is to trace the estimate through its model expression before assigning it.
The main alternative is to change the mrgsolve expressions to match the fitted model’s parameterization rather than transforming estimates to match the existing simulation model. Either approach can be appropriate, but the fixed effects, random effects, and expressions must agree together. For example, a log-scale fixed effect can remain on the log scale in mrgsolve if the model expression exponentiates it. Merely changing the numerical assignment without changing the expression is not an equivalent alternative.
Check Your Understanding
Answer each question by tracing the estimate through the model expression. Brief solutions follow the questions.
- A fitted model uses
cl = exp(tcl + eta.cl)and estimatestcl = 2.303. What typical clearance should be supplied to an mrgsolve model usingTVCL * exp(ETA(1))? - An omega diagonal entry is 0.36. What are the eta variance and standard deviation?
- A fitted model uses an additive eta on clearance, with variance \(0.04\;(\mathrm{L/h})^2\). Should the corresponding mrgsolve expression use an additive or exponential eta?
- Why is it unsafe to transfer fixed-effect estimates by their position in a printed table?
- A two-eta covariance matrix has diagonal entries 0.04 and 0.25 and covariance 0.05. What is the eta correlation?
Solutions. (1) The typical clearance is \(\exp(2.303)\), approximately 10.00 in the clearance units used by the model. (2) The variance is 0.36 and the standard deviation is \(\sqrt{0.36}=0.6000\); transfer the variance in the omega matrix. (3) Use an additive eta, because the fitted eta is additive on the clearance scale and its variance has clearance-squared units. (4) Table order can differ from parameter or eta order, so values may be assigned to the wrong names; map by name and confirm each model expression. (5) The standard deviations are \(\sqrt{0.04}=0.2000\) and \(\sqrt{0.25}=0.5000\), so the correlation is \(0.05/(0.2000 \times 0.5000)=0.5000\).