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,
  conditionNumber = c("CovarianceFixef", "CorrelationFixef", "CovarianceFull",
    "CorrelationFull"),
  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 (LL/multi/count/event), Below Quantifiable Limit (BQL) data, all residual SDs frozen, or no error() statement, FOCE-ELS is unavailable. The default is "Laplacian"; "QRPEM", "IT2S-EM", and "Naive-Pooled" are equally available.

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

conditionNumber

Character; Selects the basis and scope used to compute the reported condition number when standard errors are produced. One of:

"CovarianceFixef"

(Default) Covariance matrix of the estimated fixed effects only.

"CorrelationFixef"

Correlation matrix of the estimated fixed effects only.

"CovarianceFull"

Covariance matrix of all estimated population parameters (fixed effects, standard deviations of residual errors, Omega).

"CorrelationFull"

Correlation matrix of all estimated population parameters. This is the only option directly comparable to the condition number calculated from NONMEM's reported eigenvalues, which are computed over all estimated THETA/OMEGA/SIGMA parameters.

This argument is independent of stdErr: it does not change which standard-error covariance block is computed, only how the reported eigenvalues and condition lines (in the engine's out.txt) are derived from that block. The basis actually used is echoed there as a # conditionNumberBasis = ... comment. See Details for the formulas.

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

Controls the use of Automatic Differentiation (AD) during optimization. Accepts a logical value for backward compatibility or a character string specifying the AD mode. Only applicable to population models when method is "FOCE-ELS" or "Laplacian".

Accepted values:

FALSE

(Default) Disables automatic differentiation. Finite differences are used for all gradient and Hessian computations.

TRUE

Enables inner-loop automatic differentiation (equivalent to "InnerAD"). Provided for backward compatibility.

"InnerAD"

Enables automatic differentiation for the inner optimization loop (random effects / etas).

"OuterAD"

Enables inner-loop AD plus population-level (outer-loop) automatic differentiation.

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

The conditionNumber argument controls both the scope (which parameters) and the basis (covariance vs. correlation) used to derive the reported eigenvalues and condition in the engine's out.txt. Let C be the variance-covariance matrix of the selected parameters, as produced by the standard-error step (Hessian, sandwich, or Fisher-score, selected by stdErr); its diagonal entries are the squared standard errors of the estimates and its off-diagonals are their estimated covariances.

Scope (which parameters make up C):

  • "...Fixef": only the estimated fixed effects.

  • "...Full": all estimated population parameters (fixed effects, standard deviations of residual errors, elements of variance/covariance matrix of the random effects).

Basis (how C is used):

  • "Covariance..." (default scope is Fixef): eigenvalues are those of C directly, and condition = sqrt(lambda_max / lambda_min), where lambda_min and lambda_max are the smallest and largest strictly positive eigenvalues, respectively. This value is scale-dependent: parameters spanning many orders of magnitude (e.g. typical PK fixed effects) inflate it even when the fit is well-conditioned in correlation terms.

  • "Correlation...": C is first normalised to the correlation matrix R = D^(-1/2) * C * D^(-1/2), where D = diag(C) (the parameter variances); reported eigenvalues are those of R and condition = lambda_max / lambda_min. The result is scale-invariant and reflects only the correlation structure of the estimates. If any diagonal of C is non-positive or non-finite the correlation matrix is undefined and both lines are suppressed.

Only "CorrelationFull" matches NONMEM's condition-number scope (all estimated THETA/OMEGA/SIGMA, correlation basis); use it for direct comparison with NONMEM output. The other three options are not NONMEM-comparable.