Package {nlmixr2est}

Either an integer print-frequency or an 'iterPrintControl' object.

Scalar '*Control()' arguments forwarded to [iterPrintControl()] only when 'print' is a scalar.

Optional pre-built [iterPrintControl()] object. Wins over 'print' and the other scalars when supplied.

character vector of the package to add

number of eta parameters in the model

number of adaptive quadrature points to use

A matrix of quadrature points, one row per point.

A matrix of quadrature weights, one row per point.

The number of quadrature points.

The number of eta parameters.

The number of adaptive quadrature points.

A logical indicating if the first point is zero.

The fitted model object from which to retrieve the simulation model.

R expression

When TRUE return a list with list(object,warnings) instead of issuing the warnings. Otherwise, when FALSE issue the warnings and return the object.

When TRUE, errors raised during evaluation of expr are recorded in addition to warnings. A calling handler captures every error message as it is signalled, then lets the condition continue to propagate so that inner try()/tryCatch() blocks in expr keep working as usual. An outer tryCatch() catches errors that escape all inner handling, so the call always returns instead of stopping. If expr evaluated to a result (i.e. no error escaped), the recorded errors were caught by inner handlers and are discarded. If an error did escape, every message observed along the error chain (including follow-up errors raised by on.exit handlers, see issue 607) is returned in the error element of the result list (when lst = TRUE) or re-raised joined by newlines (when lst = FALSE). When FALSE (the default) errors propagate normally and es is always NULL. This is used by nlmixr2Est0() so that all errors from a failed estimation run are reported together rather than only the last one.

The standard object used for comparison. (for example 'foceiControl()')

The new object to be compared against the standard. This would be what the user supplide like 'foceiControl(outerOpt="bobyqa")'

A character vector of element names to be ignored during the comparison. Default is an empty character vector. These are for internal items of the list that flag certain properties like if the 'rxControl()' was generated by the 'foceiControl()' procedure or not.

A default object used for comparison; This is the estimation control procedure. It should have a class matching the function that created it.

The object to be deparsed into a language exression

A vector of indices indicating which elements are different and need to be deparsed. This likely comes from '.deparseDifferent()'

A string representing the variable name to be assigned in the deparsed expression.

An optional custom function to handle specific elements during deparsing. Default is NULL. This handles things that are specific to an estimation control and is used by functions like 'rxUiDeparse.saemControl()'

rxode2 User interface function

The names of the zero etas in the model

Input dataset

focei environment where focei family is run

rxode2 ui

is the rxode2 control that is used to translate to the modeling dataset

model text (normalized rxode2 model, e.g. from a prune)

when 'TRUE', promote 'linCmt()' to the sensitivity-based solved system

when 'TRUE', change the printed message to indicate the full model is being loaded

Covariance of scaled parameters

The final scaled parameter value

environment for fit output that needs to be adjusted

string for the fit output

dispatch environment (provides 'ui' and 'control')

the method's '*Control()' constructor (e.g. 'nlmControl')

the control object's S3 class (e.g. '"nlmControl"')

dispatch environment (provides 'ui', 'control', 'data', 'table')

estimation-method string; also the slot the raw fit is stored under (e.g. '"nlm"' -> '.ret[["nlm"]]')

'function(ui, dataSav)' running the optimizer

'function(fit, ui)' returning the full theta vector

'function(env)' translating the control to a focei-style control for output assembly

rxode2 control flag name that short-circuits and returns the raw optimizer result (e.g. '"returnNlm"')

optional 'function(fit)' returning the raw objective; when 'NULL' the driver does not set '$objective' (a 'postSetup' closure did)

'function(fit)' returning the '$message' (default 'fit$message')

when TRUE, re-emit the warnings collected from 'fitModel' via 'warning()' (nlm does this; the others do not)

'$extra' print string, or a 'function(control)' returning it

when TRUE, run '.nlmFamilyAdjustOutput()'

optional 'function(ret, ui, fitList)' returning a modified 'ret', run right after the raw fit is stored and before '.nlmFamilyAdjustOutput()' (for methods that set cov/covMethod/objective with custom values)

nlm environment

output list

parameter name of final estimate in output

Print the final line when print is nonzero

boolean indicating a hessian should be used/calculated for covariance

A named vector of initial estimates to setup the nonlinear model solving environment. The names of the parameter should match the names of the model to run (not 'THETA[#]' as required in the 'modelInfo' argument)

rxode2 ui model

rxode2 compatible data for solving/setting up

A list with 'predOnly' (predictions-only model in terms of 'THETA[#]'/'DV'), 'eventTheta' (0/1 per THETA flagging event-related parameters that need Shi2021 finite differences, same length as 'par'), and 'thetaGrad' (needed when solveType != 1; gives value/gradient per THETA). See 'ui$nlmSensModel' or 'ui$nlmRxModel' for examples.

control structure; required: 'rxControl', 'stickyRecalcN', 'maxOdeRecalc', 'odeRecalcFactor'. Optional: 'solveType', 'eventType', 'shi21maxFD', 'shiErr', 'optimHessType', 'shi21maxHess', 'hessErr', 'useColor', 'printNcol', 'print', 'normType', 'scaleType', 'scaleCmin', 'scaleCmax', 'scaleTo', 'scaleC', 'gradTo' (default 0 if missing).

lower bounds, will be scaled if present

upper bounds, will be scaled if present

Names to translate

rxode2 ui

rxode2 ui

estimation method (all methods are shown by 'nlmixr2AllEst()'). Methods can be added for other tools

nlmixr data

The estimation control object. These are expected to be different for each type of estimation method

rxode2 ui

estimation method (all methods are shown by 'nlmixr2AllEst()'). Methods can be added for other tools

nlmixr data

The estimation control object. These are expected to be different for each type of estimation method

Data to fix

String or null for assigning a nlmixr object name

Parameters that will be estimated

Parameters that will be estimated

The patient identifiers for the estimated data.

Parameters that will be estimated

dependent variable

Other parameters fed to prediction function

Parameter for estimate

Parameters that will be estimated

model function/object

estimation method (all methods are shown by 'nlmixr2AllEst()'). Methods can be added for other tools

nlmixr data

The estimation control object. These are expected to be different for each type of estimation method

rxode2 ui

estimation method (all methods are shown by 'nlmixr2AllEst()'). Methods can be added for other tools

nlmixr data

The estimation control object. These are expected to be different for each type of estimation method

rxode2 ui

estimation method (all methods are shown by 'nlmixr2AllEst()'). Methods can be added for other tools

nlmixr data

The estimation control object. These are expected to be different for each type of estimation method

rxode2 ui

estimation method (all methods are shown by 'nlmixr2AllEst()'). Methods can be added for other tools

nlmixr data

The estimation control object. These are expected to be different for each type of estimation method

rxode2 ui model

estimation method (all methods are shown by 'nlmixr2AllEst()'). Methods can be added for other tools

nlmixr data

The estimation control object. These are expected to be different for each type of estimation method

rxode2 ui model

estimation method (all methods are shown by 'nlmixr2AllEst()'). Methods can be added for other tools

nlmixr data

The estimation control object. These are expected to be different for each type of estimation method

Environment for the parsed model

The 'data.frame' of the current error

The transformation number for the current error

rxode2 ui

Do not look for covariates

Keep the mu-referenced etas

symengine environment (from '.loadSymengine()')

when 'TRUE' calculate the sensitivities with respect to 'THETA[#]'; otherwise with respect to 'ETA[#]'

the ui for the model

the estimation method

the data provided

the control object

The object that would be returned, without modification

nlmixr2 fit without WRES/CWRES

Boolean indicating if the focei objective function is added. If not the foce objective function is added.

Boolean indicating if the original fit object should be updated. By default this is true.

Environment that should be checked for object to update. By default this is the global environment.

nlmixr2 fit object

Boolean indicating if original object should be updated. By default this is TRUE.

'tableControl()' list of options

Other ignored parameters.

Environment that should be checked for object to update. By default this is the global environment.

nlmixr2 family of objects

Update the object (default FALSE)

Saved data from

Internal theta/eta parameters

a 'tableControl()' list of options

Character Vector of items to keep

Character Vector of items to drop or NULL

Environment to search for updating

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Number of Gauss-Hermite adaptive quadrature points. '0' disables AGQ; '1' is equivalent to Laplace. Cost grows quickly with ETAs: once the EBE is found, expect 'nAGQ^neta' (even 'nAGQ') or '(nAGQ^neta)-1' (odd 'nAGQ') additional evaluations per subject.

Parameters used in the default 'foceiControl()'

boolean, Interaction term for the model, in this case the default is 'TRUE'; For adaptive quadrature, with normal distribution the Hessian is calculated with the foce(i) approximation

The lower bound for adaptive quadrature log-likelihood. By default this is -Inf; in the original nlmixr's gnlmm it was -700.

The upper bound for adaptive quadrature log-likelihood. By default this is Inf; in the original nlmixr's gnlmm was 400.

Fit object

Fit object

Number of points for the quadratic approximation to the objective; must be in '[n+2, (n+1)(n+2)/2]'. Defaults to 'min(n*2, n+2)'.

Initial trust region radius (with 'rhoend', must satisfy '0 < rhoend < rhobeg'). Defaults to 'min(0.95, 0.2*max(abs(par)))'; adjusted upward if smaller than 'abs(upper-lower)/2'.

Final trust region radius. When 'NULL' (default) it is derived from 'sigdig' the way 'foceiControl()' does ('10^(-sigdig)'); otherwise the minqa '1e-6*rhobeg' default applies.

Controls amount of printing ('0'=none, '1'=start/end only, '2'=each new rho, '3'=every function evaluation, '>3'=every 'iprint' evaluations). Default '0'.

The maximum allowed number of function evaluations. If this is exceeded, the method will terminate.

return the bobyqa output instead of the nlmixr2 fit

The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.

Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.

The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced

When 'TRUE' (default), only subjects whose ODE solve produced NaN/Inf have their tolerances relaxed, and the relaxed tolerance persists across optimizer calls (sticky). When 'FALSE', all subjects have their tolerances relaxed on each retry and tolerances are reset afterward.

Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].

Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.

Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.

Parameter normalization/scaling used to get scaled initial values for scaleType, of the form Vscaled = (Vunscaled-C1)/C2 (see Feature Scaling; rescale2 follows the OptdesX manual): "rescale2" scales all parameters to (-1, 1); "rescale" (min-max) scales to (0, 1); "mean" centers on the mean with range (0, 1); "std" standardizes by mean/sd; "len" scales to unit (Euclidean) length; "constant" performs no normalization (C1=0, C2=1).

The scaling scheme for nlmixr2: "nlmixr2" (default) scales as (current-init)*scaleC[i] + scaleTo, with scaleTo from normType and scales from scaleC; "norm" uses the simple scaling from normType; "mult" scales multiplicatively as current/init*scaleTo; "multAdd" scales linearly ((current-init)+scaleTo) for parameters in an exponential block (e.g. exp(theta)) and multiplicatively otherwise.

Maximum value of the scaleC to prevent overflow.

Minimum value of the scaleC to prevent underflow.

Scaling constant used with scaleType="nlmixr2"; when not specified, chosen by parameter type to keep gradient sizes similar on a log scale: '1' for exp()-transformed/power/boxCox/ yeoJohnson parameters, '0.5*abs(est)' for additive/proportional/ lognormal error parameters, 'abs(1/digamma(est+1))' for factorials, and 'log(abs(est))*abs(est)' for log-scale parameters. May be set explicitly per parameter if these defaults don't apply well.

Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.

'rxode2' ODE solving options during fitting, created with 'rxControl()'

Optimize the rxode2 expression to speed up calculation. By default this is turned on.

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.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

Type of additive-plus-proportional error: '"combined1"', where standard deviations add:

y = f + (a + b\times f^c) \times \varepsilon

; or '"combined2"', where variances add:

y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon

. Here y = observed, f = predicted, a = additive sd, b = proportional/power sd, c = power exponent (1 in the proportional case).

This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE

Should the object have compressed items

Method for calculating the covariance. "r" (the default) uses nlmixr2's nlmixr2Hess() Hessian; "" skips the covariance step.

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

Confidence level for some tables. By default this is 0.95 or 95% confidence.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

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.

Controls how dosing/event-parameter ('alag', 'F', 'rate', 'dur') sensitivities are computed for THETA/ETA gradients: ‘"jump"' (default) uses rxode2’s analytic event sensitivities; '"fd"' uses the legacy finite-difference behavior.

Ignored parameters

data to transform

Cox-box lambda parameter

Matrix to be Factorized.

Tolerance; Algorithm suggests (.Machine$double.eps) ^ (1 / 3), default

Random seed for the variational optimization (reparameterization sampling); default 42. The Monte-Carlo gradient is stochastic, so a fixed seed makes every fit reproducible. Reparameterization noise is drawn from a counter-based stream keyed by the global iteration index, so a shorter run is a bit-for-bit prefix of a longer one and results are independent of the number of cores.

Total number of stochastic gradient ascent iterations.

Number of Monte-Carlo samples used to approximate the ELBO gradient at each iteration (the paper's 'M'; typically 1-10).

Variational family in the unconstrained space. '"fullRank"' (default) uses a block full-rank Gaussian: a dense 'neta x neta' Cholesky factor per subject plus a dense block over the population vector (mean-field across blocks). '"meanField"' uses a fully factorized (diagonal) Gaussian. Mean-field is faster but is known to underestimate marginal variances.

Which of the two methods to run, normally left at its 'NULL' default so it follows 'est': 'est="emvi"' implies 'TRUE' and 'est="fbvi"' implies 'FALSE'. 'est' wins over a contradicting value, and says so – it has to, because re-estimating a fit with the other method pipes the completed fit's control forward. 'TRUE' runs the variational-EM hybrid: the variational posterior covers the per-subject etas only, and the population parameters (thetas / omega / residual error) are point estimates maximized by the ELBO gradient; output semantics match FOCEi/SAEM. 'FALSE' runs full Bayes: the variational posterior also covers the unconstrained population vector, with flat priors.

Two things about "flat" are worth being explicit about, because they define the prior rather than merely describe the implementation. (1) A BOUNDED theta is fitted on its unconstrained scale, and the log-determinant of that constraining transform IS added to the full-Bayes objective, so the flat prior is flat on the NATURAL parameter, as in Stan. It is deliberately NOT added when 'pointEstimate=TRUE': a maximum-likelihood estimate has to stay invariant to reparameterization, which is why Stan's own 'optimize' defaults to 'jacobian=0'. (2) The between-subject variances are carried as per-eta LOG-variances and no Jacobian is applied to them, so the prior is flat on 'log(omega)' – the conventional weakly-informative choice for a scale parameter, but a choice, not an accident: it is not flat on 'omega'.

These point estimates maximize the ELBO, NOT the likelihood, and the difference is not merely cosmetic. Since 'ELBO = log p(y|theta) - KL(q || p(eta|y,theta))', any dependence of that KL on 'theta' displaces the maximizer from the MLE – "variational maximum likelihood". For VARIANCE components the displacement has a known direction: a variational family that understates posterior spread makes the omega M-step, ‘Omega = mean_i(mu_i mu_i’ + Sigma_i)', inherit that understatement, so between-subject variability is biased DOWNWARD. The bias is worst for 'viFamily="meanField"', which cannot represent within-subject posterior correlation at all; '"fullRank"' can, which is why it is the default. Structural (typical-value) parameters are far less affected. If the between-subject variances are themselves the quantity of interest, prefer '"fullRank"' and cross-check against 'est="focei"' or 'est="saem"'.

Stochastic optimizer. '"advi"' (default) uses the adaptive step-size sequence from the ADVI paper (Eqs 10-11) – the value keeps that name because the step-size rule really is the published one, even though the surrounding method is not; '"adam"' uses Adam.

When 'TRUE' (default) adaptively choose the step-size scale 'eta' by a short search over 'etaCandidates' before the main loop; when 'FALSE' use a fixed 'eta' (the first 'etaCandidates' entry).

Fraction of the run over which a declared correlated 'omega' block is held at zero correlation, letting the population variances settle before the correlations are estimated. This is saemControl()'s 'perNoCor' rule (0.75 there as well); it has no effect on a model with no declared off-diagonals.

Held at ZERO, following saem, not at the 'ini()' value: retaining an initial covariance while the variances shrink around it can leave the block non-positive-definite. A 'fixed()' covariance is exempt – it is not being estimated, so it keeps its value through the hold and out the other side. When the correlations are released the off-diagonal gain restarts rather than continuing the decayed schedule, so they are still estimable at the point they are unfrozen. This is needed here and not in vaeControl(): there the fraction is of the EM phase, where the gain is still 1 at release, whereas this run has no such phase and the fraction lands in the decayed schedule.

A value greater than 1 is an ABSOLUTE iteration count rather than a fraction, and must be a whole number. The resolved absolute iteration is stored with the fit and reused by 'resume=', so a resumed run releases the correlations at the same global iteration a single long run would – recomputing the fraction from the resumed call's 'iters' would re-apply a hold the original run had passed. Only 'est="emvi"' estimates the block at all; 'est="fbvi"' carries 'omega' as per-eta log-variances and errors on a correlated model rather than dropping the off-diagonal.

Candidate step-size scales searched when 'adaptEta' is ‘TRUE'. The default is narrower and smaller-valued than the paper’s 'c(0.01, 0.1, 1, 10, 100)' because these gradients come from FOCEi sensitivities on the model's own scale rather than from AD through a Stan program, so the useful step sizes sit lower; the paper's grid can be passed verbatim if wanted. Each candidate costs 'min(iters, 75)' iterations (a diverging one aborts early and is cheap), so the search is a substantial share of a fit – widen it deliberately. When the search selects the largest or smallest candidate the grid may be the binding constraint, and the fit says so in '$runInfo'; '$etaScores' reports the per-candidate scores behind the choice.

Stabilizing constant 'tau > 0' in the step-size denominator (paper Eq 10); the step-size is insensitive to it.

Weighting 'alpha' in (0, 1) of new vs old gradient information in the step-size memory recursion (paper Eq 11).

Convergence tolerance on the relative change in the ELBO: the loop stops early once the change falls below this. 'NULL' (default) derives it from 'sigdig' as '10^(-sigdig)', the same rule 'saemControl()' and 'foceiControl()' use for their optimizer tolerances, so it tightens with 'sigdig' instead of staying pinned. '0' disables early stopping (run all 'iters'). Because the per-iteration ELBO is an 'nMc'-sample Monte-Carlo estimate and therefore noisy, the test compares the MEAN over the last 'evalElbo' iterations against the mean over the window before it, rather than consecutive iterations. The 'adaptEta' step-size search never stops early on this criterion (its scorer reads a short run as divergence).

Window length, in iterations, for the 'tol' convergence test. Stan's ADVI re-evaluates the ELBO every 100 iterations with fresh draws; averaging the draws already taken is the cheaper equivalent. Shrunk automatically on a short run so 'iters' well below 'evalElbo' can still trigger the check.

Number of iterations of PRIOR TEMPERING (0, the default, disables it). During the warm-up the population prior is inflated by a factor ramping geometrically from 'temperInit' down to 1, which down-weights the prior term of the ELBO and keeps the per-subject variational posterior from collapsing before it is informative. This is the variational analogue of saemControl()'s 'perSa' simulated-annealing phase (true simulated annealing does not transfer: variational inference has no MCMC kernel to keep wide).

It CHANGES THE OBJECTIVE FUNCTION MID-RUN. Early iterations maximize a tempered surrogate rather than the ELBO, so the convergence theory for the ELBO does not cover the warm-up, the reported ELBO trace is not comparable across the boundary, and the 'tol' early-stopping test is suppressed until tempering ends. The 'adaptEta' step-size search also scores candidates on the untempered objective. Off by default for those reasons; turn it on for a model where the variational scale collapses early.

Initial prior inflation factor for 'klWarmup' tempering (default 10); ignored when 'klWarmup = 0'.

Inner likelihood used for the per-subject objective and gradient, run through the FOCEi inner interface: '"focei"' (default), '"foce"', '"focep"', or '"laplace"'.

When 'TRUE' return the raw variational optimization object instead of the nlmixr2 fit.

Optional warm-resume state: a previous 'emvi'/'fbvi' fit (or its '$env$viState'). The optimization continues from that state for 'iters' more iterations, bit-for-bit identical to a single fresh run of the combined length (the counter-based RNG is keyed by the global iteration index).

That equivalence requires every schedule point to be an ABSOLUTE iteration. A FRACTIONAL 'perNoCor' cannot provide it, and not because of any bookkeeping that could be fixed: 'perNoCor = 0.75' of one 120-iteration run releases the correlations at iteration 90, while 0.75 of a first 60-iteration leg releases at 45. Those are different schedules, and the resulting correlation estimates genuinely differ. Pin the schedule ('perNoCor = 90') whenever a fit may be resumed; the resolved value is then stored with the fit and reused.

Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.

Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].

Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.

Method for calculating covariance. In this discussion, R is the Hessian matrix of the objective function. The S matrix is the sum of each individual's gradient cross-product (evaluated at the individual empirical Bayes estimates).

"sa" (default) Use the stochastic-approximation Fisher Information Matrix. After estimation, a dedicated covariance phase (nSaCov iterations) holds the parameters at the converged estimate and keeps resimulating the individual parameters, Monte-Carlo averaging the Louis observed-information integrand into a converged FIM decoupled from the cooling schedule (the approach used by Monolix; Kuhn & Lavielle 2005). Always includes every estimated population parameter (theta, the Omega diagonal variances, and residual).

"analytic" Compute the FOCEI analytic observed-information covariance at the converged SAEM estimates. When the model is out of analytic-covariance scope (e.g. linCmt(), a non-normal likelihood, or a non-SD IOV parameterization) or the result is not positive definite, it falls back to the linearized Fisher information (linFim) with a message.

"linFim" Use the Linearized Fisher Information Matrix to calculate the covariance.

"fim" Use the Fisher Information Matrix accumulated during SAEM estimation to calculate the covariance. Like sa it inverts the observed information to a full theta + Omega diagonal + residual covariance, but uses the (noisier) estimation-phase matrix rather than a dedicated cov phase.

For both fim and sa the simulation-based Fisher information covers the structural theta, the Omega diagonal variances, and additive residual error. Off-diagonal Omega covariances and proportional/combined residual error are not estimated reliably by the simulation FIM (the complete-data correction is unstable when between-subject variability dominates the residual), so those variance-block standard errors are spliced in from the linearized FIM (linFim).

"r,s" Uses the sandwich matrix to calculate the covariance, that is: R^-1 \times S \times R^-1

"r" Uses the Hessian matrix to calculate the covariance as 2\times R^-1

"s" Uses the crossproduct matrix to calculate the covariance as 4\times S^-1

"" Does not calculate the covariance step.

Optimize the rxode2 expression to speed up calculation. By default this is turned on.

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.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

Type of additive-plus-proportional error: '"combined1"', where standard deviations add:

y = f + (a + b\times f^c) \times \varepsilon

; or '"combined2"', where variances add:

y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon

. Here y = observed, f = predicted, a = additive sd, b = proportional/power sd, c = power exponent (1 in the proportional case).

This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE

Should the object have compressed items

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

Confidence level for some tables. By default this is 0.95 or 95% confidence.

Specifies the "significant digits" that the ODE solving requests. This is NULL by default, and while it is NULL it has no effect at all: rxSolve() uses the standard atol/rtol (and the standard sensitivity and steady-state tolerances). sigdig only changes a tolerance when you ask for it explicitly.

When it is supplied, the tolerances are derived with one solver-independent formula – the same for stiff, non-stiff and auto-switching solvers. The rtol exponent IS sigdig and atol sits three orders below it:

• rtol = 10^(-sigdig), atol = 10^(-sigdig-3)

• the sensitivity tolerances match the main solve, so rtolSens = rtol and atolSens = atol (gradients and covariances are built from them)

• the steady-state tolerances run one order looser than the corresponding main tolerance, so ssRtol = ssRtolSens = 10*rtol and ssAtol = ssAtolSens = 10*atol

Each of these is set only when you did not pass that tolerance yourself; a tolerance you supply always wins. Because they are resolved independently, an explicit atol/rtol overrides the main solve but does not propagate to the sensitivity or steady-state tolerances – set those directly if you need them changed too.

This mapping matches how nlmixr2est derives solver tolerances from its optimization sigdig, so a sigdig used for estimation and the same sigdig used for a plain rxSolve() mean the same thing. Note it is keyed to sigdig as a request for that many significant digits, and is looser than the atol/rtol defaults for small sigdig – at sigdig = 4 it gives rtol = 1e-4 against a default rtol = 1e-6. Raise sigdig, or set atol/rtol directly, when you want a tighter solve.

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.

The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.

Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.

The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced

When 'TRUE' (default), only subjects whose ODE solve produced NaN/Inf have their tolerances relaxed, and the relaxed tolerance persists across optimizer calls (sticky). When 'FALSE', all subjects have their tolerances relaxed on each retry and tolerances are reset afterward.

Controls how dosing/event-parameter ('alag', 'F', 'rate', 'dur') sensitivities are computed for THETA/ETA gradients: ‘"jump"' (default) uses rxode2’s analytic event sensitivities; '"fd"' uses the legacy finite-difference behavior.

'rxode2' ODE solving options during fitting, created with 'rxControl()'

Other arguments to control SAEM.

Parameters passed to [emviControl()].

Which of the two methods to run, normally left at its 'NULL' default so it follows 'est': 'est="emvi"' implies 'TRUE' and 'est="fbvi"' implies 'FALSE'. 'est' wins over a contradicting value, and says so – it has to, because re-estimating a fit with the other method pipes the completed fit's control forward. 'TRUE' runs the variational-EM hybrid: the variational posterior covers the per-subject etas only, and the population parameters (thetas / omega / residual error) are point estimates maximized by the ELBO gradient; output semantics match FOCEi/SAEM. 'FALSE' runs full Bayes: the variational posterior also covers the unconstrained population vector, with flat priors.

Two things about "flat" are worth being explicit about, because they define the prior rather than merely describe the implementation. (1) A BOUNDED theta is fitted on its unconstrained scale, and the log-determinant of that constraining transform IS added to the full-Bayes objective, so the flat prior is flat on the NATURAL parameter, as in Stan. It is deliberately NOT added when 'pointEstimate=TRUE': a maximum-likelihood estimate has to stay invariant to reparameterization, which is why Stan's own 'optimize' defaults to 'jacobian=0'. (2) The between-subject variances are carried as per-eta LOG-variances and no Jacobian is applied to them, so the prior is flat on 'log(omega)' – the conventional weakly-informative choice for a scale parameter, but a choice, not an accident: it is not flat on 'omega'.

These point estimates maximize the ELBO, NOT the likelihood, and the difference is not merely cosmetic. Since 'ELBO = log p(y|theta) - KL(q || p(eta|y,theta))', any dependence of that KL on 'theta' displaces the maximizer from the MLE – "variational maximum likelihood". For VARIANCE components the displacement has a known direction: a variational family that understates posterior spread makes the omega M-step, ‘Omega = mean_i(mu_i mu_i’ + Sigma_i)', inherit that understatement, so between-subject variability is biased DOWNWARD. The bias is worst for 'viFamily="meanField"', which cannot represent within-subject posterior correlation at all; '"fullRank"' can, which is why it is the default. Structural (typical-value) parameters are far less affected. If the between-subject variances are themselves the quantity of interest, prefer '"fullRank"' and cross-check against 'est="focei"' or 'est="saem"'.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Parameters used in the default 'foceiConrol()'

Logical indicating if the estimation method should calculate 'foce' posthoc predicted parameters.

Interaction term for the model; ignored by fo

Logical indicating if the estimation method is FO (first order), but this is controlled by the estimation method so this is ignored.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Parameters used in the default 'foceiControl()'

Interaction term for the model, in this case the default is 'FALSE'; it cannot be changed, use 'focei' instead

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Ignored parameters

Precision of estimate for n1qn1 optimization.

Number of iterations for n1qn1 optimization.

Maximum number of L-BFGS-B optimization for outer problem.

Number of function evaluations for n1qn1 optimization.

Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.

Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.

Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.

Scale the initial objective function to this value. By default this is 0 (meaning do not scale)

Parameter normalization/scaling used to get scaled initial values for scaleType, of the form Vscaled = (Vunscaled-C1)/C2 (see Feature Scaling; rescale2 follows the OptdesX manual): "rescale2" scales all parameters to (-1, 1); "rescale" (min-max) scales to (0, 1); "mean" centers on the mean with range (0, 1); "std" standardizes by mean/sd; "len" scales to unit (Euclidean) length; "constant" performs no normalization (C1=0, C2=1).

The scaling scheme for nlmixr2: "nlmixr2" (default) scales as (current-init)*scaleC[i] + scaleTo, with scaleTo from normType and scales from scaleC; "norm" uses the simple scaling from normType; "mult" scales multiplicatively as current/init*scaleTo; "multAdd" scales linearly ((current-init)+scaleTo) for parameters in an exponential block (e.g. exp(theta)) and multiplicatively otherwise.

Maximum value of the scaleC to prevent overflow.

Minimum value of the scaleC to prevent underflow.

Length-2 increasing pair 'c(low, high)' (default ‘c(0.1, 10)'). Each 'theta'’s derivative-based scaling constant ('1/|init|' for a linear parameter, or the transform-specific formula) is kept when it lands inside this band, and otherwise replaced by the parameter's native magnitude '|init|'. This catches the singular cases – '1/|init|' blowing up for a small covariate initial estimate, 'log()' at init '1', 'logit' at the interval midpoint, 'factorial'/'gamma' at a digamma zero – while leaving the well-scaled common case (and its results) untouched.

Scaling constant used with scaleType="nlmixr2"; when not specified, chosen by parameter type to keep gradient sizes similar on a log scale: '1' for exp()-transformed/power/boxCox/ yeoJohnson parameters, '0.5*abs(est)' for additive/proportional/ lognormal error parameters, 'abs(1/digamma(est+1))' for factorials, and 'log(abs(est))*abs(est)' for log-scale parameters. May be set explicitly per parameter if these defaults don't apply well.

Number to adjust the scaling factor by if the initial gradient is zero.

Forward difference tolerances (relative, absolute); step size h = abs(x)*derivEps[1] + derivEps[2].

Derivative method for the outer problem: "switch", "central", or "forward". "switch" starts forward and toggles to central when abs(delta(OFV)) <= derivSwitchTol.

The tolerance to switch forward to central differences.

indicates the method for calculating the derivatives while calculating the covariance components (Hessian and S).

Method for calculating the covariance. "r,s" (the default) is the sandwich estimator (see below). "analytic" uses the exact analytic observed-information R-matrix (reported as R^{-1}) and additionally returns the residual and Omega standard errors; it covers FOCEI/FOCE fits with additive, proportional, or combined error, mu-referenced/covariate/other structural parameters (and non-mu-referenced etas), and SD-scale inter-occasion variability, and emits a message and falls back to the finite-difference Hessian for anything out of scope (FO, nAGQ > 1, censoring, DV-transformed error, bounded-parameter transforms, a structural theta shared by two etas, non-SD iovXform, or a pure-proportional variance that vanishes at a near-zero prediction). The finite-difference methods use R (the Hessian) and S (the sum of individual gradient cross-products at the empirical Bayes estimates): "r,s" sandwich (solve(R)%*%S%*%solve(R)), "r" Hessian-based (solve(R)), "s" cross-product-based (solve(S)), or "" to skip the covariance step. "sa" (SAEM Louis stochastic-approximation FIM) and "imp" (importance-sampling Monte-Carlo observed information) are also accepted for any method; they are computed post-fit at the converged estimates by the decoupled recompute engine.

absolute/relative ODE tolerance for the covariance solves – the augmented-sensitivity solves behind covMethod="analytic" and the perturbed solves behind the finite-difference methods. NULL (default) derives a tight tolerance from sigdig; supply a number to override it.

shape of fit$cov. TRUE (default) installs the full theta + residual sigma + Omega covariance (assembled analytically for covMethod="analytic", or by central finite differences over the same parameter set otherwise). For the finite-difference methods it follows covMethod: "r,s" is the full sandwich solve(Rfull) %*% Sfull %*% solve(Rfull), "s" is solve(Sfull), "r" is solve(Rfull). FALSE installs only the structural-theta block (the historical shape).

When TRUE, compute the outer (population) gradient analytically from Almquist (2015) sensitivity equations instead of by finite differences, and use the Eq-48 random-effect extrapolation for the next inner-problem starting values. Requires an analytic-scope model. Conditionally Gaussian endpoints route through the general (f,R) assembler, which covers more than the plain add/prop case – multiple endpoints, combined and power error, both-sides transforms and a single estimated boxCox/yeoJohnson lambda. A single non-Gaussian (ll()/generalized) endpoint instead differentiates the log-density directly, giving an exact inner Hessian and analytic outer gradient. Out of scope are linCmt(), fo, IOV, more than one estimated lambda, a theta mu-referenced by several random effects, and (for the non-Gaussian path) multiple endpoints, censoring or nAGQ > 1; those fall back to the finite-difference gradient with a message (linCmt() and out-of-scope log-likelihood models downgrade to fast=FALSE up front). When unspecified, the outer optimizer defaults to "lbfgsb3c" (vs "nlminb" for fast=FALSE); pairing fast=TRUE with a derivative-free outerOpt reverts to fast=FALSE. The *f methods (e.g. foceif) default this to TRUE.

Refine finite-difference slopes that the robust outlier test flags (default TRUE). When a subject's per-parameter slope sits far outside the modified z-score interval of the others, its central difference is suspect; those slopes – and only those – are recomputed with a total-variation regularized derivative (Chartrand) on a wide interval. Set FALSE to keep the plain central difference.

On by default because the outlier test is itself the gate: a well-behaved problem flags nothing and pays nothing, so the cost falls only on the complex fits where a slope really is an outlier – exactly where you would want the refinement, and where a user is least likely to know to ask for it. fit$env$nFdOutlier reports flagged parameters and refined slopes, so you can see whether it engaged for a given fit.

Worth knowing when judging it: the measurements that originally motivated this refinement were taken while the likelihood and the Shi step selection were both faulty, so they do not evidence its value on current code, and it has not been observed to trigger on ordinary fits.

Convergence tolerance on the score of the FOCE frozen-variance EBE re-solve, which the analytic outer gradient (fast=TRUE, interaction=FALSE) needs because FOCE's mode is not the inner problem's mode. NULL (default) uses 1e-9; the first iteration uses a looser 1e-3 so an already-stationary eta is returned untouched. Unlike the solver and optimizer tolerances this is not derived from sigdig – it is a convergence target on an inner Newton rather than a precision request. Set it explicitly to test whether a fit's finite-difference fallbacks are tolerance-driven.

is a double value representing the epsilon for the Hessian calculation. This is used for the R matrix calculation.

is a double value representing the epsilon for the Hessian calculation when doing focei generalized log-likelihood estimation. This is used for the R matrix calculation.

Hessian type for numeric-difference individual Hessians in generalized log-likelihood estimation: "central" (matches R's 'optimHess()', default) or "forward" (faster).

Hessian type for numeric-difference individual Hessians used for the covariance step/final likelihood: "central" (more accurate, used here) or "forward".

Treatment of the second derivative for censored (M2/M3/M4/BLQ) observations in the FOCEI family. "gauss" (the default) keeps the historic uncensored Gauss-Newton curvature, matching common PMx tools; "laplace" uses the exact censored second derivative of the objective (a proper Laplace inner Hessian and analytic covariance). Accepted by saemControl/nlmControl for a uniform interface but inert there – SAEM (stochastic EM) has no Laplace inner Hessian, and NLM uses a finite-difference Hessian that already reflects censoring exactly.

Event gradient type for dosing events; Can be "central" or "forward"

Controls how dosing/event-parameter ('alag', 'F', 'rate', 'dur') sensitivities are computed for THETA/ETA gradients: ‘"jump"' (default) uses rxode2’s analytic event sensitivities; '"fd"' uses the legacy finite-difference behavior.

Central difference tolerances (relative, absolute); step size h = abs(x)*derivEps[1] + derivEps[2].

An integer giving the number of BFGS updates retained in the "L-BFGS-B" method, It defaults to 7.

Projected-gradient convergence tolerance for "L-BFGS-B": iteration stops when max(| proj g_i |) <= lbfgsPgtol. Defaults to '0' (check suppressed).

Convergence factor for "L-BFGS-B": converges when the objective reduction is within lbfgsFactr * .Machine$double.eps. Derived from sigdig as 10^-sigdig / .Machine$double.eps, so the objective reduction target IS 10^-sigdig.

A boolean indicating if eigenvectors are calculated to include a condition number calculation.

Transformation used on the diagonal of chol(solve(omega)) (the FOCEi-estimated parameters): one of "sqrt" (default), "log", or "identity".

Transformation used on the diagonal of the IOV: one of "sd", "var", "logsd", or "logvar".

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.

Optimize the rxode2 expression to speed up calculation. By default this is turned on.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

Confidence level for some tables. By default this is 0.95 or 95% confidence.

Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].

Tolerance for boundary issues.

This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE

Boolean to indicate if you should abort the FOCEi evaluation if it runs into troubles. (default TRUE)

Boolean indicate FOCEi should be used (TRUE) instead of FOCE (FALSE)

Controls how FOCE (interaction = FALSE) evaluates the residual variance R in the inner objective; ignored for FOCEi. Either "nonmem" (default) or "foce+":

• "nonmem" freezes R at the eta = 0 population prediction and holds it constant across the inner optimization, matching NONMEM's FOCE. Advantage: reproduces NONMEM FOCE objective and standard errors, and an ODE model agrees with its closed-form (linCmt) equivalent. Disadvantage: R ignores the individual (conditional) heteroscedasticity, so it can be slightly less accurate than "foce+" for proportional/combined error.

• "foce+" evaluates R at the current conditional eta (the live variance), keeping the truncated FOCE inner gradient. Advantage: uses the conditional variance and is a bit more accurate than NONMEM's FOCE in some cases. Disadvantage: does not match NONMEM FOCE. This was the FOCE behavior in nlmixr2est 6.0.1 and earlier. This does not use the gradient of eta like the full focei method, so it is not as accurate as focei.

tolerance for Generalized Cholesky Decomposition. Defaults to suggested (.Machine$double.eps)^(1/3)

Tolerance to accept a Generalized Cholesky Decomposition for a R or S matrix.

P-value for resetting an individual ETA to 0 during optimization, based on a z-test of chol(omega^-1) %*% eta or eta/sd(allEtas). '0' = never reset, '1' = always reset.

P-value for resetting mu-referenced THETAs based on ETA drift, checked at the start and near a local minimum (see resetThetaCheckPer). '0' = never reset (the default); '1' is not allowed. Defaults to off: when the etas cannot re-center the reset repeats without progress and can error the fit out, and where it converges it reaches a worse optimum than leaving it off.

represents the p-value for reseting the population mu-referenced THETA parameters based on ETA drift during optimization, and resetting the optimization one final time. '0' = never reset (the default); see resetThetaP.

Upper bound of the diagonal omega matrix, as diag(omega)*diagOmegaBoundUpper. '1' = no upper bound.

Lower bound of the diagonal omega matrix, as diag(omega)/diagOmegaBoundLower. '1' = no lower bound.

Boolean indicating if the generalized Cholesky should be used while optimizing.

Boolean indicating if the generalized Cholesky should be used while calculating the Covariance Matrix.

is a boolean indicating if this is a FO approximation routine.

If the R matrix is non-positive definite and cannot be corrected to be non-positive definite try estimating the Hessian on the unscaled parameter space.

optimization method for the outer problem

optimization method for the inner problem (not implemented yet.)

Initial trust region radius for the bobyqa outer optimizer (with 'rhoend', must satisfy '0 < rhoend < rhobeg'). Default '0.2' (20 'abs(upper-lower)/2'. (bobyqa)

Final trust region radius. If not defined, '10^(-sigdig)' is used. (bobyqa)

Number of points for bobyqa's quadratic approximation to the objective; must be in '[n+2, (n+1)(n+2)/2]'. Defaults to '2*n + 1'. (bobyqa)

Relative tolerance before nlminb stops (nlmimb).

X tolerance for nlmixr2 optimizer

Number of maximum evaluations of the objective function (nlmimb)

Maximum number of iterations allowed (nlmimb)

Absolute tolerance for nlmixr2 optimizer (BFGS)

tolerance for nlmixr2 (BFGS)

is a boolean representing if the individual Hessian is reset when ETAs are reset using the option resetEtaP.

Mu-referenced-FOCEI-family regression variant: "none" (default, ordinary FOCEI); "lin" (mfocei/mfoce/magq/mlaplace) profiles mu-referenced population thetas and covariate coefficients out of the outer optimizer via closed-form OLS regression of each subject's back-calculated value on the covariates (muModelTol/ muModelMaxCycles); "irls" (ifocei/ifoce/iagq/ilaplace) reweights that by inner-optimization curvature. Bounded mu parameters are regression-updated with a clamped step (muModelClampRetries); a user-fixed (fix()) mu theta is never updated.

When 'TRUE' (default), algebraic expressions that can be mu-referenced are internally rewritten as mu-referenced covariates and restored after optimization. Mirrors saemControl(muRefCovAlg=)/nlmeControl(muRefCovAlg=); for foceiControl() only takes effect when muModel != "none".

Convergence tolerance for the mu-referenced-FOCEI-family "re-optimize etas, then regress" cycle (muModel != "none"): repeats until the max mu-group theta change drops below this value or muModelMaxCycles is reached.

Maximum number of "re-optimize etas, regress" cycles per outer iteration (see muModel, muModelTol).

Maximum number of active-set re-solve passes per group per regression update when a bounded mu-referenced parameter must be clamped to its bound (see muModel); on hitting the cap the current clamped-feasible solution is used.

Trim state amounts/concentrations to this value.

The maximum number of steps for the optimization of the forward-difference step size. When not zero, use this instead of Gill differences.

The maximum number of steps for the optimization of the individual Hessian matrices in the generalized likelihood problem. When 0, un-optimized finite differences are used.

The maximum number of steps for the optimization of the individual Hessian matrices in the generalized likelihood problem for the covariance step. When 0, un-optimized finite differences are used.

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)

Upper bound on the adaptive shi21 finite-difference step size for FOCEi gradients (both the inner eta and outer theta/covariate finite differences). The step-size search never probes a parameter by more than this on its estimation scale; a larger value lets the gradient of a flat, small-magnitude parameter (e.g. a covariate coefficient near 0) clear the ODE-solver noise floor, at the cost of risking a degenerate solve at the probe.

Lower bound on the adaptive shi21 finite-difference step size for FOCEi gradients. The floor is limited by the ODE solver tolerance (atol/rtol), not machine precision; below it the finite difference is dominated by solver noise.

Max steps to determine the optimal forward/central difference step size per parameter (Gill 1983). '0' = no optimal step size determined.

When looking for the optimal forward difference step size, this is This is the step size to increase the initial estimate by. So each iteration the new step size = (prior step size)*gillStep

The gillFtol is the gradient error tolerance that is acceptable before issuing a warning/error about the gradient estimates.

The relative tolerance used for Gill 1983 determination of optimal step size.

Max steps to determine the optimal forward/central difference step size per parameter (Gill 1983) during the covariance step. '0' = no optimal step size determined.

Same as gillK but for the generalized focei log-likelihood method (Gill 1986).

Same as above but during generalized focei log-likelihood

When looking for the optimal forward difference step size, this is This is the step size to increase the initial estimate by. So each iteration during the covariance step is equal to the new step size = (prior step size)*gillStepCov

The gillFtol is the gradient error tolerance that is acceptable before issuing a warning/error about the gradient estimates during the covariance step.

Same as above but applied during generalized log-likelihood estimation.

A parameter to normalize gradient step size by the parameter value during the calculation of the R matrix

A parameter to normalize gradient step size by the parameter value during the calculation of the R matrix if you are using generalized log-likelihood Hessian matrix.

A parameter to normalize gradient step size by the parameter value during the calculation of the S matrix

A parameter to normalize gradient step size by the parameter value during the calculation of the S matrix if you are using the generalized log-likelihood.

Use the Gill calculated optimal Forward difference step size for the instead of the central difference step size during the central difference gradient calculation.

Use the Gill calculated optimal Forward difference step size for the instead of the central difference step size during the central differences for optimization.

Small number used to compare covariance estimates (sandwich vs R/S matrix) before rejecting one as too small to be the final covariance estimate.

When 'TRUE', adjusts the likelihood by the 2*pi constant nlmixr2's objective function otherwise omits (to match NONMEM), more closely matching nlme/SAS likelihood approximations. The objective function itself always matches NONMEM regardless.

The parameter to adjust the gradient to if the |gradient| is very large.

Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.

The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced

A small number that represents the value where |grad| < gradCalcCentralSmall where forward differences switch to central differences.

A large number that represents the value where |grad| > gradCalcCentralLarge where forward differences switch to central differences.

When n1qn1 optimization of an ETA (starting at zero) misbehaves, reset the Hessian and nudge the ETA up by this value, then down if it still doesn't move. Defaults to 'qnorm(1-0.05/2)*1/sqrt(3)'. Falls back to etaNudge2, then to zero (stop optimizing) if unsuccessful.

This is the second eta nudge. By default it is qnorm(1-0.05/2)*sqrt(3/5), which is the n=3 quadrature point (excluding zero) times by the 0.95% normal region

If FOCEi doesn't fit with the current parameter estimates, randomly sample new parameter estimates and restart the problem. This is similar to 'PsN' resampling.

Integer seed (default '42') used to make a FOCEi fit reproducible and self-contained. The fit (including the 'mceta' Monte-Carlo initial-ETA draws, which pull from rxode2's threefry engine) runs inside [rxode2::rxWithSeed()], so it neither depends on the ambient RNG state nor advances/leaks it – repeated fits in the same session, and fits following other estimation methods, give identical results.

represents objective function % percentage below which resetThetaP is checked.

Initial (or final) ETA estimates; can also be a prior fit, whose final ETAs are then used as initial values. By default, uses the last fit's ETAs if supplied, else all ETAs start at zero ('NULL'). 'NA' disables reuse from a prior fit.

If the tolerances were reduced when calculating the initial Gill differences, the Gill difference is repeated up to a maximum number of times defined by this parameter.

The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.

Maximum number of times to reduce the ODE tolerances for a single subject and retry when the analytic outer (augmented sensitivity) solve fails. Tracked separately from 'maxOdeRecalc', which governs the inner problem. A subject that solves after loosening still contributes an analytic gradient instead of dropping the whole gradient to finite differences.

The factor the atol/rtol is loosened by on each analytic outer retry; the outer counterpart of 'odeRecalcFactor'.

The number of bad analytic outer solves for a subject before its loosened tolerance is kept for the rest of the problem; the outer counterpart of 'stickyRecalcN'.

When 'TRUE' (default), only subjects whose ODE solve produced NaN/Inf have their tolerances relaxed, and the relaxed tolerance persists across optimizer calls (sticky). When 'FALSE', all subjects have their tolerances relaxed on each retry and tolerances are reset afterward.

This is the time for a single objective function evaluation (in seconds) to start progress bars on gradient evaluations

Type of additive-plus-proportional error: '"combined1"', where standard deviations add:

y = f + (a + b\times f^c) \times \varepsilon

; or '"combined2"', where variances add:

y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon

. Here y = observed, f = predicted, a = additive sd, b = proportional/power sd, c = power exponent (1 in the proportional case).

The objective function adjustment when the ODE system cannot be solved. It is based on each individual bad solve.

Should the object have compressed items

'rxode2' ODE solving options during fitting, created with 'rxControl()'

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.

Fallback to the finite differences if the sensitivity equations do not solve.

Percentage of failed per-individual parameter gradients (replaced with the overall parameter gradient) out of the total ('ntheta*nsub') above which the S matrix is considered bad.

Factor multiplying the estimate when the lower bound is zero for a standard-deviation error parameter (add.sd, prop.sd, etc); e.g. estimate 0.15 with lower bound 0 assumes a lower bound of 0.00015. '0' disables this.

When 'TRUE' (default), reset a zero first gradient to 'sqrt(.Machine$double.eps)' instead of erroring; 'FALSE' errors; 'NA' ignores it only on the last reset attempt.

When 'TRUE' (default), reset a zero gradient encountered mid-run to 'sqrt(.Machine$double.eps)' instead of erroring.

When 'TRUE' (default), a zero-gradient reset switches to the gradient-free bobyqa method; 'NA' only does so for the first zero gradient.

Monte Carlo sampling for the best initial ETA estimate (based on 'omega'): '-2' (default) uses the Almquist (2015) Eq-48 extrapolation 'eta^0 = eta* + (d eta*/d theta)(theta_new - theta_old)' when the analytic gradient supplies 'd eta*/d theta' ('fast = TRUE'), accepting the extrapolated eta only when it is within the standardized-eta reset bound (else keeping the last eta, or resetting to 0 when that is also out of bound); '-1' jumps between the extrapolated eta and eta=0, keeping the better; both '-2' and '-1' fall back to keeping the last eta when no analytic 'd eta*/d theta' is available ('fast = FALSE'). '0' uses eta=0 for each inner optimization; for 'n>0', the last eta, eta=0, and n-1 etas sampled from omega are each evaluated and the best (by inner objective) is used.

Seeding of the n1qn1 inner-optimization Hessian: '"calc"' (default) warm-starts each inner problem with the eta Hessian calculated at the starting eta and the current theta; since theta moves between outer evaluations it is always recalculated, never reused from an earlier round. '"save"' uses the classic self-initialized Hessian.

Number of Gauss-Hermite adaptive quadrature points. '0' disables AGQ; '1' is equivalent to Laplace. Cost grows quickly with ETAs: once the EBE is found, expect 'nAGQ^neta' (even 'nAGQ') or '(nAGQ^neta)-1' (odd 'nAGQ') additional evaluations per subject.

The lower bound for adaptive quadrature log-likelihood. By default this is -Inf; in the original nlmixr's gnlmm it was -700.

The upper bound for adaptive quadrature log-likelihood. By default this is Inf; in the original nlmixr's gnlmm was 400.

Method used to compute the ODE parameter sensitivities. '"forward"' uses the classic variational (forward) sensitivity ODEs; '"default"' is the same thing.

Positive magnitude (default '0.001') used to nudge a population parameter ('theta') whose initial estimate is exactly '0' off zero before estimation. FOCEi scales a linear parameter by its native magnitude '|init|', which is '0' (no scale) for a zero initial estimate, so the parameter is moved to '+zeroTheta' when it is within the parameter's bounds, otherwise '-zeroTheta'; if neither is within the bounds an error is raised. Fixed parameters (including those fixed at '0') are left untouched.

When 'TRUE' (default), bounded parameters are transformed for unbounded optimization methods and back-transformed for final estimates. 'FALSE' optimizes on the original scale with bounds passed to the optimizer. 'NA' transforms for optimization but skips the final back-transform.

Environment

natural-scale theta, in ntheta order

nsub x neta matrix of etas to take the gradient at

inverse of the current Omega

list of d(Omega^-1)/d(estimation-scale omega element)

the matching trace terms

thread count

setup list from '.foceiGradPooledSetup()'

An 'rxode2'/'nlmixr2' UI model (a model function or its compiled UI).

The estimation data (a data frame with the usual nlmixr2 columns).

The individual likelihood type: '"focei"' (FOCE with interaction), '"focep"' (FOCE+, interaction off with the residual variance at the conditional eta) or '"foce"' (NONMEM-style FOCE, residual variance frozen at eta=0).

An [rxode2::rxControl()] object for the ODE solving options.

Additional solving/model options passed to '.foceiLikControl' (e.g. 'optExpression', 'addProp', 'eventSens').

The estimation-scale parameter vector (length 'handle$npars'), matching the FOCEi optimizer parameterization: population thetas followed by the estimated Omega elements. 'handle$initPar' from [foceiLikLoad()] is a ready starting value.

A 'nid' by 'neta' matrix of random effects (one row per subject, in the loaded system's subject order).

'"joint"' (default) returns the individual joint log density 'log p(y_i, eta_i)'; '"cond"' returns the conditional data log-likelihood 'log p(y_i | eta_i)' alone. See Details.

Number of threads for the parallel per-subject evaluation.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Parameters used in the default 'foceiControl()'

Interaction term for the model, in this case the default is 'FALSE'; it cannot be changed, use 'focei' instead

FOCE residual-variance mode; for 'focepControl()' this is always '"foce+"' and cannot be changed – use 'foceControl()' for '"nonmem"'

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Parameters used in the default 'foceiConrol()'

Logical indicating if the estimation method should calculate 'foce' posthoc predicted parameters.

Interaction term for the model; ignored by fo

Logical indicating if the estimation method is FO (first order), but this is controlled by the estimation method so this is ignored.

The numeric vector to convert

The number of significant digits to show

The value to return if 'is.na(x)'

list where first element is the fit. The class represents the estimation method.

nlmixr control object

Estimation routine

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Number of Gauss-Hermite adaptive quadrature points. '0' disables AGQ; '1' is equivalent to Laplace. Cost grows quickly with ETAs: once the EBE is found, expect 'nAGQ^neta' (even 'nAGQ') or '(nAGQ^neta)-1' (odd 'nAGQ') additional evaluations per subject.

Parameters used in the default 'foceiControl()'

boolean, Interaction term for the model, in this case the default is 'TRUE'; For adaptive quadrature, with normal distribution the Hessian is calculated with the foce(i) approximation

The lower bound for adaptive quadrature log-likelihood. By default this is -Inf; in the original nlmixr's gnlmm it was -700.

The upper bound for adaptive quadrature log-likelihood. By default this is Inf; in the original nlmixr's gnlmm was 400.

Selects the regression variant; for 'iagqControl()' this is always '"irls"' and cannot be changed – use 'magqControl()' for the closed-form OLS variant.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Parameters used in the default 'foceiControl()'

Interaction term for the model, in this case the default is 'FALSE'; it cannot be changed, use 'ifocei' instead

Selects the regression variant; for 'ifoceControl()' this is always '"irls"' and cannot be changed – use 'mfoceControl()' for the closed-form OLS variant.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Parameters used in the default 'foceiControl()'

Selects the regression variant; for 'ifoceiControl()' this is always '"irls"' and cannot be changed – use 'mfoceiControl()' for the closed-form OLS variant.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Parameters used in the default 'foceiControl()'

Interaction term for the model, in this case the default is 'FALSE'; it cannot be changed, use 'ifocei' instead

Selects the regression variant; for 'ifocepControl()' this is always '"irls"' and cannot be changed – use 'mfocepControl()' for the closed-form OLS variant.

FOCE residual-variance mode; for 'ifocepControl()' this is always '"foce+"' and cannot be changed – use 'ifoceControl()' for '"nonmem"'

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Parameters used in the default 'foceiControl()'

Number of Gauss-Hermite adaptive quadrature points. '0' disables AGQ; '1' is equivalent to Laplace. Cost grows quickly with ETAs: once the EBE is found, expect 'nAGQ^neta' (even 'nAGQ') or '(nAGQ^neta)-1' (odd 'nAGQ') additional evaluations per subject.

Selects the regression variant; for 'ilaplaceControl()' this is always '"irls"' and cannot be changed – use 'mlaplaceControl()' for the closed-form OLS variant.

Parameters passed to [impmapControl()].

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Parameters used in the default 'foceiControl()'

Number of importance samples drawn per subject per iteration (NONMEM ISAMPLE). Either a single count used for every subject, or a vector of length 'nsub' giving a count **per subject**.

Per-subject counts are the NM7 Technical Guide's own remedy for poor coverage (its derivation is Gaussian throughout and never mentions a t proposal): a subject whose weights are badly behaved can be given more samples without charging every other subject for them. Note this treats the symptom rather than the cause – more draws from a proposal whose tails are too light still gives weights with infinite variance, which 'fit$env$impPsisK' will show. See 'df' for the shape-based remedy.

Maximum number of importance-sampling EM iterations.

Number of MAP re-centering iterations per EM step; '> 0' re-centers the proposal at the MAP mode each iteration.

Initial proposal-variance inflation factor (NONMEM ISCALE); the proposal covariance is 'gamma' times the inverse of the inner information matrix at the mode.

How the proposal scale 'gamma' is adapted during the EM.

'"auto"' (default) picks per model: '"individual"' when the model is not transformably normal – a general log-likelihood ('ll()') endpoint, or a count/categorical/time-to-event distribution – and '"global"' otherwise. That is the split the hypothesis actually rests on: 'gamma = 1' is already the efficient proposal when the individual posterior is close to Gaussian, so a normal model gains nothing from per-subject adaptation and would only pay for it in effective sample size, while a general-likelihood model is exactly where the posteriors go non-Gaussian and per-subject coverage starts to vary. The test is 'all(ui$predDf$distribution == "norm")', the same line [rxode2::assertRxUiTransformNormal()] draws. The resolved value is reported in the fit's '$runInfo'.

'"global"' keeps one scale shared by every subject, inflated (never relaxed) only when the *mean* Kish effective-sample fraction falls below 'iaccept'. It leaves 'gamma' at its efficient starting value while coverage is healthy, which is the right behaviour when the individual posteriors are close to Gaussian.

'"individual"' gives every subject its own 'gamma_i' and adapts it two-sided toward a target on that subject's 'xi_i', clamped to ‘[iscaleMin, iscaleMax]'. This follows NONMEM’s *objective* – the NM7 Technical Guide states that 'gamma' is per-subject (eq. 1.90) and is "continually adjusted so that xi_i approximates IACCEPT" (note after eq. 1.76), bounded by 'ISCALE_MIN'/'ISCALE_MAX' – but the guide publishes no update formula, so the functional form used here is nlmixr2's own. Prefer this when the individual posteriors are heavy-tailed or the design is heterogeneous: a global scale is driven by the mean, so a handful of badly-covered subjects never trip it and their likelihood and 'Omega' contributions end up carried by a few samples.

The two modes report *different* efficiency statistics – '"individual"' targets ‘xi' (the mean normalized importance weight, NONMEM’s 'IACCEPT' quantity) while '"global"' targets the Kish effective-sample fraction. These are not comparable; the fit's '$runInfo' says which is in force.

How the SHARED ('gammaMethod="global"') proposal scale is adapted. Ignored for 'gammaMethod="individual"', which always follows NONMEM's two-sided per-subject rule.

'"floor"' treats 'iaccept' as a one-sided FLOOR on the mean Kish effective-sample fraction: 'gamma' stays at its efficient starting value while coverage is healthy and is inflated only when coverage drops below the floor. It never comes back down.

'"target"' (default) follows the NM7 Technical Guide, which says 'gamma' is "continually adjusted so that xi_i approximates IACCEPT" – adapted BOTH ways, on 'xi' rather than the Kish fraction, using the same analytic inversion as the per-subject controller ('gamma * (xi/iaccept)^(2/neta)', capped 1.25x each way and clamped to '[iscaleMin, iscaleMax]').

The two rules settle at different operating points, so they are not interchangeable, and constants tuned against one do not carry over to the other.

**Measured trade-off** (theophylline, 6 seeds, 'isample = 300', RMSE against an 'isample = 6000' reference):

• 3 ETAs – '"floor"': theta RMSE 0.00185, 'Omega' RMSE 0.00298, max Pareto k-hat 0.604, 0.33 subjects above 0.7, converged 100 '"target"': theta RMSE 0.00257, 'Omega' RMSE 0.00378, max k-hat -0.491, 0 subjects above 0.7, converged 0

• 8 ETAs – '"floor"' never adapts at all ('gamma' pinned at 1.0 with 'xi' 1.35, i.e. a proposal far too narrow), because it watches the mean Kish fraction, which stays healthy while 'xi' says the proposal is wrong. '"target"' moves 'gamma' to 1.25 and puts 'xi' on 0.41.

So '"target"' fixes the tail and is the only rule that reacts at high ETA dimension, but it pays for it: putting 'xi' on 'iaccept' deliberately widens the proposal ('gamma' 1.79 on the 3-ETA fixture), which costs effective sample size (0.96 to 0.70) and adds Monte-Carlo noise to the objective – enough that the fit often does not meet 'ctol' within 'nIter'.

'"target"' is the default: tuned against tuned, it wins every column at 3 ETAs and is the only rule that adapts at all at 8 ETAs. Its cost is on the 1-ETA fixture, where it roughly doubles theta RMSE (0.00113 to 0.00224) and takes about twice as many iterations. That trade follows the same weighting 'auto' uses: weights with infinite variance are a correctness problem whose error is unbounded, while the extra Monte-Carlo noise is bounded and measurable.

Choose '"floor"' for the previous behaviour – a proposal left at its efficient starting value while coverage is healthy. It is also what the tail-machinery tests pin, because '"target"' repairs the tail itself and leaves the 'df' ladder nothing to fix.

**The tuned constants travel with the rule.** Selecting a rule also selects its tuned defaults ('nConvWindow' 20 for '"target"', 10 for '"floor"'), so switching to the NONMEM method does not silently run NONMEM's law on the other rule's tuning. An explicitly supplied value always wins.

Degrees of freedom of the importance-sampling proposal (NONMEM 'DF'). '0' (default) uses a multivariate **normal** proposal; any value '> 0' uses a multivariate **t** with that many degrees of freedom.

This changes the proposal's SHAPE rather than its width, and that is the distinction that matters. 'gamma' can only make a Gaussian proposal wider; it cannot give it heavier tails. When the target posterior has heavier tails than the proposal, the importance weights have infinite variance – and neither 'xi' nor the Kish effective sample size can detect it, because the offending mass lies where the proposal rarely lands. The Pareto k-hat diagnostic ('fit$env$impPsisK') does detect it: 'k > 0.7' means that subject's weights are unreliable. A t proposal has polynomial tails that dominate a Gaussian target's, which bounds the weights.

NONMEM's guidance (Bauer, *NONMEM Tutorial Part II*) is to set a nonzero 'DF' when there are fewer data points than etas, or for categorical data. Small values (3-8) are heavy; large values approach the Gaussian.

NONMEM 'AUTO=1' equivalent: adapt the proposal degrees of freedom, the sample count and the acceptance target **per subject** rather than applying one global setting to everybody.

* **'df'** – any subject gets a heavy-tailed t proposal when the model is not transformably normal, and any subject whose Pareto k-hat reports tail failure gets one on that evidence. The tutorial's other trigger, "fewer data points than there are ETAs", is **not** applied on its own – see 'autoNonmemSparse'. An escalation that fails to improve k-hat over two iterations is withdrawn, since a heavy tail the data creates is not repairable by proposal shape. * **'isample'** – the total sample budget ('isample * nsub') is reallocated toward subjects whose effective-sample fraction is lowest, the tutorial's "many ETAs or ... large stochastic fluctuations". It is load-balancing, not a cost increase. Note sample count is deliberately *not* driven by Pareto k-hat: a heavy tail is not repairable by more draws (see 'df'). * **'iaccept'** – lowered to 0.2 for the same sparse/categorical subjects, per the tutorial.

The concrete values (the 'df' ladder, the k-hat thresholds, the budget reallocation rule) are **nlmixr2's choices**. NONMEM does not publish what 'AUTO=1' picks internally; only the triggers and 'IACCEPT ~ 0.2' are documented. Unlike NONMEM's AUTO, which its own tutorial warns "may result in lack of stochastic reproducibility", this remains seeded and thread-count independent.

Per-subject values are reported in 'fit$env$impDfInd', 'fit$env$impNsampleInd' and 'fit$env$impIacceptInd'.

**Measured trade-off.** 'auto = TRUE' (the default) improves the *tail* behaviour of the importance weights and the accuracy of 'Omega', at some cost in Monte-Carlo noise on the objective. On theophylline with three ETAs – a one-ETA model has no tail failure to fix, so it shows nothing either way – against a reference computed at 'isample = 8000', over 8 seeds:

• 'auto = FALSE': max Pareto k-hat 0.941, 2.38 subjects above 0.7; objective RMSE 0.0113, 'Omega' RMSE 0.00406

• 'auto = TRUE': max Pareto k-hat 0.571, 0.25 subjects above 0.7; objective RMSE 0.0165, 'Omega' RMSE 0.00301

So 'auto' removes the tail failure and estimates 'Omega' about 26 accurately, for about 46 on by default because weights with infinite variance are a correctness problem – their error is unbounded in the worst case – whereas the extra noise is a bounded, measurable cost. Setting 'df' globally gives a better objective still on a model that is uniformly heavy-tailed, but costs 75 more objective RMSE on one that is not, which is why it is not the default.

Set 'auto = FALSE' to recover the previous behaviour exactly (that path remains bit-identical to earlier versions), which is worth doing when you want the tightest possible objective on a model whose 'fit$env$impPsisK' values are already comfortably below 0.7.

Apply the NONMEM tutorial's 'nobs < neta' trigger unconditionally, so a subject with fewer observations than random effects always gets a t proposal. 'FALSE' (default) leaves such subjects to the Pareto k-hat evidence like any other, and withdraws an escalation that does not improve k-hat within two iterations.

The default diverges from the tutorial deliberately, on measurement. On a fixture built to the tutorial's own definition of sparse (2 observations, 3 etas), 8 seeds against an 'isample = 8000' reference, applying the rule made every number worse – objective RMSE 0.1517 -> 0.2059, 'Omega' RMSE 0.02379 -> 0.03163, and *more* failing subjects (3.88 -> 4.88). With fewer observations than random effects the individual posterior is not identified, so the heavy tail is structural and no proposal shape repairs it; the reference itself still reads max k-hat 0.794.

Set ‘TRUE' to get the documented NONMEM rule anyway. NONMEM’s own testing is not published and was not done on these models, so someone who measures the opposite on their own problem should be able to have it.

Number of consecutive iterations an escalated 'df' may fail to improve Pareto k-hat before that escalation is withdrawn and the subject returned to the proposal it had without it. '0' never withdraws. Withdrawal is final, so escalation and withdrawal cannot oscillate, and it never goes below the 'df' the model itself requires – a non-normal endpoint keeps its t proposal.

A rung is judged against what the subject manages WITHOUT any escalation, measured while it sits there, so deterioration that happens before any escalation is tracked and an escalation is never credited for it.

Lower/upper bounds for the adapted 'gamma' (NONMEM ISCALE_MIN / ISCALE_MAX). Both bounds are reachable under 'gammaRule="target"'; under '"floor"' 'gamma' only ever moves up, so only 'iscaleMax' can bind.

Minimum importance-sampling effective-sample fraction (NONMEM IACCEPT). The proposal scale 'gamma' is kept at its efficient starting value while the achieved fraction stays at or above 'iaccept', and is inflated (toward 'iscaleMax') only when it drops below this floor.

Convergence tolerance on the windowed objective-function change; 'NULL' derives it from 'sigdig'.

Length of the trailing iteration window used to average the objective-function change for convergence (NONMEM-style CTYPE).

Base seed for the per-subject thread-safe (threefry) RNG streams; results are reproducible and independent of the thread count.

Covariance method. '"imp"' (default) computes the Monte-Carlo importance-sampling observed-information covariance for the estimated thetas and Omega parameters (a finite-difference Hessian of the importance-sampling objective over fixed common-random-number samples), stashed as '$impCov' / '$impSe' and installed as the fit covariance; the theta standard errors match the Hessian-based FOCEI covariance, though the variance of a tightly-determined random effect (an Omega diagonal) can be over-estimated because the fixed samples barely span its prior variation. '"analytic"', '"r,s"', '"r"', '"s"' instead compute the FOCEI covariance post-fit at the converged estimates (see [foceiControl()]); '""' skips the covariance step.

When 'TRUE', draw quasi-random (Sobol low-discrepancy) importance samples instead of pseudo-random Gaussian samples (QRPEM, Leary & Dunlavey PAGE 2012); the E-step integrals converge at O(1/N) instead of O(1/sqrt(N)).

Only used with 'qr=TRUE'. When 'TRUE' each (iteration, subject) applies a random Cranley-Patterson shift to the Sobol points (seeded, thread-count independent); 'FALSE' reuses one fixed Sobol point set everywhere (fully deterministic E-step, no RNG in the draw).

Only used with 'qr=TRUE' and 'qrShift=TRUE'. When 'TRUE' the shift is redrawn each iteration so residual quasi-random error averages out over the EM; 'FALSE' draws one shift per subject at the fit start, making each EM iteration a deterministic map (smoothest objective trace).

When 'TRUE', accelerate the non-mu / residual-error M-step by SIR (sampling-importance-resampling): the theta-sensitivity Newton step uses 'sirSample' equal-weight resampled points per subject instead of all 'isample' weighted samples.

Number of SIR resampled points per subject; 'NULL' uses 'max(25, ceiling(isample/10))'. Must be at most 'isample'.

Mu-referencing variant for the MAP inner problem; for 'impmapControl()' this is always '"lin"' and cannot be changed.

Integer. Print one iteration row every 'every' parameter evaluations; '0' suppresses output. Defaults to '1L'.

Integer or 'NULL'. Parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.

Integer or 'NULL'. Re-emit the column header every 'headerEvery' parameter-print events; '0' prints it once at fit start. 'NULL' (default) uses '10L'.

Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].

Logical. When 'TRUE', print a single row per iteration, suppressing the unscaled ('U') / back-transformed ('X') rows. Defaults to 'FALSE'.

Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.

Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.

Integer. Print one iteration row every 'every' parameter evaluations; '0' suppresses output. Defaults to '1L'.

Integer or 'NULL'. Parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.

Integer or 'NULL'. Re-emit the column header every 'headerEvery' parameter-print events; '0' prints it once at fit start. 'NULL' (default) uses '10L'.

Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].

Logical. When 'TRUE', print a single row per iteration, suppressing the unscaled ('U') / back-transformed ('X') rows. Defaults to 'FALSE'.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Parameters used in the default 'foceiControl()'

Number of Gauss-Hermite adaptive quadrature points. '0' disables AGQ; '1' is equivalent to Laplace. Cost grows quickly with ETAs: once the EBE is found, expect 'nAGQ^neta' (even 'nAGQ') or '(nAGQ^neta)-1' (odd 'nAGQ') additional evaluations per subject.

If positive, print tracing information; higher values give more detail (see source for "L-BFGS-B" trace levels).

Convergence tolerance factor for "L-BFGS-B"; converges when the objective reduction is within this factor of machine tolerance (default 1e7, i.e. ~1e-8).

Tolerance on the projected gradient for "L-BFGS-B"; 0 (default) suppresses the check.

Absolute x-value tolerance for "L-BFGS-B"; 0 (default) suppresses the check.

Relative x-value tolerance for "L-BFGS-B"; 0 (default) suppresses the check.

Number of BFGS updates retained in "L-BFGS-B" (default 5).

maximum number of iterations.

return the lbfgsb3c output instead of the nlmixr2 fit

The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.

Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.

The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced

When 'TRUE' (default), only subjects whose ODE solve produced NaN/Inf have their tolerances relaxed, and the relaxed tolerance persists across optimizer calls (sticky). When 'FALSE', all subjects have their tolerances relaxed on each retry and tolerances are reset afterward.

Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].

Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.

Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.

Parameter normalization/scaling used to get scaled initial values for scaleType, of the form Vscaled = (Vunscaled-C1)/C2 (see Feature Scaling; rescale2 follows the OptdesX manual): "rescale2" scales all parameters to (-1, 1); "rescale" (min-max) scales to (0, 1); "mean" centers on the mean with range (0, 1); "std" standardizes by mean/sd; "len" scales to unit (Euclidean) length; "constant" performs no normalization (C1=0, C2=1).

The scaling scheme for nlmixr2: "nlmixr2" (default) scales as (current-init)*scaleC[i] + scaleTo, with scaleTo from normType and scales from scaleC; "norm" uses the simple scaling from normType; "mult" scales multiplicatively as current/init*scaleTo; "multAdd" scales linearly ((current-init)+scaleTo) for parameters in an exponential block (e.g. exp(theta)) and multiplicatively otherwise.

Maximum value of the scaleC to prevent overflow.

Minimum value of the scaleC to prevent underflow.

Scaling constant used with scaleType="nlmixr2"; when not specified, chosen by parameter type to keep gradient sizes similar on a log scale: '1' for exp()-transformed/power/boxCox/ yeoJohnson parameters, '0.5*abs(est)' for additive/proportional/ lognormal error parameters, 'abs(1/digamma(est+1))' for factorials, and 'log(abs(est))*abs(est)' for log-scale parameters. May be set explicitly per parameter if these defaults don't apply well.

Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.

this is the factor that the gradient is scaled to before optimizing. This only works with scaleType="nlmixr2".

'rxode2' ODE solving options during fitting, created with 'rxControl()'

Optimize the rxode2 expression to speed up calculation. By default this is turned on.

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.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

Type of additive-plus-proportional error: '"combined1"', where standard deviations add:

y = f + (a + b\times f^c) \times \varepsilon

; or '"combined2"', where variances add:

y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon

. Here y = observed, f = predicted, a = additive sd, b = proportional/power sd, c = power exponent (1 in the proportional case).

Controls how dosing/event-parameter ('alag', 'F', 'rate', 'dur') sensitivities are computed for THETA/ETA gradients: ‘"jump"' (default) uses rxode2’s analytic event sensitivities; '"fd"' uses the legacy finite-difference behavior.

Method used to compute the ODE parameter sensitivities. '"forward"' uses the classic variational (forward) sensitivity ODEs; '"default"' is the same thing.

This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE

Should the object have compressed items

Method for calculating the covariance. "r" (the default) uses nlmixr2's nlmixr2Hess() Hessian; "" skips the covariance step.

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

Confidence level for some tables. By default this is 0.95 or 95% confidence.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

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.

Ignored parameters

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Number of Gauss-Hermite adaptive quadrature points. '0' disables AGQ; '1' is equivalent to Laplace. Cost grows quickly with ETAs: once the EBE is found, expect 'nAGQ^neta' (even 'nAGQ') or '(nAGQ^neta)-1' (odd 'nAGQ') additional evaluations per subject.

Parameters used in the default 'foceiControl()'

boolean, Interaction term for the model, in this case the default is 'TRUE'; For adaptive quadrature, with normal distribution the Hessian is calculated with the foce(i) approximation

The lower bound for adaptive quadrature log-likelihood. By default this is -Inf; in the original nlmixr's gnlmm it was -700.

The upper bound for adaptive quadrature log-likelihood. By default this is Inf; in the original nlmixr's gnlmm was 400.

Selects the regression variant; for 'magqControl()' this is always '"lin"' and cannot be changed – use 'iagqControl()' for the IRLS variant.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Parameters used in the default 'foceiControl()'

Interaction term for the model, in this case the default is 'FALSE'; it cannot be changed, use 'mfocei' instead

Selects the regression variant; for 'mfoceControl()' this is always '"lin"' and cannot be changed – use 'ifoceControl()' for the IRLS variant.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Parameters used in the default 'foceiControl()'

Selects the regression variant; for 'mfoceiControl()' this is always '"lin"' and cannot be changed – use 'ifoceiControl()' for the IRLS variant.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Parameters used in the default 'foceiControl()'

Interaction term for the model, in this case the default is 'FALSE'; it cannot be changed, use 'mfocei' instead

Selects the regression variant; for 'mfocepControl()' this is always '"lin"' and cannot be changed – use 'ifocepControl()' for the IRLS variant.

FOCE residual-variance mode; for 'mfocepControl()' this is always '"foce+"' and cannot be changed – use 'mfoceControl()' for '"nonmem"'

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

Parameters used in the default 'foceiControl()'

Number of Gauss-Hermite adaptive quadrature points. '0' disables AGQ; '1' is equivalent to Laplace. Cost grows quickly with ETAs: once the EBE is found, expect 'nAGQ^neta' (even 'nAGQ') or '(nAGQ^neta)-1' (odd 'nAGQ') additional evaluations per subject.

Selects the regression variant; for 'mlaplaceControl()' this is always '"lin"' and cannot be changed – use 'ilaplaceControl()' for the IRLS variant.

Precision of estimate for n1qn1 optimization.

Number of iterations

Number of function evaluations

Verbosity of messages.

Boolean to control if the function value and parameter estimates are echoed every time a function is called.

return the n1qn1 output instead of the nlmixr2 fit

The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.

Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.

The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced

When 'TRUE' (default), only subjects whose ODE solve produced NaN/Inf have their tolerances relaxed, and the relaxed tolerance persists across optimizer calls (sticky). When 'FALSE', all subjects have their tolerances relaxed on each retry and tolerances are reset afterward.

Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].

Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.

Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.

Parameter normalization/scaling used to get scaled initial values for scaleType, of the form Vscaled = (Vunscaled-C1)/C2 (see Feature Scaling; rescale2 follows the OptdesX manual): "rescale2" scales all parameters to (-1, 1); "rescale" (min-max) scales to (0, 1); "mean" centers on the mean with range (0, 1); "std" standardizes by mean/sd; "len" scales to unit (Euclidean) length; "constant" performs no normalization (C1=0, C2=1).

The scaling scheme for nlmixr2: "nlmixr2" (default) scales as (current-init)*scaleC[i] + scaleTo, with scaleTo from normType and scales from scaleC; "norm" uses the simple scaling from normType; "mult" scales multiplicatively as current/init*scaleTo; "multAdd" scales linearly ((current-init)+scaleTo) for parameters in an exponential block (e.g. exp(theta)) and multiplicatively otherwise.

Maximum value of the scaleC to prevent overflow.

Minimum value of the scaleC to prevent underflow.

Scaling constant used with scaleType="nlmixr2"; when not specified, chosen by parameter type to keep gradient sizes similar on a log scale: '1' for exp()-transformed/power/boxCox/ yeoJohnson parameters, '0.5*abs(est)' for additive/proportional/ lognormal error parameters, 'abs(1/digamma(est+1))' for factorials, and 'log(abs(est))*abs(est)' for log-scale parameters. May be set explicitly per parameter if these defaults don't apply well.

Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.

this is the factor that the gradient is scaled to before optimizing. This only works with scaleType="nlmixr2".

'rxode2' ODE solving options during fitting, created with 'rxControl()'

Optimize the rxode2 expression to speed up calculation. By default this is turned on.

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.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

Type of additive-plus-proportional error: '"combined1"', where standard deviations add:

y = f + (a + b\times f^c) \times \varepsilon

; or '"combined2"', where variances add:

y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon

. Here y = observed, f = predicted, a = additive sd, b = proportional/power sd, c = power exponent (1 in the proportional case).

Controls how dosing/event-parameter ('alag', 'F', 'rate', 'dur') sensitivities are computed for THETA/ETA gradients: ‘"jump"' (default) uses rxode2’s analytic event sensitivities; '"fd"' uses the legacy finite-difference behavior.

Method used to compute the ODE parameter sensitivities. '"forward"' uses the classic variational (forward) sensitivity ODEs; '"default"' is the same thing.

This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE

Should the object have compressed items

Method for calculating the covariance. "r" (the default) uses nlmixr2's nlmixr2Hess() Hessian; "n1qn1" uses the optimizer's own Hessian; "" skips the covariance step.

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

Confidence level for some tables. By default this is 0.95 or 95% confidence.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

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.

When 'TRUE' (default), bounded parameters are transformed for unbounded optimization methods and back-transformed for final estimates. 'FALSE' optimizes on the original scale with bounds passed to the optimizer. 'NA' transforms for optimization but skips the final back-transform.

Ignored parameters

Number of points for bobyqa's quadratic approximation to the objective; must be in '[n+2, (n+1)(n+2)/2]'. Defaults to '2*n + 1'. (bobyqa)

Initial trust region radius for the bobyqa outer optimizer (with 'rhoend', must satisfy '0 < rhoend < rhobeg'). Default '0.2' (20 'abs(upper-lower)/2'. (bobyqa)

Final trust region radius. If not defined, '10^(-sigdig)' is used. (bobyqa)

Controls amount of printing ('0'=none, '1'=start/end only, '2'=each new rho, '3'=every function evaluation, '>3'=every 'iprint' evaluations). Default '0'.

The maximum allowed number of function evaluations. If this is exceeded, the method will terminate.

return the newuoa output instead of the nlmixr2 fit

The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.

Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.

The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced

When 'TRUE' (default), only subjects whose ODE solve produced NaN/Inf have their tolerances relaxed, and the relaxed tolerance persists across optimizer calls (sticky). When 'FALSE', all subjects have their tolerances relaxed on each retry and tolerances are reset afterward.

Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].

Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.

Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.

Parameter normalization/scaling used to get scaled initial values for scaleType, of the form Vscaled = (Vunscaled-C1)/C2 (see Feature Scaling; rescale2 follows the OptdesX manual): "rescale2" scales all parameters to (-1, 1); "rescale" (min-max) scales to (0, 1); "mean" centers on the mean with range (0, 1); "std" standardizes by mean/sd; "len" scales to unit (Euclidean) length; "constant" performs no normalization (C1=0, C2=1).

The scaling scheme for nlmixr2: "nlmixr2" (default) scales as (current-init)*scaleC[i] + scaleTo, with scaleTo from normType and scales from scaleC; "norm" uses the simple scaling from normType; "mult" scales multiplicatively as current/init*scaleTo; "multAdd" scales linearly ((current-init)+scaleTo) for parameters in an exponential block (e.g. exp(theta)) and multiplicatively otherwise.

Maximum value of the scaleC to prevent overflow.

Minimum value of the scaleC to prevent underflow.

Scaling constant used with scaleType="nlmixr2"; when not specified, chosen by parameter type to keep gradient sizes similar on a log scale: '1' for exp()-transformed/power/boxCox/ yeoJohnson parameters, '0.5*abs(est)' for additive/proportional/ lognormal error parameters, 'abs(1/digamma(est+1))' for factorials, and 'log(abs(est))*abs(est)' for log-scale parameters. May be set explicitly per parameter if these defaults don't apply well.

Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.

'rxode2' ODE solving options during fitting, created with 'rxControl()'

Optimize the rxode2 expression to speed up calculation. By default this is turned on.

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.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

Type of additive-plus-proportional error: '"combined1"', where standard deviations add:

y = f + (a + b\times f^c) \times \varepsilon

; or '"combined2"', where variances add:

y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon

. Here y = observed, f = predicted, a = additive sd, b = proportional/power sd, c = power exponent (1 in the proportional case).

This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE

Should the object have compressed items

Method for calculating the covariance. "r" (the default) uses nlmixr2's nlmixr2Hess() Hessian; "" skips the covariance step.

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

Confidence level for some tables. By default this is 0.95 or 95% confidence.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

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.

When 'TRUE' (default), bounded parameters are transformed for unbounded optimization methods and back-transformed for final estimates. 'FALSE' optimizes on the original scale with bounds passed to the optimizer. 'NA' transforms for optimization but skips the final back-transform.

Controls how dosing/event-parameter ('alag', 'F', 'rate', 'dur') sensitivities are computed for THETA/ETA gradients: ‘"jump"' (default) uses rxode2’s analytic event sensitivities; '"fd"' uses the legacy finite-difference behavior.

Ignored parameters

an estimate of the size of each parameter at the minimum.

an estimate of the size of f at the minimum.

this argument determines the level of printing which is done during the minimization process. The default value of 0 means that no printing occurs, a value of 1 means that initial and final details are printed and a value of 2 means that full tracing information is printed.

the number of significant digits in the function f.

a positive scalar giving the tolerance at which the scaled gradient is considered close enough to zero to terminate the algorithm. The scaled gradient is a measure of the relative change in f in each direction p[i] divided by the relative change in p[i].

a positive scalar which gives the maximum allowable scaled step length. stepmax is used to prevent steps which would cause the optimization function to overflow, to prevent the algorithm from leaving the area of interest in parameter space, or to detect divergence in the algorithm. stepmax would be chosen small enough to prevent the first two of these occurrences, but should be larger than any anticipated reasonable step.

A positive scalar providing the minimum allowable relative step length.

a positive integer specifying the maximum number of iterations to be performed before the program is terminated.

a logical scalar specifying whether the analytic gradients and Hessians, if they are supplied, should be checked against numerical derivatives at the initial parameter values. This can help detect incorrectly formulated gradients or Hessians.

is a logical that allows a return of the 'nlm' object

controls whether ‘nlm' uses nlmixr2’s analytical gradients (event-related parameters like lag time/duration/rate/F use Shi2021 finite differences instead): '"hessian"' builds a Hessian from the analytical gradient via finite differences, '"gradient"' supplies the gradient and lets 'nlm' compute the finite-difference Hessian, and '"fun"' lets 'nlm' compute both by finite differences.

The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.

Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.

The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced

When 'TRUE' (default), only subjects whose ODE solve produced NaN/Inf have their tolerances relaxed, and the relaxed tolerance persists across optimizer calls (sticky). When 'FALSE', all subjects have their tolerances relaxed on each retry and tolerances are reset afterward.

Event gradient type for dosing events; Can be "central" or "forward"

This represents the epsilon when optimizing the ideal step size for numeric differentiation using the Shi2021 method

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)

Hessian type for numeric-difference individual Hessians in generalized log-likelihood estimation: "central" (matches R's 'optimHess()', default) or "forward" (faster).

This represents the epsilon when optimizing the Hessian step size using the Shi2021 method.

Maximum number of times to optimize the best step size for the hessian calculation

Treatment of the second derivative for censored (M2/M3/M4/BLQ) observations in the FOCEI family. "gauss" (the default) keeps the historic uncensored Gauss-Newton curvature, matching common PMx tools; "laplace" uses the exact censored second derivative of the objective (a proper Laplace inner Hessian and analytic covariance). Accepted by saemControl/nlmControl for a uniform interface but inert there – SAEM (stochastic EM) has no Laplace inner Hessian, and NLM uses a finite-difference Hessian that already reflects censoring exactly.

Controls how dosing/event-parameter ('alag', 'F', 'rate', 'dur') sensitivities are computed for THETA/ETA gradients: ‘"jump"' (default) uses rxode2’s analytic event sensitivities; '"fd"' uses the legacy finite-difference behavior.

Method used to compute the ODE parameter sensitivities. '"forward"' uses the classic variational (forward) sensitivity ODEs; '"default"' is the same thing.

Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].

Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.

Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.

Parameter normalization/scaling used to get scaled initial values for scaleType, of the form Vscaled = (Vunscaled-C1)/C2 (see Feature Scaling; rescale2 follows the OptdesX manual): "rescale2" scales all parameters to (-1, 1); "rescale" (min-max) scales to (0, 1); "mean" centers on the mean with range (0, 1); "std" standardizes by mean/sd; "len" scales to unit (Euclidean) length; "constant" performs no normalization (C1=0, C2=1).

The scaling scheme for nlmixr2: "nlmixr2" (default) scales as (current-init)*scaleC[i] + scaleTo, with scaleTo from normType and scales from scaleC; "norm" uses the simple scaling from normType; "mult" scales multiplicatively as current/init*scaleTo; "multAdd" scales linearly ((current-init)+scaleTo) for parameters in an exponential block (e.g. exp(theta)) and multiplicatively otherwise.

Maximum value of the scaleC to prevent overflow.

Minimum value of the scaleC to prevent underflow.

Scaling constant used with scaleType="nlmixr2"; when not specified, chosen by parameter type to keep gradient sizes similar on a log scale: '1' for exp()-transformed/power/boxCox/ yeoJohnson parameters, '0.5*abs(est)' for additive/proportional/ lognormal error parameters, 'abs(1/digamma(est+1))' for factorials, and 'log(abs(est))*abs(est)' for log-scale parameters. May be set explicitly per parameter if these defaults don't apply well.

Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.

this is the factor that the gradient is scaled to before optimizing. This only works with scaleType="nlmixr2".

'rxode2' ODE solving options during fitting, created with 'rxControl()'

Optimize the rxode2 expression to speed up calculation. By default this is turned on.

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.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

Type of additive-plus-proportional error: '"combined1"', where standard deviations add:

y = f + (a + b\times f^c) \times \varepsilon

; or '"combined2"', where variances add:

y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon

. Here y = observed, f = predicted, a = additive sd, b = proportional/power sd, c = power exponent (1 in the proportional case).

This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE

Should the object have compressed items

"r" uses nlmixr2's 'nlmixr2Hess()' for the hessian, or "nlm" uses the hessian from 'stats::nlm(.., hessian=TRUE)'; defaults to "nlm" when using nlmixr2's hessian/gradient for solving.

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

Confidence level for some tables. By default this is 0.95 or 95% confidence.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

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.

When 'TRUE' (default), bounded parameters are transformed for unbounded optimization methods and back-transformed for final estimates. 'FALSE' optimizes on the original scale with bounds passed to the optimizer. 'NA' transforms for optimization but skips the final back-transform.

additional arguments to be passed to f.

When TRUE (default) also print the final iteration line.

A nsub x ntheta matrix of per-subject parameter values. Row id is solved against subject id (in the loaded etTrans order).

When TRUE, record this evaluation's population parameter estimate – the per-subject mean of thetaMat's columns (phi = beta + b averaged over subjects, which equals the fixed effect exactly for parameters without a random effect) – into the resident nlm parameter history via the shared scale machinery. This is how an external optimizer (e.g. lme4::nlmer) populates the iteration print and the history recovered by nlmGetParHist(). No objective value is recorded (the scale's showOfv is expected to be 0 for these engines). Defaults to FALSE.

Maximum number of evaluations of the objective function allowed. Defaults to 200.

Maximum number of iterations allowed. Defaults to 150.

The value of the objective function and the parameters is printed every trace'th iteration. When 0 no trace information is to be printed

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

Relative tolerance. When 'NULL' (default) it is derived from 'sigdig' the way 'foceiControl()' does ('10^(-sigdig)').

X tolerance. When 'NULL' (default) it is derived from 'sigdig' ('10^(-sigdig)').

false convergence tolerance. Defaults to '2.2e-14'.

Minimum step size. Default to '1.'.

Maximum step size. Default to '1.'.

singular convergence tolerance; defaults to 'rel.tol;.

See PORT documentation (or leave alone).

... probably need to check PORT documentation

an estimated bound on the relative error in the objective function value

'rxode2' ODE solving options during fitting, created with 'rxControl()'

Optimize the rxode2 expression to speed up calculation. By default this is turned on.

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.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

logical; when TRUE this will return the nlminb result instead of the nlmixr2 fit object

controls whether ‘nlm' uses nlmixr2’s analytical gradients (event-related parameters like lag time/duration/rate/F use Shi2021 finite differences instead): '"hessian"' builds a Hessian from the analytical gradient via finite differences, '"gradient"' supplies the gradient and lets 'nlm' compute the finite-difference Hessian, and '"fun"' lets 'nlm' compute both by finite differences.

The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.

Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.

The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced

When 'TRUE' (default), only subjects whose ODE solve produced NaN/Inf have their tolerances relaxed, and the relaxed tolerance persists across optimizer calls (sticky). When 'FALSE', all subjects have their tolerances relaxed on each retry and tolerances are reset afterward.

Event gradient type for dosing events; Can be "central" or "forward"

This represents the epsilon when optimizing the ideal step size for numeric differentiation using the Shi2021 method

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)

Hessian type for numeric-difference individual Hessians in generalized log-likelihood estimation: "central" (matches R's 'optimHess()', default) or "forward" (faster).

This represents the epsilon when optimizing the Hessian step size using the Shi2021 method.

Maximum number of times to optimize the best step size for the hessian calculation

Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].

Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.

Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.

Parameter normalization/scaling used to get scaled initial values for scaleType, of the form Vscaled = (Vunscaled-C1)/C2 (see Feature Scaling; rescale2 follows the OptdesX manual): "rescale2" scales all parameters to (-1, 1); "rescale" (min-max) scales to (0, 1); "mean" centers on the mean with range (0, 1); "std" standardizes by mean/sd; "len" scales to unit (Euclidean) length; "constant" performs no normalization (C1=0, C2=1).

The scaling scheme for nlmixr2: "nlmixr2" (default) scales as (current-init)*scaleC[i] + scaleTo, with scaleTo from normType and scales from scaleC; "norm" uses the simple scaling from normType; "mult" scales multiplicatively as current/init*scaleTo; "multAdd" scales linearly ((current-init)+scaleTo) for parameters in an exponential block (e.g. exp(theta)) and multiplicatively otherwise.

Maximum value of the scaleC to prevent overflow.

Minimum value of the scaleC to prevent underflow.

Scaling constant used with scaleType="nlmixr2"; when not specified, chosen by parameter type to keep gradient sizes similar on a log scale: '1' for exp()-transformed/power/boxCox/ yeoJohnson parameters, '0.5*abs(est)' for additive/proportional/ lognormal error parameters, 'abs(1/digamma(est+1))' for factorials, and 'log(abs(est))*abs(est)' for log-scale parameters. May be set explicitly per parameter if these defaults don't apply well.

Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.

this is the factor that the gradient is scaled to before optimizing. This only works with scaleType="nlmixr2".

Type of additive-plus-proportional error: '"combined1"', where standard deviations add:

y = f + (a + b\times f^c) \times \varepsilon

; or '"combined2"', where variances add:

y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon

. Here y = observed, f = predicted, a = additive sd, b = proportional/power sd, c = power exponent (1 in the proportional case).

Controls how dosing/event-parameter ('alag', 'F', 'rate', 'dur') sensitivities are computed for THETA/ETA gradients: ‘"jump"' (default) uses rxode2’s analytic event sensitivities; '"fd"' uses the legacy finite-difference behavior.

Method used to compute the ODE parameter sensitivities. '"forward"' uses the classic variational (forward) sensitivity ODEs; '"default"' is the same thing.

This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE

Should the object have compressed items

Method for calculating the covariance. "r" (the default) uses nlmixr2's nlmixr2Hess() Hessian; "nlminb" uses the optimizer's own Hessian; "" skips the covariance step.

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

Confidence level for some tables. By default this is 0.95 or 95% confidence.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

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.

Fitted object or function specifying the model.

nlmixr data

estimation method (all methods are shown by 'nlmixr2AllEst()'). Methods can be added for other tools

The estimation control object. These are expected to be different for each type of estimation method

The output table control object (like 'tableControl()')

Other parameters

Boolean to save a nlmixr2 object in a rds file in the working directory. If NULL, uses option "nlmixr2.save"

Environment where the nlmixr object/function is evaluated before running the estimation routine.

Nlmixr2 fit object

specifies the interpolation method for time-varying covariates. When solving ODEs it often samples times outside the sampling time specified in events. When this happens, the time varying covariates are interpolated. Currently this can be:

• "linear" interpolation, which interpolates the covariate by solving the line between the observed covariates and extrapolating the new covariate value.

• "locf" – Last observation carried forward (the default).

• "nocb" – Next Observation Carried Backward. This is the same method that NONMEM uses.

• "midpoint" Last observation carried forward to midpoint; Next observation carried backward to midpoint.

  For time-varying covariates where a missing value is present, the interpolation method will use either "locf" or "nocb" throughout if they are the type of covariate interpolation that is selected.

  When using the linear or midpoint interpolation, the lower point in the interpolation will use locf to interpolate missing covariates and the upper point will use the nocb to interpolate missing covariates.

an optional lower limit for the primary covariate. Defaults to min(primary).

an optional upper limit for the primary covariate. Defaults to max(primary).

an optional integer with the number of primary covariate values at which to evaluate the predictions. Defaults to 51.

some methods for the generic may require additional arguments.

a fitted model object from which predictions can be extracted, using a predict method.

an optional one-sided formula specifying the primary covariate to be used to generate the augmented predictions. By default, if a covariate can be extracted from the data used to generate object (using getCovariate), it will be used as primary.

This is the UI that will be used for the translation

This has the data

focei control for data creation

Table options

Environment setup which needs the following: - '$table' for table options - '$origData' – Original Data - '$dataSav' – Processed data from .foceiPreProcessData - '$idLvl' – Level information for ID factor added - '$covLvl' – Level information for items to convert to factor - '$ui' for ui object - '$fullTheta' Full theta information - '$etaObf' data frame with ID, etas and OBJI - '$cov' For covariance - '$covMethod' for the method of calculating the covariance - '$adjObf' Should the objective function value be adjusted - '$objective' objective function value - '$extra' Extra print information - '$method' Estimation method (for printing) - '$omega' Omega matrix - '$theta' Is a theta data frame - '$model' a list of model information for table generation. Needs a 'predOnly' model - '$message' Message for display - '$est' estimation method - '$ofvType' (optional) tells the type of ofv is currently being use

There are some more details that need to be described here

Estimation method

Environment for the nlmixr2 estimation routines.

This needs to have:

- rxode2 ui object in '$ui'

- data to fit in the estimation routine in '$data'

- control for the estimation routine's control options in '$ui'

Other arguments provided to 'nlmixr2Est()' provided for flexibility but not currently used inside nlmixr

for the internal functions theta is the parameter values

the md5 identifier for the internal gradient function information.

either a function or a non-empty character string naming the function to be called.

an environment within which to evaluate the call. This will be most useful if what is a character string and the arguments are symbols or quoted expressions.

Which parameters to calculate the forward difference and optimal forward difference interval

Names for the theta parameters

The relative tolerance used for Gill 1983 determination of optimal step size.

Max steps to determine the optimal forward/central difference step size per parameter (Gill 1983). '0' = no optimal step size determined.

When looking for the optimal forward difference step size, this is This is the step size to increase the initial estimate by. So each iteration the new step size = (prior step size)*gillStep

The gillFtol is the gradient error tolerance that is acceptable before issuing a warning/error about the gradient estimates.

Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].

Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.

Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.

either a function or a non-empty character string naming the function to be called.

a list of arguments to the function call. The names attribute of args gives the argument names.

an environment within which to evaluate the call. This will be most useful if what is a character string and the arguments are symbols or quoted expressions.

Which parameters to calculate the forward difference and optimal forward difference interval

The relative tolerance used for Gill 1983 determination of optimal step size.

Max steps to determine the optimal forward/central difference step size per parameter (Gill 1983). '0' = no optimal step size determined.

When looking for the optimal forward difference step size, this is This is the step size to increase the initial estimate by. So each iteration the new step size = (prior step size)*gillStep

The gillFtol is the gradient error tolerance that is acceptable before issuing a warning/error about the gradient estimates.

Initial values for the parameters to be optimized over.

A function to be minimized (or maximized), with first argument the vector of parameters over which minimization is to take place. It should return a scalar result.

Extra arguments sent to nlmixr2Gill83

an environment within which to evaluate the call. This will be most useful if what is a character string and the arguments are symbols or quoted expressions.

String to print

Version information (by default use package version)

maximum number of iterations for the nlme optimization algorithm. Default is 50.

maximum number of iterations for the PNLS optimization step inside the nlme optimization. Default is 7.

maximum number of iterations for nlminb (iter.max) or the nlm (iterlim, from the 10-th step) optimization step inside the nlme optimization. Default is 50 (which may be too small for e.g. for overparametrized cases).

minimum factor by which to shrink the default step size in an attempt to decrease the sum of squares in the PNLS step. Default 0.001.

tolerance for the convergence criterion in the nlme algorithm. Default is 1e-6.

number of iterations for the EM algorithm used to refine the initial estimates of the random effects variance-covariance coefficients. Default is 25.

tolerance for the convergence criterion in PNLS step. Default is 1e-3.

tolerance for the convergence criterion in nlm, passed as the gradtol argument to the function (see documentation on nlm). Default is 1e-7.

a logical value indicating whether the fitted object should be returned when the maximum number of iterations is reached without convergence of the algorithm. Default is FALSE.

a logical value passed as the trace to nlminb(.., control= list(trace = *, ..)) or as argument print.level to nlm(). Default is FALSE.

logical indicating if a warning should be signalled whenever the minimization (by opt) in the LME step does not converge; defaults to TRUE.

a logical value indicating whether numerical gradient vectors and Hessian matrices of the log-likelihood function should be used in the nlm optimization. This option is only available when the correlation structure (corStruct) and the variance function structure (varFunc) have no "varying" parameters and the pdMat classes used in the random effects structure are pdSymm (general positive-definite), pdDiag (diagonal), pdIdent (multiple of the identity), or pdCompSymm (compound symmetry). Default is TRUE.

a logical value indicating whether the approximate covariance matrix of the variance-covariance parameters should be calculated. Default is TRUE.

relative step for numerical derivatives calculations. Default is .Machine$double.eps^(1/3).

numeric value - minimum absolute parameter value in the approximate variance calculation. The default is 0.05.

the optimizer to be used, either "nlminb" (the default) or "nlm".

a logical value indicating whether the pdNatural parametrization should be used for general positive-definite matrices (pdSymm) in reStruct, when the approximate covariance matrix of the estimators is calculated. Default is TRUE.

optionally a positive number to fix the residual error at. If NULL, as by default, or 0, sigma is estimated.

Optimize the rxode2 expression to speed up calculation. By default this is turned on.

boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.

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.

'rxode2' ODE solving options during fitting, created with 'rxControl()'

a character string. If "REML" the model is fit by maximizing the restricted log-likelihood. If "ML" the log-likelihood is maximized. Defaults to "ML".

optionally, any of the following: (i) a two-sided formula of the form r1+...+rn~x1+...+xm | g1/.../gQ, with r1,...,rn naming parameters included on the right hand side of model, x1+...+xm specifying the random-effects model for these parameters and g1/.../gQ the grouping structure (Q may be equal to 1, in which case no / is required). The random effects formula will be repeated for all levels of grouping, in the case of multiple levels of grouping; (ii) a two-sided formula of the form r1+...+rn~x1+..+xm, a list of two-sided formulas of the form r1~x1+...+xm, with possibly different random-effects models for different parameters, a pdMat object with a two-sided formula, or list of two-sided formulas (i.e. a non-NULL value for formula(random)), or a list of pdMat objects with two-sided formulas, or lists of two-sided formulas. In this case, the grouping structure formula will be given in groups, or derived from the data used to fit the nonlinear mixed-effects model, which should inherit from class groupedData,; (iii) a named list of formulas, lists of formulas, or pdMat objects as in (ii), with the grouping factors as names. The order of nesting will be assumed the same as the order of the order of the elements in the list; (iv) an reStruct object. See the documentation on pdClasses for a description of the available pdMat classes. Defaults to fixed, resulting in all fixed effects having also random effects.

a two-sided linear formula of the form f1+...+fn~x1+...+xm, or a list of two-sided formulas of the form f1~x1+...+xm, with possibly different models for different parameters. The f1,...,fn are the names of parameters included on the right hand side of model and the x1+...+xm expressions define linear models for these parameters (when the left hand side of the formula contains several parameters, they all are assumed to follow the same linear model, described by the right hand side expression). A 1 on the right hand side of the formula(s) indicates a single fixed effects for the corresponding parameter(s).

an optional varFunc object or one-sided formula describing the within-group heteroscedasticity structure. If given as a formula, it is used as the argument to varFixed, corresponding to fixed variance weights. See the documentation on varClasses for a description of the available varFunc classes. Defaults to NULL, corresponding to homoscedastic within-group errors.

an optional logical value. If TRUE information on the evolution of the iterative algorithm is printed. Default is FALSE.

Returns the nlme object instead of the nlmixr object (by default FALSE). If any of the nlme specific options of 'random', 'fixed', 'sens', the nlme object is returned

Type of additive-plus-proportional error: '"combined1"', where standard deviations add:

y = f + (a + b\times f^c) \times \varepsilon

; or '"combined2"', where variances add:

y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon

. Here y = observed, f = predicted, a = additive sd, b = proportional/power sd, c = power exponent (1 in the proportional case).

This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE

Should the object have compressed items

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

Confidence level for some tables. By default this is 0.95 or 95% confidence.

Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.

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.

When 'TRUE' (default), algebraic expressions that can be mu-referenced are internally rewritten as mu-referenced covariates and restored after optimization. Mirrors saemControl(muRefCovAlg=)/nlmeControl(muRefCovAlg=); for foceiControl() only takes effect when muModel != "none".

Controls how dosing/event-parameter ('alag', 'F', 'rate', 'dur') sensitivities are computed for THETA/ETA gradients: ‘"jump"' (default) uses rxode2’s analytic event sensitivities; '"fd"' uses the legacy finite-difference behavior.

Convenience alias for the shared nlmixr 'print' control. 'nlme' prints progress through its own 'verbose' option, so 'print' maps to it: 'print=0' runs quietly ('verbose=FALSE') and any positive value is verbose ('verbose=TRUE'). When 'print' is not supplied an explicit 'verbose' is used as given.

Covariance method: '"analytic"' (default) computes the focei observed-information covariance at the converged nlme estimates post-fit (falling back to the finite-difference '"r,s"' -> '"r"'/'"s"' chain when out of analytic scope); '"r,s"', '"r"', '"s"' request the finite-difference forms directly; '"nlme"' and '""' skip the recompute and keep nlme's own standard errors. When the recompute fails the '"nlme"' covariance is kept.

Further, named control arguments to be passed to nlminb (apart from trace and iter.max mentioned above), where used (eval.max and those from abs.tol down).

object to print

Other things output

of test to be run

when 'TRUE' skip the test on CRAN.

nlmixr2 fit object from a different version of nlmixr2.

estimated value

nlmixr fit object

nlmixr objective function data frame which has column names "OBJF", "AIC", "BIC", "Log-likelihood" and "Condition#(Cov)" "Condition#(Cor)"

Objective Function Type

Eta objective function table to add (with focei) to give focei objective function

nlmixr2 object

string of the timing name

time (in seconds)

nlmixr fit

data to cbind to nlmixr fit

nlmixr fit

nlmixr2 fit object to update in the environment

Name of the object

Environment to search

Original fit$env to compare, otherwise simply use fit$env

Name of the timing to be integrated

Code to be evaluated and timed

nlmixr2 fit data, fit environment, or NULL (timing is added when the fit is finalized); supply this if called after a fit already exists

A positive integer specifying the maximum number of iterations allowed.

A positive numeric value specifying the tolerance level for the relative offset convergence criterion.

A positive numeric value specifying the minimum step-size factor allowed on any step in the iteration. The increment is calculated with a Gauss-Newton algorithm and successively halved until the residual sum of squares has been decreased or until the step-size factor has been reduced below this limit.

a logical specifying whether the number of evaluations (steps in the gradient direction taken each iteration) is printed.

a logical specifying whether nls() should return instead of signalling an error in the case of termination before convergence. Termination before convergence happens upon completion of maxiter iterations, in the case of a singular gradient, and in the case that the step-size factor is reduced below minFactor.

a constant to be added to the denominator of the relative offset convergence criterion calculation to avoid a zero divide in the case where the fit of a model to data is very close. The default value of 0 keeps the legacy behaviour of nls(). A value such as 1 seems to work for problems of reasonable scale with very small residuals.

only when numerical derivatives are used: logical indicating if central differences should be employed, i.e., numericDeriv(*, central=TRUE) be used.

character string specifying the algorithm to use. The default algorithm is a Gauss-Newton algorithm. Other possible values are "plinear" for the Golub-Pereyra algorithm for partially linear least-squares models and "port" for the ‘nl2sol’ algorithm from the Port library – see the references. Can be abbreviated.

non-negative numeric. Termination occurs when both the actual and predicted relative reductions in the sum of squares are at most ftol. Therefore, ftol measures the relative error desired in the sum of squares.

non-negative numeric. Termination occurs when the relative error between two consecutive iterates is at most ptol. Therefore, ptol measures the relative error desired in the approximate solution.

non-negative numeric. Termination occurs when the cosine of the angle between result of fn evaluation fvec and any column of the Jacobian is at most gtol in absolute value. Therefore, gtol measures the orthogonality desired between the function vector and the columns of the Jacobian.

a list or numeric vector containing positive entries that serve as multiplicative scale factors for the parameters. Length of diag should be equal to that of par. If not, user-provided diag is ignored and diag is internally set.