Use to define engine parameters for model execution.
engineParams(
model,
sort = NULL,
ODE = "MatrixExponent",
rtolODE = 1e-06,
atolODE = 1e-06,
maxStepsODE = 50000,
numIterations = 1000,
method = NULL,
stdErr = NULL,
isCentralDiffStdErr = TRUE,
stepSizeStdErr = NULL,
logTransform = NULL,
numIntegratePtsAGQ = 1,
numIterNonParametric = 0,
allowSyntheticGradient = FALSE,
fastOptimization = FALSE,
numIterMAPNP = 0,
numRepPCWRES = 0,
stepSizeLinearize = 0.002,
numDigitLaplacian = 7,
numDigitBlup = 13,
gradTolOuter = 2e-04,
stepTolOuter = 1e-04,
gradTolInner = 1.71e-05,
stepTolInner = 7.07e-08,
refDeltaLagl = 0.001,
mapAssist = 0,
iSample = 300,
iAcceptRatio = 0.1,
impDist = "Normal",
tDOF = 4,
numSampleSIR = 10,
numBurnIn = 0,
freezeOmega = FALSE,
MCPEM = FALSE,
runAllIterations = FALSE,
scramble = "Owen",
emTolType = 0,
emConvLen = 10,
emConvCritVal = 5,
stepSizePartialDeriv = 1e-05,
numTimeStepPartialDeriv = 20
)List of engine parameters to be used during fitting or simulation
Model object. The type of model (population or individual) is determined by the model@isPopulation slot. If model@isPopulation is TRUE, the model is treated as a population model; otherwise, it's treated as an individual model.
Logical; Specifies whether to sort the input data by subject and
time. If TRUE, data are sorted. If FALSE, data are not
sorted. Defaults to FALSE if the model contains reset information
(model@hasResetInfo = TRUE); otherwise, defaults to TRUE.
Character; Specifies the ODE solver to be used. Options are:
"MatrixExponent", "DVERK", "DOPRI5",
"AutoDetect", "Stiff", "LSODE". See Details section
for a description of each solver.
Numeric; Specifying relative tolerance for the numerical ODE solver.
Numeric; Specifying absolute tolerance for the numerical ODE solver.
Numeric; Specifies the maximum number of steps allowed for the ODE solver.
Integer; Specifies the maximum number of iterations for the estimation algorithm. Must be a non-negative integer, with a maximum value of 10000.
Character; Specifies the estimation method. For population
models, options are: "QRPEM", "IT2S-EM", "FOCE-LB",
"FO", "FOCE-ELS", "Laplacian", and
"Naive-Pooled". For individual models, only "Naive-Pooled" is
available. The default for population models depends on model
characteristics:
If the model includes discontinuous observed variables (e.g., count data),
Below Quantifiable Limit (BQL) data, or has no unfrozen sigmas, the default is "Laplacian".
Otherwise, the default is "FOCE-ELS".
Character; Specifies the method for standard error computations. Options vary depending on the model type and estimation method:
Individual models: "Hessian" (default) or "None".
Population models with method = "QRPEM": "Fisher-Score" (default) or "None".
Population models with method = "IT2S-EM": "None" only.
Population models with method in c("FOCE-LB", "FO", "FOCE-ELS", "Laplacian", "Naive-Pooled"):
"Sandwich" (default), "Hessian", "Fisher-Score", "Auto-Detect", or "None".
"None" means that standard error calculations are not performed.
Logical; If TRUE (default), uses central
difference for standard error calculations when applicable. If
FALSE, uses forward difference.
Numeric; Specifies the relative step size used for the
numerical computation of the Hessian matrix during standard error
calculations. If not specified, a default value is used (0.001 for
"Naive-Pooled" method, and 0.01 otherwise).
Logical or NULL; Controls log-transformation behavior, particularly for models with a LogAdditive residual error (e.g., C*exp(epsilon)). The internal engine parameter 'logtran' is set based on this argument and specific model characteristics as detailed below.
NULL (default) or TRUE: When the model has exactly
one residual error model and it is LogAdditive, this setting enables
Log-Transform Both Sides (LTBS). In LTBS, predictions and observations
are log-transformed, and the model is fit in the log-domain. This
results in the internal `logtran` engine parameter being set to 1.
FALSE: When the model has exactly one residual error model
and it is LogAdditive, this setting results in the LogAdditive error
being treated as a proportional/multiplicative error during fitting
(by neglecting third and higher-order terms in the Taylor expansion
of exp(epsilon)). This sets the internal `logtran` engine parameter
to 0. For simulation, the error is treated as exp(epsilon).
For other model configurations, the `logtran` parameter is determined as follows:
If there are multiple residual error models or no residual error models, `logtran` is set to 0, irrespective of the `logTransform` value. (In the case of multiple errors, any LogAdditive errors present are treated as proportional).
If there is a single residual error model that is not LogAdditive:
For built-in models: `logtran` is set to 0.
For textual models: `logtran` reflects the `logTransform` setting (it becomes 1 if `logTransform` is `NULL` or `TRUE`, and 0 if `logTransform` is `FALSE`). A warning is issued if `logTransform` is `NULL` or `TRUE` in this scenario, highlighting that LTBS is typically for LogAdditive errors and that error type identification can be challenging in textual models.
Integer; Specifies the number of quadrature points
per dimension to use for Adaptive Gaussian Quadrature (AGQ). Only
applicable to population models when method is "FOCE-ELS" or
"Laplacian".
1: Standard FOCE-ELS/LAPLACIAN computation (no AGQ).
>1: AGQ is performed. The total number of quadrature points used is (number of ETAs)^numIntegratePtsAGQ.
Integer; Controls non-parametric (NP) optimization.
0: Disables NP optimization.
1: Enables NONMEM-style NP optimization using posthoc estimates as support points.
>1: Enables an evolutionary NP algorithm, using numIterNonParametric as the number of generations.
Only applicable to population models when method is not
"Naive-Pooled".
Deprecated.
Logical; Controls the differentiation method used
during the optimization of random effects (etas). If TRUE, automatic
differentiation is used where possible. If FALSE, a finite
difference approach is used. Only applicable to population models when
method is "FOCE-ELS" or "Laplacian".
Integer; Specifies the number of iterations for a
preliminary Naive-Pooled (NP) optimization run before the main estimation.
Applicable when the method is not "NAIVE-POOLED".
Integer; Specifies the number of replicates to generate
for Population Conditional Weighted Residuals (PCWRES) calculations.
Setting this value to 0 disables PCWRES computation. Only applicable to
population models when method is not set to "Naive-Pooled".
Numeric; Specifies the relative step size for numerical differentiation during model linearization.
Numeric; Specifies the optimization accuracy
(NDIGIT) for the outer loop (thetas and sigmas) when using
"FOCE-ELS" or "Laplacian" methods. Only applicable to
population models.
Numeric; Specifies the optimization accuracy (NDIGIT) for
the inner loop (optimization of etas). Also applies to the single
optimization loop in the "NAIVE-POOLED" method.
Numeric; maximum gradient tolerance for the outer loop (Theta/Omega/Sigma optimization) of "FOCE-ELS" or "Laplacian" method. This tolerance controls how close the gradient must be to zero before the outer optimization is considered converged.
Numeric; maximum step tolerance for the outer loop (Theta/Omega/Sigma optimization) of "FOCE-ELS" or "Laplacian" method. This measures the relative change in the solution vector between iterations.
Numeric; maximum gradient tolerance for the inner loop (Eta optimization) of "FOCE-ELS" or "Laplacian" method. A smaller value forces the algorithm to iterate until a very small gradient is achieved.
Numeric; maximum step tolerance for the inner loop (Eta optimization) of "FOCE-ELS" or "Laplacian" method. This determines when the algorithm will terminate based on minimal changes in the solution vector.
Numeric; tolerance for the change in the log-likelihood (LL) value during outer loop optimization of "FOCE-ELS" or "Laplacian" method. This parameter is used to check convergence by comparing the absolute change in LL between major iterations. If the change in LL is less than refDeltaLagl and the optimization driver returns a specific termination code, the algorithm considers the solution sufficiently converged. This tolerance helps to avoid unnecessary iterations when improvements in LL become marginal.
Numeric; Controls the use of MAP assistance in the QRPEM algorithm.
0: No MAP assistance.
>0: The inner ETAs optimization loop is used in the QRPEM outer
optimization loop with a periodicity equal to the value of mapAssist.
Only applicable to population models with method = "QRPEM".
Numeric; Specifies the number of sample points used in the
QRPEM algorithm. Only applicable to population models with method =
"QRPEM".
Numeric; Specifies the acceptance ratio used in the QRPEM
algorithm for scaling the covariance matrix. Only applicable to population
models with method = "QRPEM".
Character; Specifies the importance sampling distribution used
in the QRPEM algorithm. Options are: "Normal",
"DoubleExponential", "Direct", "T",
"Mixture-2", "Mixture-3". Only applicable to population
models with method = "QRPEM". See Details for further information.
Numeric; Specifies the degrees of freedom for the multivariate T
distribution used in importance sampling. Only applicable when method
= "QRPEM" and impDist = "T". Must be between 3 and 30.
Numeric; Specifies the number of samples per eta per
subject used in the Sampling Importance Resampling (SIR) algorithm within
QRPEM. Only applicable to population models with method = "QRPEM".
Numeric; Specifies the number of burn-in iterations in the
QRPEM algorithm. During burn-in, omegas can be frozen (see
freezeOmega parameter). Only applicable to population models with
method = "QRPEM".
Logical; Set to TRUE to freeze Omega but not Theta
for the number of iterations specified in the numBurnIn. Only
applicable to population models with method = "QRPEM".
Logical; Controls the sampling method used in the QRPEM algorithm.
FALSE: Quasi-Random sampling.
TRUE: Monte-Carlo sampling.
Only applicable to population models with method = "QRPEM".
Logical; Set to TRUE to execute all requested
iterations specified in numIterations. Only applicable to population
models with method = "QRPEM".
Character; Specifies the scrambling method for quasi-random
number generation in the QRPEM algorithm. Options are: "None",
"Owen", "Faure-Tezuka". Only applicable to population models
with method = "QRPEM".
Numeric; QRPEM convergence check type. Options:
0: Default (no rollout, LL & Theta and Sigma).
1: LL & All Population Params (Theta, Omega, and Sigma) with rollout.
2: LL with rollout.
3: All Population Params with rollout.
Only applicable to population models with method = "QRPEM".
Numeric; number of iterations over which convergence is checked in the QRPEM method. Only applicable to population models with method = "QRPEM" and emTolType being nonzero.
Numeric; critical value used in the QRPEM convergence check. It specifies the threshold improvement required to continue iterating. Only applicable to population models with method = "QRPEM" and emTolType being nonzero.
Numeric; Specifying the step size used to numerically calculate the partial derivatives of observed variables with respect to parameters. Only applicable to individual models.
Numeric; Specifying the number of time steps used to output the partial derivatives of observed variables with respect to parameters. Only applicable to individual models.
Both "DVERK" and "DOPRI5" are non-stiff solvers.
"AutoDetect" represents LSODA solver implemenation, which solves the
initial value problem for stiff or nonstiff systems of first order ordinary
differential equations. "Stiff" is a LSODE (Livermore solver). It is
best suited for stiff problems. "MatrixExponent" is a matrix
exponential solver.
For the QRPEM method, the impDist parameter controls the importance
sampling distribution. The ximpsampdof slot in the internal
NlmeEngineExtraParams object is set based on impDist as
follows:
"Normal": ximpsampdof = 0
"DoubleExponential": ximpsampdof = 1
"Direct": ximpsampdof = 2
"T": ximpsampdof is set to the value of tDOF.
"Mixture-2": ximpsampdof = -2
"Mixture-3": ximpsampdof = -3