nlmixr2 nlminb defaults
Usage
nlminbControl(
eval.max = 200,
iter.max = 150,
trace = 0,
abs.tol = 0,
rel.tol = 1e-10,
x.tol = 1.5e-08,
xf.tol = 2.2e-14,
step.min = 1,
step.max = 1,
sing.tol = rel.tol,
scale = 1,
scale.init = NULL,
diff.g = NULL,
rxControl = NULL,
optExpression = TRUE,
sumProd = FALSE,
literalFix = TRUE,
returnNlminb = FALSE,
solveType = c("hessian", "grad", "fun"),
stickyRecalcN = 4,
maxOdeRecalc = 5,
odeRecalcFactor = 10^(0.5),
eventType = c("central", "forward"),
shiErr = (.Machine$double.eps)^(1/3),
shi21maxFD = 20L,
optimHessType = c("central", "forward"),
hessErr = (.Machine$double.eps)^(1/3),
shi21maxHess = 20L,
useColor = crayon::has_color(),
printNcol = floor((getOption("width") - 23)/12),
print = 1L,
normType = c("rescale2", "mean", "rescale", "std", "len", "constant"),
scaleType = c("nlmixr2", "norm", "mult", "multAdd"),
scaleCmax = 1e+05,
scaleCmin = 1e-05,
scaleC = NULL,
scaleTo = 1,
gradTo = 1,
addProp = c("combined2", "combined1"),
calcTables = TRUE,
compress = TRUE,
covMethod = c("r", "nlminb", ""),
adjObf = TRUE,
ci = 0.95,
sigdig = 4,
sigdigTable = NULL,
...
)Arguments
- eval.max
Maximum number of evaluations of the objective function allowed. Defaults to 200.
- iter.max
Maximum number of iterations allowed. Defaults to 150.
- trace
The value of the objective function and the parameters is printed every trace'th iteration. When 0 no trace information is to be printed
- abs.tol
Absolute tolerance. Defaults to 0 so the absolute convergence test is not used. If the objective function is known to be non-negative, the previous default of `1e-20` would be more appropriate
- rel.tol
Relative tolerance. Defaults to `1e-10`.
- x.tol
X tolerance. Defaults to `1.5e-8`.
- xf.tol
false convergence tolerance. Defaults to `2.2e-14`.
- step.min
Minimum step size. Default to ‘1.’.
- step.max
Maximum step size. Default to ‘1.’.
- sing.tol
singular convergence tolerance; defaults to `rel.tol;.
- scale
See PORT documentation (or leave alone).
- scale.init
... probably need to check PORT documentation
- diff.g
an estimated bound on the relative error in the objective function value
- rxControl
`rxode2` ODE solving options during fitting, created with `rxControl()`
- optExpression
Optimize the rxode2 expression to speed up calculation. By default this is turned on.
- sumProd
Is a boolean indicating if the model should change multiplication to high precision multiplication and sums to high precision sums using the PreciseSums package. By default this is
FALSE.- literalFix
boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is `TRUE`.
- returnNlminb
logical; when TRUE this will return the nlminb result instead of the nlmixr2 fit object
- solveType
tells if `nlm` will use nlmixr2's analytical gradients when available (finite differences will be used for event-related parameters like parameters controlling lag time, duration/rate of infusion, and modeled bioavailability). This can be:
- `"hessian"` which will use the analytical gradients to create a Hessian with finite differences.
- `"gradient"` which will use the gradient and let `nlm` calculate the finite difference hessian
- `"fun"` where nlm will calculate both the finite difference gradient and the finite difference Hessian
When using nlmixr2's finite differences, the "ideal" step size for either central or forward differences are optimized for with the Shi2021 method which may give more accurate derivatives
- stickyRecalcN
The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.
- maxOdeRecalc
Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.
- odeRecalcFactor
The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced
- eventType
Event gradient type for dosing events; Can be "central" or "forward"
- shiErr
This represents the epsilon when optimizing the ideal step size for numeric differentiation using the Shi2021 method
- shi21maxFD
The maximum number of steps for the optimization of the forward difference step size when using dosing events (lag time, modeled duration/rate and bioavailability)
- optimHessType
The hessian type for when calculating the individual hessian by numeric differences (in generalized log-likelihood estimation). The options are "central", and "forward". The central differences is what R's `optimHess()` uses and is the default for this method. (Though the "forward" is faster and still reasonable for most cases). The Shi21 cannot be changed for the Gill83 algorithm with the optimHess in a generalized likelihood problem.
- hessErr
This represents the epsilon when optimizing the Hessian step size using the Shi2021 method.
- shi21maxHess
Maximum number of times to optimize the best step size for the hessian calculation
- useColor
Boolean indicating if focei can use ASCII color codes
- printNcol
Number of columns to printout before wrapping parameter estimates/gradient
Integer representing when the outer step is printed. When this is 0 or do not print the iterations. 1 is print every function evaluation (default), 5 is print every 5 evaluations.
- normType
This is the type of parameter normalization/scaling used to get the scaled initial values for nlmixr2. These are used with
scaleTypeof.With the exception of
rescale2, these come from Feature Scaling. Therescale2The rescaling is the same type described in the OptdesX software manual.In general, all all scaling formula can be described by:
$$v_{scaled}$$ = ($$v_{unscaled}-C_{1}$$)/$$C_{2}$$
Where
The other data normalization approaches follow the following formula
$$v_{scaled}$$ = ($$v_{unscaled}-C_{1}$$)/$$C_{2}$$
rescale2This scales all parameters from (-1 to 1). The relative differences between the parameters are preserved with this approach and the constants are:$$C_{1}$$ = (max(all unscaled values)+min(all unscaled values))/2
$$C_{2}$$ = (max(all unscaled values) - min(all unscaled values))/2
rescaleor min-max normalization. This rescales all parameters from (0 to 1). As in therescale2the relative differences are preserved. In this approach:$$C_{1}$$ = min(all unscaled values)
$$C_{2}$$ = max(all unscaled values) - min(all unscaled values)
meanor mean normalization. This rescales to center the parameters around the mean but the parameters are from 0 to 1. In this approach:$$C_{1}$$ = mean(all unscaled values)
$$C_{2}$$ = max(all unscaled values) - min(all unscaled values)
stdor standardization. This standardizes by the mean and standard deviation. In this approach:$$C_{1}$$ = mean(all unscaled values)
$$C_{2}$$ = sd(all unscaled values)
lenor unit length scaling. This scales the parameters to the unit length. For this approach we use the Euclidean length, that is:$$C_{1}$$ = 0
$$C_{2}$$ = $$\sqrt(v_1^2 + v_2^2 + \cdots + v_n^2)$$
constantwhich does not perform data normalization. That is$$C_{1}$$ = 0
$$C_{2}$$ = 1
- scaleType
The scaling scheme for nlmixr2. The supported types are:
nlmixr2In this approach the scaling is performed by the following equation:$$v_{scaled}$$ = ($$v_{current} - v_{init}$$)*scaleC[i] + scaleTo
The
scaleToparameter is specified by thenormType, and the scales are specified byscaleC.normThis approach uses the simple scaling provided by thenormTypeargument.multThis approach does not use the data normalization provided bynormType, but rather uses multiplicative scaling to a constant provided by thescaleToargument.In this case:
$$v_{scaled}$$ = $$v_{current}$$/$$v_{init}$$*scaleTo
multAddThis approach changes the scaling based on the parameter being specified. If a parameter is defined in an exponential block (ie exp(theta)), then it is scaled on a linearly, that is:$$v_{scaled}$$ = ($$v_{current}-v_{init}$$) + scaleTo
Otherwise the parameter is scaled multiplicatively.
$$v_{scaled}$$ = $$v_{current}$$/$$v_{init}$$*scaleTo
- scaleCmax
Maximum value of the scaleC to prevent overflow.
- scaleCmin
Minimum value of the scaleC to prevent underflow.
- scaleC
The scaling constant used with
scaleType=nlmixr2. When not specified, it is based on the type of parameter that is estimated. The idea is to keep the derivatives similar on a log scale to have similar gradient sizes. Hence parameters like log(exp(theta)) would have a scaling factor of 1 and log(theta) would have a scaling factor of ini_value (to scale by 1/value; ie d/dt(log(ini_value)) = 1/ini_value or scaleC=ini_value)For parameters in an exponential (ie exp(theta)) or parameters specifying powers, boxCox or yeoJohnson transformations , this is 1.
For additive, proportional, lognormal error structures, these are given by 0.5*abs(initial_estimate)
Factorials are scaled by abs(1/digamma(initial_estimate+1))
parameters in a log scale (ie log(theta)) are transformed by log(abs(initial_estimate))*abs(initial_estimate)
These parameter scaling coefficients are chose to try to keep similar slopes among parameters. That is they all follow the slopes approximately on a log-scale.
While these are chosen in a logical manner, they may not always apply. You can specify each parameters scaling factor by this parameter if you wish.
- scaleTo
Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.
- gradTo
this is the factor that the gradient is scaled to before optimizing. This only works with scaleType="nlmixr2".
- addProp
specifies the type of additive plus proportional errors, the one where standard deviations add (combined1) or the type where the variances add (combined2).
The combined1 error type can be described by the following equation:
$$y = f + (a + b\times f^c) \times \varepsilon$$
The combined2 error model can be described by the following equation:
$$y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon$$
Where:
- y represents the observed value
- f represents the predicted value
- a is the additive standard deviation
- b is the proportional/power standard deviation
- c is the power exponent (in the proportional case c=1)
- calcTables
This boolean is to determine if the foceiFit will calculate tables. By default this is
TRUE- compress
Should the object have compressed items
- covMethod
Method for calculating covariance. In this discussion, R is the Hessian matrix of the objective function. The S matrix is the sum of individual gradient cross-product (evaluated at the individual empirical Bayes estimates).
"
r,s" Uses the sandwich matrix to calculate the covariance, that is:solve(R) %*% S %*% solve(R)"
r" Uses the Hessian matrix to calculate the covariance as2 %*% solve(R)"
s" Uses the cross-product matrix to calculate the covariance as4 %*% solve(S)"" Does not calculate the covariance step.
- adjObf
is a boolean to indicate if the objective function should be adjusted to be closer to NONMEM's default objective function. By default this is
TRUE- ci
Confidence level for some tables. By default this is 0.95 or 95% confidence.
- sigdig
Optimization significant digits. This controls:
The tolerance of the inner and outer optimization is
10^-sigdigThe tolerance of the ODE solvers is
0.5*10^(-sigdig-2); For the sensitivity equations and steady-state solutions the default is0.5*10^(-sigdig-1.5)(sensitivity changes only applicable for liblsoda)The tolerance of the boundary check is
5 * 10 ^ (-sigdig + 1)
- sigdigTable
Significant digits in the final output table. If not specified, then it matches the significant digits in the `sigdig` optimization algorithm. If `sigdig` is NULL, use 3.
- ...
Further arguments to be supplied to
objective.
Examples
# \donttest{
# A logit regression example with emax model
dsn <- data.frame(i=1:1000)
dsn$time <- exp(rnorm(1000))
dsn$DV=rbinom(1000,1,exp(-1+dsn$time)/(1+exp(-1+dsn$time)))
mod <- function() {
ini({
E0 <- 0.5
Em <- 0.5
E50 <- 2
g <- fix(2)
})
model({
v <- E0+Em*time^g/(E50^g+time^g)
ll(bin) ~ DV * v - log(1 + exp(v))
})
}
fit2 <- nlmixr(mod, dsn, est="nlminb")
#>
#>
#>
#>
#> ℹ parameter labels from comments are typically ignored in non-interactive mode
#> ℹ Need to run with the source intact to parse comments
#> → loading into symengine environment...
#> → pruning branches (`if`/`else`) of population log-likelihood model...
#> ✔ done
#> → calculate jacobian
#> → calculate ∂(f)/∂(θ)
#> → finding duplicate expressions in nlm llik gradient...
#> → optimizing duplicate expressions in nlm llik gradient...
#> → finding duplicate expressions in nlm pred-only...
#> → optimizing duplicate expressions in nlm pred-only...
#>
#>
#>
#>
#> → calculating covariance
#> ✔ done
#> → loading into symengine environment...
#> → pruning branches (`if`/`else`) of full model...
#> ✔ done
#> → finding duplicate expressions in EBE model...
#> → optimizing duplicate expressions in EBE model...
#> → compiling EBE model...
#>
#>
#> ✔ done
#> → Calculating residuals/tables
#> ✔ done
#> → compress origData in nlmixr2 object, save 9120
#> → compress parHistData in nlmixr2 object, save 2784
print(fit2)
#> ── nlmixr² log-likelihood nlminb ──
#>
#> OBJF AIC BIC Log-likelihood Condition#(Cov) Condition#(Cor)
#> lPop -702.1913 1141.686 1156.409 -567.8429 1061.334 92.29859
#>
#> ── Time (sec $time): ──
#>
#> setup table compress other
#> elapsed 0.002813 0.046 0.011 2.325187
#>
#> ── ($parFixed or $parFixedDf): ──
#>
#> Est. SE %RSE Back-transformed(95%CI) BSV(SD) Shrink(SD)%
#> E0 -0.5562 0.2205 39.65 -0.5562 (-0.9884, -0.124)
#> Em 6.824 4.108 60.19 6.824 (-1.227, 14.88)
#> E50 3.527 1.754 49.71 3.527 (0.09045, 6.964)
#> g 2 FIXED FIXED 2
#>
#> Covariance Type ($covMethod): r (nlminb)
#> Censoring ($censInformation): No censoring
#> Minimization message ($message):
#> relative convergence (4)
#>
#> ── Fit Data (object is a modified tibble): ──
#> # A tibble: 1,000 × 5
#> ID TIME DV IPRED v
#> <fct> <dbl> <dbl> <dbl> <dbl>
#> 1 1 0.0165 0 -0.453 -0.556
#> 2 1 0.0372 1 -1.01 -0.555
#> 3 1 0.0882 0 -0.455 -0.552
#> # ℹ 997 more rows
# you can also get the nlm output with fit2$nlminb
fit2$nlminb
#> $par
#> E0 Em E50
#> -0.5562158 6.8243063 3.5274540
#>
#> $objective
#> [1] 567.8429
#>
#> $convergence
#> [1] 0
#>
#> $iterations
#> [1] 9
#>
#> $evaluations
#> function gradient
#> 15 10
#>
#> $message
#> [1] "relative convergence (4)"
#>
#> $scaleC
#> [1] 0.003025658 0.039166286 0.035501967
#>
#> $parHistData
#> iter type objf E0 Em E50
#> 1 1 Scaled 664.3020 -1.000000e+00 -1.000000e+00 1.000000e+00
#> 2 1 Unscaled 664.3020 5.000000e-01 5.000000e-01 2.000000e+00
#> 3 1 Back-Transformed 664.3020 5.000000e-01 5.000000e-01 2.000000e+00
#> 4 2 Scaled 663.2590 -1.192767e+00 -1.054198e-01 1.014293e+00
#> 5 2 Unscaled 663.2590 4.994168e-01 5.350374e-01 2.000507e+00
#> 6 2 Back-Transformed 663.2590 4.994168e-01 5.350374e-01 2.000507e+00
#> 7 3 Scaled 660.3552 -1.947459e+00 2.548835e+00 1.142916e+00
#> 8 3 Unscaled 660.3552 4.971333e-01 6.389947e-01 2.005074e+00
#> 9 3 Back-Transformed 660.3552 4.971333e-01 6.389947e-01 2.005074e+00
#> 10 4 Scaled 651.4533 -8.468400e+00 1.158379e+01 3.193471e+00
#> 11 4 Unscaled 651.4533 4.774032e-01 9.928603e-01 2.077873e+00
#> 12 4 Back-Transformed 651.4533 4.774032e-01 9.928603e-01 2.077873e+00
#> 13 5 Scaled 638.6847 -3.211393e+01 2.103046e+01 9.325660e+00
#> 14 5 Unscaled 638.6847 4.058599e-01 1.362851e+00 2.295577e+00
#> 15 5 Back-Transformed 638.6847 4.058599e-01 1.362851e+00 2.295577e+00
#> 16 6 Scaled 618.4630 -8.842653e+01 3.196009e+01 1.527454e+01
#> 17 6 Unscaled 618.4630 2.354772e-01 1.790924e+00 2.506774e+00
#> 18 6 Back-Transformed 618.4630 2.354772e-01 1.790924e+00 2.506774e+00
#> 19 7 Scaled 586.6264 -2.402661e+02 5.426643e+01 1.488642e+01
#> 20 7 Unscaled 586.6264 -2.239373e-01 2.664581e+00 2.492995e+00
#> 21 7 Back-Transformed 586.6264 -2.239373e-01 2.664581e+00 2.492995e+00
#> 22 8 Scaled 577.6845 -4.091671e+02 9.062513e+01 -6.891088e+00
#> 23 8 Unscaled 577.6845 -7.349741e-01 4.088616e+00 1.719851e+00
#> 24 8 Back-Transformed 577.6845 -7.349741e-01 4.088616e+00 1.719851e+00
#> 25 9 Scaled 570.2958 -4.090877e+02 1.125863e+02 1.006903e+01
#> 26 9 Unscaled 570.2958 -7.347337e-01 4.948755e+00 2.321969e+00
#> 27 9 Back-Transformed 570.2958 -7.347337e-01 4.948755e+00 2.321969e+00
#> 28 10 Scaled 568.5426 -3.859555e+02 1.260802e+02 2.233961e+01
#> 29 10 Unscaled 568.5426 -6.647436e-01 5.477258e+00 2.757598e+00
#> 30 10 Back-Transformed 568.5426 -6.647436e-01 5.477258e+00 2.757598e+00
#> 31 11 Scaled 567.9630 -3.629940e+02 1.409506e+02 3.333805e+01
#> 32 11 Unscaled 567.9630 -5.952699e-01 6.059680e+00 3.148064e+00
#> 33 11 Back-Transformed 567.9630 -5.952699e-01 6.059680e+00 3.148064e+00
#> 34 12 Scaled 567.8483 -3.512389e+02 1.552172e+02 4.165856e+01
#> 35 12 Unscaled 567.8483 -5.597032e-01 6.618446e+00 3.443459e+00
#> 36 12 Back-Transformed 567.8483 -5.597032e-01 6.618446e+00 3.443459e+00
#> 37 13 Scaled 567.8429 -3.502120e+02 1.599472e+02 4.380057e+01
#> 38 13 Unscaled 567.8429 -5.565960e-01 6.803705e+00 3.519505e+00
#> 39 13 Back-Transformed 567.8429 -5.565960e-01 6.803705e+00 3.519505e+00
#> 40 14 Scaled 567.8429 -3.500894e+02 1.604627e+02 4.401979e+01
#> 41 14 Unscaled 567.8429 -5.562250e-01 6.823896e+00 3.527287e+00
#> 42 14 Back-Transformed 567.8429 -5.562250e-01 6.823896e+00 3.527287e+00
#> 43 15 Scaled 567.8429 -3.500863e+02 1.604732e+02 4.402449e+01
#> 44 15 Unscaled 567.8429 -5.562158e-01 6.824306e+00 3.527454e+00
#> 45 15 Back-Transformed 567.8429 -5.562158e-01 6.824306e+00 3.527454e+00
#> 46 16 Scaled 567.8429 -3.500863e+02 1.604732e+02 4.402449e+01
#> 47 16 Unscaled 567.8429 -5.562158e-01 6.824306e+00 3.527454e+00
#> 48 16 Back-Transformed 567.8429 -5.562158e-01 6.824306e+00 3.527454e+00
#> 49 1 Forward Sensitivity NA 2.287292e-01 -1.139587e+00 -1.007877e-02
#> 50 7 Forward Sensitivity NA 3.365644e-02 -6.062339e-01 2.972991e-01
#> 51 8 Forward Sensitivity NA 9.613539e-02 4.695186e-01 -1.330428e+00
#> 52 9 Forward Sensitivity NA 1.036280e-02 1.249100e-01 -3.703666e-01
#> 53 10 Forward Sensitivity NA -7.442000e-03 2.296292e-02 -9.575293e-02
#> 54 11 Forward Sensitivity NA -2.982629e-03 9.205289e-04 -2.239961e-02
#> 55 12 Forward Sensitivity NA 2.930256e-04 -1.823928e-03 -8.079844e-04
#> 56 13 Forward Sensitivity NA -5.830956e-05 -3.581104e-04 3.999487e-04
#> 57 14 Forward Sensitivity NA -7.809605e-07 -4.798043e-06 2.546606e-06
#> 58 15 Forward Sensitivity NA 5.119659e-10 9.768064e-10 -8.692294e-08
#>
#> $par.scaled
#> E0 Em E50
#> -350.08631 160.47322 44.02449
#>
#> $hessian
#> E0 Em E50
#> E0 0.001806574 0.002166854 -0.005847333
#> Em 0.002166854 0.006467726 -0.014832491
#> E50 -0.005847333 -0.014832491 0.036368424
#>
#> $covMethod
#> [1] "r (nlminb)"
#>
#> $cov.scaled
#> E0 Em E50
#> E0 5312.467 2766.670 1982.499
#> Em 2766.670 11000.029 4931.076
#> E50 1982.499 4931.076 2439.822
#>
#> $cov
#> E0 Em E50
#> E0 0.04863354 0.3278608 0.2129537
#> Em 0.32786081 16.8740213 6.8565634
#> E50 0.21295371 6.8565634 3.0751260
#>
#> $r
#> E0 Em E50
#> E0 0.000903287 0.001083427 -0.002923667
#> Em 0.001083427 0.003233863 -0.007416245
#> E50 -0.002923667 -0.007416245 0.018184212
#>
# }