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.
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
)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).
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.
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.
Numeric; Relative tolerance for the ODE solver.
Default: 1e-6. (Not applicable if ODE = "MatrixExponent").
Numeric; Absolute tolerance for the ODE solver.
Default: 1e-6. (Not applicable if ODE = "MatrixExponent").
Integer; Maximum number of steps for the ODE solver.
Default: 50000L. (Not applicable if ODE = "MatrixExponent").
Integer; Maximum number of estimation iterations (max:
10000).
Default: 1000L.
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.
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.
Logical; Use central (TRUE) or forward (FALSE)
difference for numerical standard error calculations. Default: TRUE.
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).
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.
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).
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).
Logical; Use Automatic Differentiation (TRUE) or Finite
Difference (FALSE) for optimizing random effects (etas). Default:
FALSE.
(Population models, method = "FOCE-ELS" or "Laplacian" only).
Integer; Number of preliminary Naive-Pooled iterations.
Default: 0L. (Population models, method != "Naive-Pooled" only).
Integer; Replicates for PCWRES (max 10000). 0 disables
calculation.
Default: 0L. (Population models, method != "Naive-Pooled" only).
Numeric; Relative step size for numerical
differentiation during linearization. Must be positive. Default:
0.002.
(Population models? Check NLME docs).
Integer; Optimization accuracy (NDIGIT) for the
outer loop ("FOCE-ELS"/"Laplacian"). Positive integer. Default:
7L.
(Population models, method = "FOCE-ELS" or "Laplacian" only).
Integer; Optimization accuracy (NDIGIT) for the inner
loop (etas) or for "Naive-Pooled". Positive integer. Default: 13L.
(Population models or method = "Naive-Pooled").
Numeric; Max gradient tolerance, outer loop.
Non-negative.
Default: 2e-4. (Population models, method = "FOCE-ELS" or "Laplacian" only).
Numeric; Max step tolerance, outer loop. Non-negative.
Default: 1e-4. (Population models, method = "FOCE-ELS" or "Laplacian" only).
Numeric; Max gradient tolerance, inner loop (etas).
Non-negative.
Default: 1.71e-5. (Population models, method = "FOCE-ELS" or "Laplacian" only).
Numeric; Max step tolerance, inner loop (etas).
Non-negative.
Default: 7.07e-8. (Population models, method = "FOCE-ELS" or "Laplacian" only).
Numeric; Log-likelihood change tolerance. Non-negative.
Default: 1e-3. (Population models, method = "FOCE-ELS" or "Laplacian" only).
Integer; Periodicity for MAP assistance. 0 disables.
Default: 0L. (Population models, method = "QRPEM" only).
Integer; Sample points. Positive integer.
Default: 300L. (Population models, method = "QRPEM" only).
Numeric; Acceptance ratio for covariance scaling.
Positive.
Default: 0.1. (Population models, method = "QRPEM" only).
Character; Importance sampling distribution. Options:
"Normal", etc.
Default: "Normal". (Population models, method = "QRPEM" only).
Integer; Degrees of freedom for T distribution importance
sampling (3-30).
Default: 4L. (Population models, method = "QRPEM" and impDist = "T" only).
Integer; Samples per eta per subject for SIR. Positive
integer.
Default: 10L. (Population models, method = "QRPEM" only).
Integer; Burn-in iterations.
Default: 0L. (Population models, method = "QRPEM" only).
Logical; Freeze Omega during burn-in.
Default: FALSE. (Population models, method = "QRPEM" only).
Logical; Use Monte-Carlo (TRUE) or Quasi-Random (FALSE)
sampling.
Default: FALSE. (Population models, method = "QRPEM" only).
Logical; Force execution of all iterations.
Default: FALSE. (Population models, method = "QRPEM" only).
Character; Quasi-random scrambling. Options: "Owen", etc.
Default: "Owen". (Population models, method = "QRPEM" only).
Integer; QRPEM convergence check type (0-3).
Default: 0L. (Population models, method = "QRPEM" only).
Integer; Iterations for QRPEM convergence check window.
Positive.
Default: 10L. (Used when emTolType > 0, QRPEM only).
Numeric; Critical value for QRPEM convergence check.
Positive.
Default: 5.0. (Used when emTolType > 0, QRPEM only).
Numeric; Step size for numerical partial
derivatives. Positive.
Default: 1e-5. (Individual models only).
Integer; Time steps for outputting partial
derivatives. Positive integer.
Default: 20L. (Individual models only).
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".
write_ModelTemplateTokens(), specify_SimParams()
# Default settings
EstArgs_def <- specify_EngineParams()
print(EstArgs_def)
# Setting sort = TRUE
EstArgs_sort_true <- specify_EngineParams(sort = TRUE)
print(EstArgs_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
)
print(EstArgs_qrpem_str)
Run the code above in your browser using DataLab