Skip to contents

Stabilizing Covariance Estimates with preconditionFit()

Matthew Fidler

2026-09-29

Source: vignettes/articles/precondition.Rmd
precondition.Rmd

The problem: ill-conditioned covariance matrices

After fitting a nonlinear mixed-effects model with FOCEI, the standard errors (SEs) of the population parameters are derived from the variance-covariance matrix of the parameter estimates. This matrix is assembled from the R matrix (second-derivative / Hessian approximation) and, optionally, the S matrix (cross-product of first derivatives). When the parameters are on very different scales, or when two parameters are nearly collinear, the R matrix becomes ill-conditioned: small rounding errors in the gradient calculations are amplified during the matrix inversion and the resulting covariance matrix is unreliable.

Symptoms of this problem include:

  • covMethod reported as "r" or "s" rather than the preferred "r,s"
  • NaN or negative values on the diagonal of the covariance matrix
  • Standard errors that are implausibly large or small relative to the estimates
  • %RSE values that are very large

The solution: preconditioning

Aoki, Nordgren, and Hooker (2016) showed that a simple linear reparameterization of the fixed-effects parameters can dramatically improve the condition number of the R matrix without changing the model or its fit. The idea is to find a matrix P such that P R P^T is close to the identity matrix, run FOCEI on the reparameterized model (which converges to a numerically stable covariance matrix), and then transform the result back to the original parameterization.

nlmixr2extra implements this approach in preconditionFit().

Reference: Aoki Y, Nordgren R, Hooker AC. Preconditioning of Nonlinear Mixed Effects Models for Stabilization of Variance-Covariance Matrix Computations. AAPS J. 2016;18(2):505–518. doi:[10.1208/s12248-016-9866-5](https://doi.org/10.1208/s12248-016-9866-5)

Basic usage 

library(nlmixr2extra)

oneCompartment <- function() {
  ini({
    tka <- 0.45  # log Ka
    tcl <- 1     # log Cl
    tv  <- 3.45  # log V
    eta.ka ~ 0.6
    eta.cl ~ 0.3
    eta.v  ~ 0.1
    add.sd <- 0.7
  })
  model({
    ka <- exp(tka + eta.ka)
    cl <- exp(tcl + eta.cl)
    v  <- exp(tv  + eta.v)
    d/dt(depot)  <- -ka * depot
    d/dt(center) <-  ka * depot - cl/v * center
    cp <- center / v
    cp ~ add(add.sd)
  })
}

fit := nlmixr2(oneCompartment, data = nlmixr2data::theo_sd,
               est = "focei", control = list(print = 0))
fit

ka=exp(tka+eta.ka)cl=exp(tcl+eta.cl)v=exp(tv+eta.v)ddepotdt=−ka×depotdcenterdt=ka×depot−clv×centercp=centervcp∼add(add.sd)\begin{align*} {ka} & = \exp\left({tka}+{eta.ka}\right) \\ {cl} & = \exp\left({tcl}+{eta.cl}\right) \\ {v} & = \exp\left({tv}+{eta.v}\right) \\ \frac{d \: depot}{dt} & = -{ka} {\times} {depot} \\ \frac{d \: center}{dt} & = {ka} {\times} {depot}-\frac{{cl}}{{v}} {\times} {center} \\ {cp} & = \frac{{center}}{{v}} \\ {cp} & \sim add({add.sd}) \end{align*}

If the covariance method reported is not "r,s" (or you simply want a more robust covariance estimate), apply preconditioning:

invisible(preconditionFit(fit))
#> → loading into symengine environment...
#> → pruning branches (`if`/`else`) of full model...
#> ✔ done
#> [====|====|====|====|====|====|====|====|====|====] 0:00:00
#> → calculate sensitivities
#> [====|====|====|====|====|====|====|====|====|====] 0:00:00
#> → calculate ∂(f)/∂(η)
#> [====|====|====|====|====|====|====|====|====|====] 0:00:00
#> → calculate ∂(R²)/∂(η)
#> [====|====|====|====|====|====|====|====|====|====] 0:00:00
#> → finding duplicate expressions in inner model...
#> → finding duplicate expressions in EBE model...
#> → compiling inner model...
#> ✔ done
#> → finding duplicate expressions in FD model...
#> → compiling EBE model...
#> ✔ done
#> → compiling events FD model...
#> ✔ done
#> rxode2 5.1.7 using 1 threads (see ?getRxThreads)
#>   no cache: create with `rxCreateCache()`
#> 
#> Attaching package: 'rxode2'
#> The following objects are masked from 'package:nlmixr2est':
#> 
#>     boxCox, yeoJohnson
#> Key: U: Unscaled Parameters; X: Back-transformed parameters; G: Gill difference gradient approximation
#> F: Forward difference gradient approximation
#> C: Central difference gradient approximation
#> M: Mixed forward and central difference gradient approximation
#> A: Analytic (forward sensitivity) gradient (fast=TRUE)
#> Unscaled parameters for Omegas=chol(solve(omega));
#> Diagonals are transformed, as specified by foceiControl(diagXform=)
#> 
#> |    #| Function Val. |nlmixr2Pre_tka |nlmixr2Pre_tcl |nlmixr2Pre_tv |nlmixr2Pre_add.sd |
#> |.....................|        o1 |        o2 |        o3 |...........|
#> |    1|     116.81105 |   -0.9752 |    -1.000 |     1.000 |   -0.7133 |
#> |.....................|   -0.9898 |   -0.9890 |   -0.9880 |...........|
#> |    U|               |     12.83 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    X|               |     12.83 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    2|     116.81098 |   -0.9752 |    -1.000 |     1.000 |   -0.7133 |
#> |.....................|   -0.9898 |   -0.9890 |   -0.9880 |...........|
#> |    U|               |     12.83 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    X|               |     12.83 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    3|     117.16602 |   -0.7752 |    -1.000 |     1.000 |   -0.7133 |
#> |.....................|   -0.9898 |   -0.9890 |   -0.9880 |...........|
#> |    U|               |     15.40 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    X|               |     15.40 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    4|     116.81090 |   -0.9752 |   -0.8000 |     1.000 |   -0.7133 |
#> |.....................|   -0.9898 |   -0.9890 |   -0.9880 |...........|
#> |    U|               |     12.83 |    -6.756 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    X|               |     12.83 |    -6.756 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    5|     355.05484 |   -0.9752 |    -1.000 |     1.200 |   -0.7133 |
#> |.....................|   -0.9898 |   -0.9890 |   -0.9880 |...........|
#> |    U|               |     12.83 |    -6.786 |     1889. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    X|               |     12.83 |    -6.786 |     1889. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    6|     118.06431 |   -0.9752 |    -1.000 |     1.000 |   -0.5133 |
#> |.....................|   -0.9898 |   -0.9890 |   -0.9880 |...........|
#> |    U|               |     12.83 |    -6.786 |     1574. |     263.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    X|               |     12.83 |    -6.786 |     1574. |     263.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    7|     118.02696 |   -0.9752 |    -1.000 |     1.000 |   -0.7133 |
#> |.....................|   -0.7898 |   -0.9890 |   -0.9880 |...........|
#> |    U|               |     12.83 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.417 |     1.945 |     2.666 |...........|
#> |    X|               |     12.83 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.417 |     1.945 |     2.666 |...........|
#> |    8|     116.96433 |   -0.9752 |    -1.000 |     1.000 |   -0.7133 |
#> |.....................|   -0.9898 |   -0.7890 |   -0.9880 |...........|
#> |    U|               |     12.83 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.259 |     2.048 |     2.666 |...........|
#> |    X|               |     12.83 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.259 |     2.048 |     2.666 |...........|
#> |    9|     116.82676 |   -0.9752 |    -1.000 |     1.000 |   -0.7133 |
#> |.....................|   -0.9898 |   -0.9890 |   -0.7880 |...........|
#> |    U|               |     12.83 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.741 |...........|
#> |    X|               |     12.83 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.741 |...........|
#> |   10|     117.13147 |    -1.175 |    -1.000 |     1.000 |   -0.7133 |
#> |.....................|   -0.9898 |   -0.9890 |   -0.9880 |...........|
#> |    U|               |     10.27 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    X|               |     10.27 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> 
#> |    #| Function Val. |nlmixr2Pre_tka |nlmixr2Pre_tcl |nlmixr2Pre_tv |nlmixr2Pre_add.sd |
#> |.....................|        o1 |        o2 |        o3 |...........|
#> |   11|     116.81517 |   -0.9752 |    -1.200 |     1.000 |   -0.7133 |
#> |.....................|   -0.9898 |   -0.9890 |   -0.9880 |...........|
#> |    U|               |     12.83 |    -6.815 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    X|               |     12.83 |    -6.815 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |   12|     357.44856 |   -0.9752 |    -1.000 |    0.8000 |   -0.7133 |
#> |.....................|   -0.9898 |   -0.9890 |   -0.9880 |...........|
#> |    U|               |     12.83 |    -6.786 |     1259. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    X|               |     12.83 |    -6.786 |     1259. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |   13|     118.45718 |   -0.9752 |    -1.000 |     1.000 |   -0.9133 |
#> |.....................|   -0.9898 |   -0.9890 |   -0.9880 |...........|
#> |    U|               |     12.83 |    -6.786 |     1574. |     175.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    X|               |     12.83 |    -6.786 |     1574. |     175.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |   14|     117.97931 |   -0.9752 |    -1.000 |     1.000 |   -0.7133 |
#> |.....................|    -1.190 |   -0.9890 |   -0.9880 |...........|
#> |    U|               |     12.83 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.100 |     1.945 |     2.666 |...........|
#> |    X|               |     12.83 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.100 |     1.945 |     2.666 |...........|
#> |   15|     117.03261 |   -0.9752 |    -1.000 |     1.000 |   -0.7133 |
#> |.....................|   -0.9898 |    -1.189 |   -0.9880 |...........|
#> |    U|               |     12.83 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.843 |     2.666 |...........|
#> |    X|               |     12.83 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.843 |     2.666 |...........|
#> |   16|     116.87995 |   -0.9752 |    -1.000 |     1.000 |   -0.7133 |
#> |.....................|   -0.9898 |   -0.9890 |    -1.188 |...........|
#> |    U|               |     12.83 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.591 |...........|
#> |    X|               |     12.83 |    -6.786 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.591 |...........|
#> |   17|     116.81773 |   -0.9803 |   -0.8066 |     1.000 |   -0.6997 |
#> |.....................|   -0.9918 |   -0.9708 |   -0.9248 |...........|
#> |    U|               |     12.77 |    -6.757 |     1575. |     222.9 |
#> |.....................|     1.257 |     1.955 |     2.690 |...........|
#> |    X|               |     12.77 |    -6.757 |     1575. |     222.9 |
#> |.....................|     1.257 |     1.955 |     2.690 |...........|
#> |   18|     116.81210 |   -0.9752 |   -0.7600 |     1.000 |   -0.7133 |
#> |.....................|   -0.9898 |   -0.9890 |   -0.9880 |...........|
#> |    U|               |     12.83 |    -6.750 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    X|               |     12.83 |    -6.750 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |   19|     116.82828 |   -0.9769 |   -0.8042 |     1.000 |   -0.7009 |
#> |.....................|   -0.9921 |   -0.9775 |    -1.035 |...........|
#> |    U|               |     12.81 |    -6.757 |     1575. |     222.6 |
#> |.....................|     1.257 |     1.951 |     2.649 |...........|
#> |    X|               |     12.81 |    -6.757 |     1575. |     222.6 |
#> |.....................|     1.257 |     1.951 |     2.649 |...........|
#> |   20|     116.81286 |   -0.9929 |   -0.7823 |     1.000 |   -0.7133 |
#> |.....................|   -0.9898 |   -0.9890 |   -0.9880 |...........|
#> |    U|               |     12.61 |    -6.754 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    X|               |     12.61 |    -6.754 |     1574. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> 
#> |    #| Function Val. |nlmixr2Pre_tka |nlmixr2Pre_tcl |nlmixr2Pre_tv |nlmixr2Pre_add.sd |
#> |.....................|        o1 |        o2 |        o3 |...........|
#> |   21|     116.82180 |   -0.9782 |   -0.8012 |     1.000 |   -0.7090 |
#> |.....................|   -0.9901 |    -1.012 |   -0.9798 |...........|
#> |    U|               |     12.79 |    -6.756 |     1575. |     220.8 |
#> |.....................|     1.258 |     1.934 |     2.669 |...........|
#> |    X|               |     12.79 |    -6.756 |     1575. |     220.8 |
#> |.....................|     1.258 |     1.934 |     2.669 |...........|
#> |   22|     117.46112 |   -0.9752 |   -0.8100 |     1.010 |   -0.7133 |
#> |.....................|   -0.9898 |   -0.9890 |   -0.9880 |...........|
#> |    U|               |     12.83 |    -6.758 |     1590. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |    X|               |     12.83 |    -6.758 |     1590. |     219.9 |
#> |.....................|     1.259 |     1.945 |     2.666 |...........|
#> |   23|     116.81006 |   -0.9707 |   -0.7922 |    0.9997 |   -0.7165 |
#> |.....................|   -0.9880 |   -0.9817 |   -0.9808 |...........|
#> |    U|               |     12.89 |    -6.755 |     1574. |     219.2 |
#> |.....................|     1.260 |     1.949 |     2.669 |...........|
#> |    X|               |     12.89 |    -6.755 |     1574. |     219.2 |
#> |.....................|     1.260 |     1.949 |     2.669 |...........|
#> |   24|     116.81125 |   -0.9708 |   -0.7915 |    0.9995 |   -0.7123 |
#> |.....................|    -1.001 |   -0.9813 |   -0.9796 |...........|
#> |    U|               |     12.89 |    -6.755 |     1573. |     220.1 |
#> |.....................|     1.249 |     1.949 |     2.669 |...........|
#> |    X|               |     12.89 |    -6.755 |     1573. |     220.1 |
#> |.....................|     1.249 |     1.949 |     2.669 |...........|
#> |   25|     116.81557 |   -0.9705 |   -0.7820 |    0.9997 |   -0.7068 |
#> |.....................|   -0.9879 |   -0.9813 |   -0.9804 |...........|
#> |    U|               |     12.89 |    -6.753 |     1574. |     221.3 |
#> |.....................|     1.260 |     1.949 |     2.669 |...........|
#> |    X|               |     12.89 |    -6.753 |     1574. |     221.3 |
#> |.....................|     1.260 |     1.949 |     2.669 |...........|
#> |   26|     116.81176 |   -0.9739 |   -0.7863 |    0.9995 |   -0.7201 |
#> |.....................|   -0.9932 |   -0.9920 |   -0.9836 |...........|
#> |    U|               |     12.85 |    -6.754 |     1573. |     218.4 |
#> |.....................|     1.256 |     1.944 |     2.668 |...........|
#> |    X|               |     12.85 |    -6.754 |     1573. |     218.4 |
#> |.....................|     1.256 |     1.944 |     2.668 |...........|
#> |   27|     117.40188 |   -0.9705 |   -0.7821 |     1.009 |   -0.7167 |
#> |.....................|   -0.9879 |   -0.9813 |   -0.9804 |...........|
#> |    U|               |     12.89 |    -6.753 |     1589. |     219.1 |
#> |.....................|     1.260 |     1.949 |     2.669 |...........|
#> |    X|               |     12.89 |    -6.753 |     1589. |     219.1 |
#> |.....................|     1.260 |     1.949 |     2.669 |...........|
#> |   28|     116.80977 |   -0.9780 |   -0.7989 |    0.9996 |   -0.7162 |
#> |.....................|   -0.9926 |   -0.9727 |   -0.9802 |...........|
#> |    U|               |     12.80 |    -6.756 |     1574. |     219.2 |
#> |.....................|     1.256 |     1.954 |     2.669 |...........|
#> |    X|               |     12.80 |    -6.756 |     1574. |     219.2 |
#> |.....................|     1.256 |     1.954 |     2.669 |...........|
#> |   29|     116.81181 |   -0.9680 |   -0.8089 |    0.9996 |   -0.7161 |
#> |.....................|   -0.9924 |   -0.9735 |   -0.9806 |...........|
#> |    U|               |     12.92 |    -6.757 |     1574. |     219.3 |
#> |.....................|     1.256 |     1.953 |     2.669 |...........|
#> |    X|               |     12.92 |    -6.757 |     1574. |     219.3 |
#> |.....................|     1.256 |     1.953 |     2.669 |...........|
#> |   30|     116.80955 |   -0.9788 |   -0.7918 |    0.9996 |   -0.7189 |
#> |.....................|   -0.9936 |   -0.9844 |   -0.9780 |...........|
#> |    U|               |     12.79 |    -6.755 |     1574. |     218.6 |
#> |.....................|     1.256 |     1.948 |     2.670 |...........|
#> |    X|               |     12.79 |    -6.755 |     1574. |     218.6 |
#> |.....................|     1.256 |     1.948 |     2.670 |...........|
#> 
#> |    #| Function Val. |nlmixr2Pre_tka |nlmixr2Pre_tcl |nlmixr2Pre_tv |nlmixr2Pre_add.sd |
#> |.....................|        o1 |        o2 |        o3 |...........|
#> |   31|     116.81098 |   -0.9731 |   -0.7907 |    0.9996 |   -0.7197 |
#> |.....................|   -0.9934 |   -0.9865 |   -0.9907 |...........|
#> |    U|               |     12.86 |    -6.755 |     1574. |     218.5 |
#> |.....................|     1.256 |     1.947 |     2.665 |...........|
#> |    X|               |     12.86 |    -6.755 |     1574. |     218.5 |
#> |.....................|     1.256 |     1.947 |     2.665 |...........|
#> |   32|     116.81114 |   -0.9789 |   -0.7817 |    0.9995 |   -0.7191 |
#> |.....................|    -1.003 |   -0.9841 |   -0.9776 |...........|
#> |    U|               |     12.78 |    -6.753 |     1573. |     218.6 |
#> |.....................|     1.248 |     1.948 |     2.670 |...........|
#> |    X|               |     12.78 |    -6.753 |     1573. |     218.6 |
#> |.....................|     1.248 |     1.948 |     2.670 |...........|
#> |   33|     116.80809 |   -0.9728 |   -0.7893 |    0.9996 |   -0.7179 |
#> |.....................|   -0.9949 |   -0.9798 |   -0.9664 |...........|
#> |    U|               |     12.86 |    -6.755 |     1574. |     218.9 |
#> |.....................|     1.255 |     1.950 |     2.674 |...........|
#> |    X|               |     12.86 |    -6.755 |     1574. |     218.9 |
#> |.....................|     1.255 |     1.950 |     2.674 |...........|
#> |   34|     116.80751 |   -0.9703 |   -0.7923 |    0.9996 |   -0.7171 |
#> |.....................|   -0.9961 |   -0.9747 |   -0.9539 |...........|
#> |    U|               |     12.90 |    -6.755 |     1574. |     219.0 |
#> |.....................|     1.254 |     1.953 |     2.679 |...........|
#> |    X|               |     12.90 |    -6.755 |     1574. |     219.0 |
#> |.....................|     1.254 |     1.953 |     2.679 |...........|
#> |   35|     116.80686 |   -0.9767 |   -0.7906 |    0.9995 |   -0.7160 |
#> |.....................|   -0.9960 |   -0.9827 |   -0.9444 |...........|
#> |    U|               |     12.81 |    -6.755 |     1573. |     219.3 |
#> |.....................|     1.254 |     1.949 |     2.682 |...........|
#> |    X|               |     12.81 |    -6.755 |     1573. |     219.3 |
#> |.....................|     1.254 |     1.949 |     2.682 |...........|
#> |   36|     116.80663 |   -0.9760 |   -0.7867 |    0.9996 |   -0.7151 |
#> |.....................|   -0.9973 |   -0.9777 |   -0.9319 |...........|
#> |    U|               |     12.82 |    -6.754 |     1574. |     219.5 |
#> |.....................|     1.253 |     1.951 |     2.687 |...........|
#> |    X|               |     12.82 |    -6.754 |     1574. |     219.5 |
#> |.....................|     1.253 |     1.951 |     2.687 |...........|
#> |   37|     116.81021 |   -0.9693 |   -0.7962 |    0.9996 |   -0.7155 |
#> |.....................|   -0.9972 |   -0.9795 |   -0.9242 |...........|
#> |    U|               |     12.91 |    -6.756 |     1574. |     219.4 |
#> |.....................|     1.253 |     1.950 |     2.690 |...........|
#> |    X|               |     12.91 |    -6.756 |     1574. |     219.4 |
#> |.....................|     1.253 |     1.950 |     2.690 |...........|
#> |   38|     116.81103 |   -0.9760 |   -0.7968 |    0.9996 |   -0.7246 |
#> |.....................|   -0.9969 |   -0.9783 |   -0.9345 |...........|
#> |    U|               |     12.82 |    -6.756 |     1574. |     217.4 |
#> |.....................|     1.253 |     1.951 |     2.686 |...........|
#> |    X|               |     12.82 |    -6.756 |     1574. |     217.4 |
#> |.....................|     1.253 |     1.951 |     2.686 |...........|
#> |   39|     116.80795 |   -0.9883 |   -0.7855 |    0.9996 |   -0.7132 |
#> |.....................|   -0.9915 |   -0.9746 |   -0.9332 |...........|
#> |    U|               |     12.66 |    -6.754 |     1574. |     219.9 |
#> |.....................|     1.257 |     1.953 |     2.687 |...........|
#> |    X|               |     12.66 |    -6.754 |     1574. |     219.9 |
#> |.....................|     1.257 |     1.953 |     2.687 |...........|
#> |   40|     116.80790 |   -0.9761 |   -0.7763 |    0.9995 |   -0.7152 |
#> |.....................|   -0.9976 |   -0.9869 |   -0.9291 |...........|
#> |    U|               |     12.82 |    -6.753 |     1573. |     219.4 |
#> |.....................|     1.252 |     1.947 |     2.688 |...........|
#> |    X|               |     12.82 |    -6.753 |     1573. |     219.4 |
#> |.....................|     1.252 |     1.947 |     2.688 |...........|
#> 
#> |    #| Function Val. |nlmixr2Pre_tka |nlmixr2Pre_tcl |nlmixr2Pre_tv |nlmixr2Pre_add.sd |
#> |.....................|        o1 |        o2 |        o3 |...........|
#> |   41|     116.81127 |   -0.9866 |   -0.7907 |    0.9996 |   -0.7119 |
#> |.....................|    -1.003 |   -0.9724 |   -0.9318 |...........|
#> |    U|               |     12.69 |    -6.755 |     1574. |     220.2 |
#> |.....................|     1.248 |     1.954 |     2.687 |...........|
#> |    X|               |     12.69 |    -6.755 |     1574. |     220.2 |
#> |.....................|     1.248 |     1.954 |     2.687 |...........|
#> |   42|     116.80369 |   -0.9759 |   -0.7846 |    0.9995 |   -0.7162 |
#> |.....................|   -0.9910 |   -0.9755 |   -0.9326 |...........|
#> |    U|               |     12.82 |    -6.754 |     1573. |     219.2 |
#> |.....................|     1.258 |     1.952 |     2.687 |...........|
#> |    X|               |     12.82 |    -6.754 |     1573. |     219.2 |
#> |.....................|     1.258 |     1.952 |     2.687 |...........|
#> |   43|     116.81446 |   -0.9683 |   -0.7797 |    0.9994 |   -0.7212 |
#> |.....................|   -0.9820 |   -0.9719 |   -0.9324 |...........|
#> |    U|               |     12.92 |    -6.753 |     1573. |     218.1 |
#> |.....................|     1.265 |     1.954 |     2.687 |...........|
#> |    X|               |     12.92 |    -6.753 |     1573. |     218.1 |
#> |.....................|     1.265 |     1.954 |     2.687 |...........|
#> |   44|     116.80795 |   -0.9755 |   -0.7850 |    0.9995 |   -0.7158 |
#> |.....................|   -0.9894 |   -0.9744 |   -0.9266 |...........|
#> |    U|               |     12.83 |    -6.754 |     1573. |     219.3 |
#> |.....................|     1.259 |     1.953 |     2.689 |...........|
#> |    X|               |     12.83 |    -6.754 |     1573. |     219.3 |
#> |.....................|     1.259 |     1.953 |     2.689 |...........|
#> |   45|     116.80700 |   -0.9756 |   -0.7821 |    0.9997 |   -0.7168 |
#> |.....................|   -0.9952 |   -0.9714 |   -0.9356 |...........|
#> |    U|               |     12.83 |    -6.753 |     1574. |     219.1 |
#> |.....................|     1.254 |     1.955 |     2.686 |...........|
#> |    X|               |     12.83 |    -6.753 |     1574. |     219.1 |
#> |.....................|     1.254 |     1.955 |     2.686 |...........|
#> |   46|     116.88253 |   -0.9765 |   -0.7844 |    0.9962 |   -0.7173 |
#> |.....................|   -0.9908 |   -0.9754 |   -0.9326 |...........|
#> |    U|               |     12.82 |    -6.754 |     1568. |     219.0 |
#> |.....................|     1.258 |     1.952 |     2.687 |...........|
#> |    X|               |     12.82 |    -6.754 |     1568. |     219.0 |
#> |.....................|     1.258 |     1.952 |     2.687 |...........|
#> |   47|     116.80613 |   -0.9756 |   -0.7855 |    0.9999 |   -0.7143 |
#> |.....................|   -0.9904 |   -0.9776 |   -0.9344 |...........|
#> |    U|               |     12.83 |    -6.754 |     1574. |     219.6 |
#> |.....................|     1.258 |     1.951 |     2.686 |...........|
#> |    X|               |     12.83 |    -6.754 |     1574. |     219.6 |
#> |.....................|     1.258 |     1.951 |     2.686 |...........|
#> |   48|     116.80850 |   -0.9766 |   -0.7834 |    0.9995 |   -0.7163 |
#> |.....................|   -0.9904 |   -0.9751 |   -0.9334 |...........|
#> |    U|               |     12.81 |    -6.754 |     1573. |     219.2 |
#> |.....................|     1.258 |     1.953 |     2.687 |...........|
#> |    X|               |     12.81 |    -6.754 |     1573. |     219.2 |
#> |.....................|     1.258 |     1.953 |     2.687 |...........|
#> |   49|     116.80869 |   -0.9755 |   -0.7853 |    0.9999 |   -0.7175 |
#> |.....................|   -0.9916 |   -0.9759 |   -0.9326 |...........|
#> |    U|               |     12.83 |    -6.754 |     1574. |     218.9 |
#> |.....................|     1.257 |     1.952 |     2.687 |...........|
#> |    X|               |     12.83 |    -6.754 |     1574. |     218.9 |
#> |.....................|     1.257 |     1.952 |     2.687 |...........|
#> |   50|     116.80810 |   -0.9761 |   -0.7853 |    0.9995 |   -0.7156 |
#> |.....................|   -0.9910 |   -0.9753 |   -0.9323 |...........|
#> |    U|               |     12.82 |    -6.754 |     1573. |     219.4 |
#> |.....................|     1.258 |     1.952 |     2.687 |...........|
#> |    X|               |     12.82 |    -6.754 |     1573. |     219.4 |
#> |.....................|     1.258 |     1.952 |     2.687 |...........|
#> 
#> |    #| Function Val. |nlmixr2Pre_tka |nlmixr2Pre_tcl |nlmixr2Pre_tv |nlmixr2Pre_add.sd |
#> |.....................|        o1 |        o2 |        o3 |...........|
#> |   51|     116.80809 |   -0.9754 |   -0.7840 |    0.9995 |   -0.7158 |
#> |.....................|   -0.9914 |   -0.9757 |   -0.9324 |...........|
#> |    U|               |     12.83 |    -6.754 |     1573. |     219.3 |
#> |.....................|     1.257 |     1.952 |     2.687 |...........|
#> |    X|               |     12.83 |    -6.754 |     1573. |     219.3 |
#> |.....................|     1.257 |     1.952 |     2.687 |...........|
#> |   52|     116.80803 |   -0.9757 |   -0.7849 |    0.9995 |   -0.7162 |
#> |.....................|   -0.9912 |   -0.9755 |   -0.9335 |...........|
#> |    U|               |     12.83 |    -6.754 |     1573. |     219.2 |
#> |.....................|     1.257 |     1.952 |     2.687 |...........|
#> |    X|               |     12.83 |    -6.754 |     1573. |     219.2 |
#> |.....................|     1.257 |     1.952 |     2.687 |...........|
#> |   53|     116.80827 |   -0.9763 |   -0.7846 |    0.9995 |   -0.7163 |
#> |.....................|   -0.9904 |   -0.9761 |   -0.9323 |...........|
#> |    U|               |     12.82 |    -6.754 |     1573. |     219.2 |
#> |.....................|     1.258 |     1.952 |     2.687 |...........|
#> |    X|               |     12.82 |    -6.754 |     1573. |     219.2 |
#> |.....................|     1.258 |     1.952 |     2.687 |...........|
#> |   54|     116.80736 |   -0.9765 |   -0.7849 |    0.9995 |   -0.7160 |
#> |.....................|   -0.9917 |   -0.9753 |   -0.9325 |...........|
#> |    U|               |     12.82 |    -6.754 |     1573. |     219.3 |
#> |.....................|     1.257 |     1.952 |     2.687 |...........|
#> |    X|               |     12.82 |    -6.754 |     1573. |     219.3 |
#> |.....................|     1.257 |     1.952 |     2.687 |...........|
#> |   55|     116.80777 |   -0.9759 |   -0.7845 |    0.9996 |   -0.7165 |
#> |.....................|   -0.9909 |   -0.9746 |   -0.9323 |...........|
#> |    U|               |     12.82 |    -6.754 |     1574. |     219.2 |
#> |.....................|     1.258 |     1.953 |     2.687 |...........|
#> |    X|               |     12.82 |    -6.754 |     1574. |     219.2 |
#> |.....................|     1.258 |     1.953 |     2.687 |...........|
#> |   56|     116.80815 |   -0.9760 |   -0.7841 |    0.9995 |   -0.7161 |
#> |.....................|   -0.9914 |   -0.9762 |   -0.9324 |...........|
#> |    U|               |     12.82 |    -6.754 |     1573. |     219.2 |
#> |.....................|     1.257 |     1.952 |     2.687 |...........|
#> |    X|               |     12.82 |    -6.754 |     1573. |     219.2 |
#> |.....................|     1.257 |     1.952 |     2.687 |...........|
#> |   57|     116.80914 |   -0.9754 |   -0.7845 |    0.9992 |   -0.7158 |
#> |.....................|   -0.9903 |   -0.9755 |   -0.9325 |...........|
#> |    U|               |     12.83 |    -6.754 |     1573. |     219.3 |
#> |.....................|     1.258 |     1.952 |     2.687 |...........|
#> |    X|               |     12.83 |    -6.754 |     1573. |     219.3 |
#> |.....................|     1.258 |     1.952 |     2.687 |...........|
#> |   58|     116.80812 |   -0.9750 |   -0.7845 |    0.9995 |   -0.7164 |
#> |.....................|   -0.9910 |   -0.9756 |   -0.9325 |...........|
#> |    U|               |     12.84 |    -6.754 |     1573. |     219.2 |
#> |.....................|     1.258 |     1.952 |     2.687 |...........|
#> |    X|               |     12.84 |    -6.754 |     1573. |     219.2 |
#> |.....................|     1.258 |     1.952 |     2.687 |...........|
#> |   59|     116.80832 |   -0.9765 |   -0.7844 |    0.9999 |   -0.7158 |
#> |.....................|   -0.9909 |   -0.9757 |   -0.9331 |...........|
#> |    U|               |     12.82 |    -6.754 |     1574. |     219.3 |
#> |.....................|     1.258 |     1.952 |     2.687 |...........|
#> |    X|               |     12.82 |    -6.754 |     1574. |     219.3 |
#> |.....................|     1.258 |     1.952 |     2.687 |...........|
#> |   60|     116.80823 |   -0.9759 |   -0.7846 |    0.9995 |   -0.7162 |
#> |.....................|   -0.9910 |   -0.9755 |   -0.9326 |...........|
#> |    U|               |     12.82 |    -6.754 |     1573. |     219.2 |
#> |.....................|     1.258 |     1.952 |     2.687 |...........|
#> |    X|               |     12.82 |    -6.754 |     1573. |     219.2 |
#> |.....................|     1.258 |     1.952 |     2.687 |...........|
#> calculating covariance matrix
#> [====|====|====|====|====|====|====|====|====|====] 0:00:00 
#> done
#> → loading into symengine environment...
#> → pruning branches (`if`/`else`) of full model...
#> ✔ done
#> [====|====|====|====|====|====|====|====|====|====] 0:00:00
#> → calculate sensitivities
#> [====|====|====|====|====|====|====|====|====|====] 0:00:00
#> → calculate ∂(f)/∂(η)
#> [====|====|====|====|====|====|====|====|====|====] 0:00:00
#> → finding duplicate expressions in inner model...
#> → finding duplicate expressions in EBE model...
#> → compiling inner model...
#> ✔ done
#> → finding duplicate expressions in FD model...
#> → compiling EBE model...
#> ✔ done
#> → compiling events FD model...
#> ✔ done
#> Updated original fit object fit
fit$covMethod
#> [1] "precondition"

preconditionFit() modifies the original fit object in-place: after the call, fit$cov, fit$parFixedDf, and fit$covMethod all reflect the preconditioned covariance. The function returns the preconditioned covariance matrix invisibly.

Controlling the amount of re-estimation

The estType argument determines how much of the model is re-estimated on the reparameterized problem:

estType What is re-estimated When to use
"full" (default) Outer and inner iterations (theta, ETA) When you suspect the original estimates may have converged to a local minimum
"posthoc" Inner iterations only (ETA, given theta) When you trust the theta estimates but want a better covariance
"none" Nothing – only the covariance matrix is re-computed Fastest; good for a quick diagnostic check 
# Shown for reference -- each call re-estimates and modifies `fit` in place, so
# run whichever one you want against a freshly fitted model.
# Only recompute the covariance matrix (fastest)
preconditionFit(fit, estType = "none")

# Fix theta, re-estimate ETAs, then compute covariance
preconditionFit(fit, estType = "posthoc")

# Full re-estimation on the reparameterized model (default)
preconditionFit(fit, estType = "full")

Retrying until convergence: ntry

The inner loop of preconditionFit() iterates the preconditioning until the reparameterized problem achieves a "r,s" covariance (the most reliable type). If that target is not reached within ntry attempts the function stops with an error. The default is ntry = 10.

# Allow up to 20 attempts before giving up
preconditionFit(fit, ntry = 20L)

If preconditionFit() fails even with more tries, the R matrix itself may be too poorly determined for preconditioning to help. In that case inspect the model for identifiability problems or consider likelihood profiling (profile(fit)) instead of Wald-based confidence intervals.

Switching between covariance estimates

preconditionFit() stores the preconditioned covariance alongside any previously computed covariances in fit$covList. You can inspect what is available and switch between them with setCov():

# See which covariance estimates are stored
names(fit$covList)
#> [1] "r,s"
# Switch back to the standard r,s covariance
setCov(fit, "r,s")

# Switch to the preconditioned covariance
setCov(fit, "precondition")

After setCov() the fit object is updated in-place and the displayed parameter table (fit$parFixedDf) reflects the selected covariance.

Worked example: comparing SEs before and after preconditioning 

library(nlmixr2extra)

# a second, untouched fit: `fit` above was already preconditioned in place
fitCompare := nlmixr2(oneCompartment, data = nlmixr2data::theo_sd,
                      est = "focei", control = list(print = 0))

# Record the original parameter table
dfBefore <- fitCompare$parFixedDf
cat("Covariance method before:", fitCompare$covMethod, "\n")
#> Covariance method before: r,s

# Apply preconditioning (only recompute covariance, do not re-estimate)
invisible(preconditionFit(fitCompare, estType = "none"))
#> calculating covariance matrix
#> [====|====|====|====|====|====|====|====|====|====] 0:00:00
dfAfter <- fitCompare$parFixedDf
cat("Covariance method after:", fitCompare$covMethod, "\n")
#> Covariance method after: precondition

# Compare standard errors
cbind(
  SE_before = dfBefore$SE,
  SE_after  = dfAfter$SE,
  row.names = rownames(dfBefore)
)
#>        SE_before            SE_after              row.names
#> tka    "0.23191882512431"   "0.0216417252282623"  "tka"    
#> tcl    "0.169047370259566"  "0.009228606428201"   "tcl"    
#> tv     "0.0405121558563634" "0.00923909311815786" "tv"     
#> add.sd "0.0730247302042821" "0.0820970850815736"  "add.sd"

The point estimates (Estimate, Back-transformed) and the random-effects summaries (BSV(CV%), Shrink(SD)%) are identical before and after – only the covariance-derived quantities (SE, %RSE, confidence intervals) change.

When to use preconditionFit()

Use preconditionFit() when:

  • fit$covMethod is not "r,s" after a FOCEI fit
  • Standard errors look implausibly large or contain NaN
  • You want a publication-quality covariance estimate and are willing to spend extra computation time

It is not needed when FOCEI already produces a "r,s" covariance and the SEs look reasonable. For models where identifiability is in doubt (very large %RSE for multiple parameters simultaneously), consider likelihood profiling rather than trying to stabilize a structurally unreliable covariance.

Requirements

preconditionFit() requires:

  • A fit produced by FOCEI (or a method that stores an R matrix in fit$R). SAEM fits do not store an R matrix by default; call fit <- nlmixr2(model, data, est = "focei", ...) first, or use getVarCov(saemFit) to trigger covariance computation.
  • The nlmixr2extra package to be loaded.