Skip to contents

Main function to specify engine parameters

engineParams.Rd

Use to define engine parameters for model execution.

Usage

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
)

Arguments

model

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.

sort

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.

ODE

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.

rtolODE

Numeric; Specifying relative tolerance for the numerical ODE solver.

atolODE

Numeric; Specifying absolute tolerance for the numerical ODE solver.

maxStepsODE

Numeric; Specifies the maximum number of steps allowed for the ODE solver.

numIterations

Integer; Specifies the maximum number of iterations for the estimation algorithm. Must be a non-negative integer, with a maximum value of 10000.

method

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".

stdErr

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.

isCentralDiffStdErr

Logical; If TRUE (default), uses central difference for standard error calculations when applicable. If FALSE, uses forward difference.

stepSizeStdErr

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).

logTransform

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.

numIntegratePtsAGQ

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.

numIterNonParametric

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".

allowSyntheticGradient

Deprecated.

fastOptimization

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".

numIterMAPNP

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".

numRepPCWRES

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".

stepSizeLinearize

Numeric; Specifies the relative step size for numerical differentiation during model linearization.

numDigitLaplacian

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.

numDigitBlup

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.

gradTolOuter

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.

stepTolOuter

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.

gradTolInner

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.

stepTolInner

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.

refDeltaLagl

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.

mapAssist

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".

iSample

Numeric; Specifies the number of sample points used in the QRPEM algorithm. Only applicable to population models with method = "QRPEM".

iAcceptRatio

Numeric; Specifies the acceptance ratio used in the QRPEM algorithm for scaling the covariance matrix. Only applicable to population models with method = "QRPEM".

impDist

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.

tDOF

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.

numSampleSIR

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".

numBurnIn

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".

freezeOmega

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".

MCPEM

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".

runAllIterations

Logical; Set to TRUE to execute all requested iterations specified in numIterations. Only applicable to population models with method = "QRPEM".

scramble

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".

emTolType

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".

emConvLen

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.

emConvCritVal

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.

stepSizePartialDeriv

Numeric; Specifying the step size used to numerically calculate the partial derivatives of observed variables with respect to parameters. Only applicable to individual models.

numTimeStepPartialDeriv

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.

Value

List of engine parameters to be used during fitting or simulation

Details

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