Skip to contents

Specify Engine Parameters for NLME Model Execution

specify_EngineParams.Rd

Defines optional engine parameters to control the estimation or simulation process in Phoenix NLME. This function generates a single character string containing space-separated name=value pairs for non-default settings. Parameters are included in the output string according to the order in the function signature.

Usage

specify_EngineParams(
  sort = FALSE,
  ODE = c("MatrixExponent", "DVERK", "DOPRI5", "AutoDetect", "Stiff", "LSODE"),
  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", "Hessian", "Fisher-Score", "Auto-Detect", "None"),
  isCentralDiffStdErr = TRUE,
  stepSizeStdErr = 0.01,
  logTransform = NULL,
  numIntegratePtsAGQ = 1L,
  numIterNonParametric = 0L,
  fastOptimization = FALSE,
  numIterMAPNP = 0L,
  numRepPCWRES = 0L,
  stepSizeLinearize = 0.002,
  numDigitLaplacian = 7L,
  numDigitBlup = 13L,
  gradTolOuter = 2e-04,
  stepTolOuter = 1e-04,
  gradTolInner = 1.71e-05,
  stepTolInner = 7.07e-08,
  refDeltaLagl = 0.001,
  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"),
  emTolType = 0L,
  emConvLen = 10L,
  emConvCritVal = 5,
  stepSizePartialDeriv = 1e-05,
  numTimeStepPartialDeriv = 20L
)

Arguments

sort

Logical; Specifies whether to sort the input data by subject and time. Default: FALSE. (Note: NLME/RsNLME may default to TRUE if model has no reset info). Included in output only if set to TRUE.

ODE

Character; Specifies the ODE solver. Options: "MatrixExponent", "DVERK", "DOPRI5", "AutoDetect", "Stiff", "LSODE". Default: "MatrixExponent". "AutoDetect" and "LSODE" use LSODA. "Stiff" is LSODE configured for stiff systems.

rtolODE

Numeric; Relative tolerance for the ODE solver. Default: 1e-6. (Not applicable if ODE = "MatrixExponent").

atolODE

Numeric; Absolute tolerance for the ODE solver. Default: 1e-6. (Not applicable if ODE = "MatrixExponent").

maxStepsODE

Integer; Maximum number of steps for the ODE solver. Default: 50000L. (Not applicable if ODE = "MatrixExponent").

numIterations

Integer; Maximum number of estimation iterations (max: 10000). Default: 1000L.

method

Character; Estimation method. Options: "FOCE-ELS", "QRPEM", "Laplacian", "Naive-Pooled", "FOCE-LB", "IT2S-EM", "FO". Default: "FOCE-ELS". (Note: NLME/RsNLME default depends on model type). Only "Naive-Pooled" is valid for individual models.

stdErr

Character; Standard error computation method. Options: "Sandwich", "Hessian", "Fisher-Score", "Auto-Detect", "None". Default: "Sandwich" (for most methods), "Fisher-Score" (if method="QRPEM"), "None" (if method="IT2S-EM"). The default applied depends on the chosen method. See Certara.RsNLME::engineParams documentation for full details.

isCentralDiffStdErr

Logical; Use central (TRUE) or forward (FALSE) difference for numerical standard error calculations. Default: TRUE.

stepSizeStdErr

Numeric; Relative step size for numerical Hessian computation for standard errors. Must be positive. Default: 0.01. (Note: NLME/RsNLME default differs for Naive-Pooled method).

logTransform

Logical or NULL; Controls log-transformation behavior for models with log-additive residual error (e.g., C*exp(epsilon)). Default: NULL. If set to TRUE or FALSE (i.e., not NULL), the logTransform=VALUE pair is included in the output string. The NLME engine interprets this parameter based on the model structure.

  • For models with a single log-additive residual error:

    • NULL or TRUE: Enables fitting in the log-domain (LTBS approach).

    • FALSE: The log-additive error is treated as proportional during fitting.

  • For models with multiple residual errors where at least one is log-additive: The log-additive error(s) are treated as proportional during fitting, regardless of the logTransform value.

  • For models without log-additive residual errors: This setting is generally ignored by the engine concerning special log-additive handling.

Note: This function includes logTransform in the output string if it's not NULL. The ultimate applicability and interpretation are handled by the NLME engine based on the detailed model structure.

numIntegratePtsAGQ

Integer; Number of quadrature points per dimension for Adaptive Gaussian Quadrature (AGQ). 1 means no AGQ. >1 enables AGQ. Default: 1L. (Population models, method = "FOCE-ELS" or "Laplacian" only).

numIterNonParametric

Integer; Controls non-parametric (NP) optimization. 0: Disable. 1: NONMEM-style NP. >1: Evolutionary NP algorithm generations. Default: 0L. (Population models, method != "Naive-Pooled" only).

fastOptimization

Logical; Use Automatic Differentiation (TRUE) or Finite Difference (FALSE) for optimizing random effects (etas). Default: FALSE. (Population models, method = "FOCE-ELS" or "Laplacian" only).

numIterMAPNP

Integer; Number of preliminary Naive-Pooled iterations. Default: 0L. (Population models, method != "Naive-Pooled" only).

numRepPCWRES

Integer; Replicates for PCWRES (max 10000). 0 disables calculation. Default: 0L. (Population models, method != "Naive-Pooled" only).

stepSizeLinearize

Numeric; Relative step size for numerical differentiation during linearization. Must be positive. Default: 0.002. (Population models? Check NLME docs).

numDigitLaplacian

Integer; Optimization accuracy (NDIGIT) for the outer loop ("FOCE-ELS"/"Laplacian"). Positive integer. Default: 7L. (Population models, method = "FOCE-ELS" or "Laplacian" only).

numDigitBlup

Integer; Optimization accuracy (NDIGIT) for the inner loop (etas) or for "Naive-Pooled". Positive integer. Default: 13L. (Population models or method = "Naive-Pooled").

gradTolOuter

Numeric; Max gradient tolerance, outer loop. Non-negative. Default: 2e-4. (Population models, method = "FOCE-ELS" or "Laplacian" only).

stepTolOuter

Numeric; Max step tolerance, outer loop. Non-negative. Default: 1e-4. (Population models, method = "FOCE-ELS" or "Laplacian" only).

gradTolInner

Numeric; Max gradient tolerance, inner loop (etas). Non-negative. Default: 1.71e-5. (Population models, method = "FOCE-ELS" or "Laplacian" only).

stepTolInner

Numeric; Max step tolerance, inner loop (etas). Non-negative. Default: 7.07e-8. (Population models, method = "FOCE-ELS" or "Laplacian" only).

refDeltaLagl

Numeric; Log-likelihood change tolerance. Non-negative. Default: 1e-3. (Population models, method = "FOCE-ELS" or "Laplacian" only).

mapAssist

Integer; Periodicity for MAP assistance. 0 disables. Default: 0L. (Population models, method = "QRPEM" only).

iSample

Integer; Sample points. Positive integer. Default: 300L. (Population models, method = "QRPEM" only).

iAcceptRatio

Numeric; Acceptance ratio for covariance scaling. Positive. Default: 0.1. (Population models, method = "QRPEM" only).

impDist

Character; Importance sampling distribution. Options: "Normal", etc. Default: "Normal". (Population models, method = "QRPEM" only).

tDOF

Integer; Degrees of freedom for T distribution importance sampling (3-30). Default: 4L. (Population models, method = "QRPEM" and impDist = "T" only).

numSampleSIR

Integer; Samples per eta per subject for SIR. Positive integer. Default: 10L. (Population models, method = "QRPEM" only).

numBurnIn

Integer; Burn-in iterations. Default: 0L. (Population models, method = "QRPEM" only).

freezeOmega

Logical; Freeze Omega during burn-in. Default: FALSE. (Population models, method = "QRPEM" only).

MCPEM

Logical; Use Monte-Carlo (TRUE) or Quasi-Random (FALSE) sampling. Default: FALSE. (Population models, method = "QRPEM" only).

runAllIterations

Logical; Force execution of all iterations. Default: FALSE. (Population models, method = "QRPEM" only).

scramble

Character; Quasi-random scrambling. Options: "Owen", etc. Default: "Owen". (Population models, method = "QRPEM" only).

emTolType

Integer; QRPEM convergence check type (0-3). Default: 0L. (Population models, method = "QRPEM" only).

emConvLen

Integer; Iterations for QRPEM convergence check window. Positive. Default: 10L. (Used when emTolType > 0, QRPEM only).

emConvCritVal

Numeric; Critical value for QRPEM convergence check. Positive. Default: 5.0. (Used when emTolType > 0, QRPEM only).

stepSizePartialDeriv

Numeric; Step size for numerical partial derivatives. Positive. Default: 1e-5. (Individual models only).

numTimeStepPartialDeriv

Integer; Time steps for outputting partial derivatives. Positive integer. Default: 20L. (Individual models only).

Value

A single character string containing space-separated name=value pairs, ordered according to the function signature. Includes parameters if specified with non-default values (using method-specific defaults for stdErr).

Details

This function allows customization of the NLME engine settings. Parameters are validated based on type, range, and applicability (detailed in parameter descriptions). Only parameters explicitly set to a value different from their default for the specified context (e.g., method-specific defaults for stdErr) are included in the output string. Values are returned as character strings.

Important Note on Defaults: Uses fixed defaults as specified in the argument list for comparison unless otherwise noted (e.g., stdErr). The actual default applied by NLME might differ based on model context (population vs individual, presence of reset info, discontinuities, BQL data).

Parameter Applicability & Warnings: The function checks for common cases where provided parameters might be ignored by the NLME engine based on the selected method or other settings. Warnings are issued in such cases. It assumes population context unless method="Naive-Pooled".

See also

write_ModelTemplateTokens(), specify_SimParams()

Examples

# Default settings
EstArgs_def <- specify_EngineParams()
print(EstArgs_def)
#> [1] " sort=FALSE"

# Setting sort = TRUE
EstArgs_sort_true <- specify_EngineParams(sort = TRUE)
print(EstArgs_sort_true)
#> [1] " sort=TRUE"

# QRPEM method with several custom settings
EstArgs_qrpem_str <-
  specify_EngineParams(
    sort = TRUE, # Explicitly non-default
    ODE = "DVERK",
    rtolODE = 1e-5,
    numIterations = 500,
    method = "QRPEM",
    isCentralDiffStdErr = FALSE,
    numIterMAPNP = 3,
    iSample = 350,
    impDist = "Mixture-2",
    scramble = "Tezuka-Faur",
    numBurnIn = 10,
    freezeOmega = TRUE
  )
#> For method='QRPEM', stdErr must be 'Fisher-Score' or 'None'. Setting stdErr='Fisher-Score'.
print(EstArgs_qrpem_str)
#> [1] " sort=TRUE ODE=DVERK rtolODE=1e-05 numIterations=500 method=QRPEM isCentralDiffStdErr=FALSE numIterMAPNP=3 iSample=350 impDist=Mixture-2 numBurnIn=10 freezeOmega=TRUE scramble=Tezuka-Faur"