Skip to contents

Specify engine parameters for model execution

specify_EngineParams.Rd

Use to define extra engine parameters for model execution.

Usage

specify_EngineParams(
  sort = FALSE,
  ODE = c("MatrixExponent", "DVERK", "DOPRI5", "AutoDetect", "Stiff"),
  rtolODE = 1e-06,
  atolODE = 1e-06,
  maxStepsODE = 50000L,
  numIterations = 1000L,
  method = c("FOCE-ELS", "QRPEM", "Laplacian", "Naive-Pooled", "FOCE-LB", "IT2S-EM",
    "FO"),
  stdErr = c("Sandwich", "Auto-Detect", "Hessian", "Fisher-Score", "None"),
  isCentralDiffStdErr = TRUE,
  stepSizeStdErr = 0.01,
  numIntegratePtsAGQ = 1L,
  numIterNonParametric = 0L,
  allowSyntheticGradient = FALSE,
  numIterMAPNP = 0L,
  numRepPCWRES = 0L,
  stepSizeLinearize = 0.002,
  numDigitLaplacian = 7L,
  numDigitBlup = 13L,
  mapAssist = 0L,
  iSample = 300L,
  iAcceptRatio = 0.1,
  impDist = c("Normal", "DoubleExponential", "Direct", "T", "Mixture-2", "Mixture-3"),
  tDOF = 4L,
  numSampleSIR = 10L,
  numBurnIn = 0L,
  freezeOmega = FALSE,
  MCPEM = FALSE,
  runAllIterations = FALSE,
  scramble = c("Owen", "Tezuka-Faur", "None")
)

Arguments

sort

Logical; Specifying whether or not to sort the input data by subject and time values. Default is TRUE.

ODE

Character; Specifying the solver used to numerically solve Ordinary Differential Equations (ODEs). Options are

  • MatrixExponent (the default),

  • DVERK,

  • DOPRI5,

  • AutoDetect,

  • Stiff.

Note: both DVERK and DOPRI5 are non-stiff solvers. NLME will automatically switches to DVERK if ODEs are nonlinear.

rtolODE

Numeric; Specifying relative tolerance for the ODE solver. Not applicable when ODE == MatrixExponent.

atolODE

Numeric; Specifying absolute tolerance for the ODE solver.

maxStepsODE

Numeric; Specifying maximum number of allowable steps or function evaluations for the ODE solver.

numIterations

Numeric; Specifying maximum number of iterations for estimation.

method

Character; Specifying engine method for estimation. Options are:

  • FOCE-ELS (the default),

  • QRPEM,

  • Laplacian,

  • Naive-Pooled,

  • FOCE-LB,

  • IT2S-EM,

  • FO.

Note: if model involves any discontinuous observed variable (e.g., count data) or BQL data, NLME will switch from default method FOCE-ELS to Laplacian.

stdErr

Character; Specifying method for standard error computations. Options are:

  • Auto-Detect (the default),

  • Sandwich,

  • Hessian,

  • Fisher-Score,

  • None.

Here None means that standard error calculations are not performed. Since when method = QRPEM only Fisher-Score standard error type is available in NLME, any selected option except None will reset to stdErr = "Fisher-Score".

isCentralDiffStdErr

Logical; Default TRUE uses central difference for stdErr calculations. Set to FALSE for forward difference method.

stepSizeStdErr

Numeric; Specifying the step size used for stdErr calculations.

numIntegratePtsAGQ

Numeric; Specifying the number of integration points for adaptive Gaussian quadrature (AGQ) algorithm. Only applicable to models with method set to either FOCE-ELS or Laplacian.

numIterNonParametric

Numeric; Specifying the number of iterations to perform non-parametric estimation. Only applicable when method is not set to Naive-Pooled (otherwise ignored).

allowSyntheticGradient

Logical, Set to TRUE to use synthetic gradient during the estimation process. Only applicable to population models when method is not set to Naive-Pooled (otherwise ignored).

numIterMAPNP

Numeric; Specifying the number of iterations to perform Maximum A Posterior (MAP) initial Naive Pooling (NP) run before estimation. Only applicable to population models when method is not set to Naive-Pooled (otherwise ignored).

numRepPCWRES

Numeric; Specifying the number of replicates to generate the PCWRES after the simple estimation. Only applicable to population models when method is not set to Naive-Pooled (otherwise ignored).

stepSizeLinearize

Numeric; Specifying the step size used for numerical differentiation when linearizing the model function during the estimation process.

numDigitLaplacian

Numeric; Specifying the number of significant decimal digits for the Laplacian/ELS algorithm to use to reach convergence.

numDigitBlup

Numeric; Specifying the number of significant decimal digits for the individual estimation to use to reach convergence.

mapAssist

Numeric; Specifying the period used to perform MAP assistance (mapAssist = 0 means that MAP assistance is not performed). Only applicable when method == "QRPEM".

iSample

Numeric; Specifying the number of samples. Only applicable when method == "QRPEM".

iAcceptRatio

Numeric; Specifying the acceptance ratio. Only applicable when method == "QRPEM".

impDist

Character; Specifying the distribution used for important sampling, and options are

  • Normal (the default),

  • DoubleExponential,

  • Direct,

  • T,

  • Mixture-2,

  • Mixture-3.

Only applicable to the model with method = "QRPEM".

tDOF

Numeric; Specifying the degree of freedom (allowed value is between 3 and 30) for T distribution. Only applicable when method =="QRPEM" and impDist == "T".

numSampleSIR

Numeric; Specifying the number of samples per subject used in the Sampling Importance Re-Sampling (SIR) algorithm to determine the number of SIR samples taken from the empirical discrete distribution that approximates the target conditional distribution. Only applicable to population models with method = "QRPEM".

numBurnIn

Numeric; Specifying the number of burn-in iterations to perform at startup to adjust certain internal parameters. 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; Set to TRUE to use Monte-Carlo sampling instead of Quasi-Random. 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; Specifying the quasi-random scrambling method to use, and options are

  • Owen (the default),

  • Tezuka-Faur,

  • None.

Only applicable to population models with method = "QRPEM".

See also

write_ModelTemplateTokens(), specify_SimParams()

Examples

# default
EstArgs <- specify_EngineParams()
# QRPEM method
EstArgs <-
  specify_EngineParams(
    sort = TRUE,
    ODE = "DVERK",
    rtolODE = 1e-5,
    atolODE = 1e-5,
    maxStepsODE = 6000,
    numIterations = 100,
    method = "QRPEM",
    numIterMAPNP = 3,
    stdErr = "Fisher-Score",
    isCentralDiffStdErr = FALSE,
    iSample = 350,
    impDist = "Mixture-2",
    scramble = "Tezuka-Faur")