Runs candidate models with and without IIV on \(K_m\) by modifying only the corresponding random-effect setting in the current model code.
Usage
step_iiv_km(
dat,
start.mod = NULL,
search.space = "ivbase",
no.cores = NULL,
param_table = NULL,
penalty.control = NULL,
precomputed_results_file = NULL,
filename = "test",
foldername = NULL,
.modEnv = NULL,
verbose = TRUE,
...
)Arguments
- dat
A data frame containing pharmacokinetic data in standard nlmixr2 format, including "ID", "TIME", "EVID", and "DV", and may include additional columns.
- start.mod
A named integer vector specifying the starting model code. If NULL, a base model is generated using
base_model().- search.space
Character, one of "ivbase" or "oralbase". Default is "ivbase".
- no.cores
Integer. Number of CPU cores to use. If NULL, uses
rxode2::getRxThreads().- param_table
Optional data frame of initial parameter estimates. If NULL, the table is generated by
auto_param_table().- penalty.control
A list of penalty control parameters defined by
penaltyControl(), specifying penalty values used for model diagnostics during fitness evaluation.- precomputed_results_file
Optional path to a CSV file of previously computed model results used for caching.
- filename
Optional character string used as a prefix for output files. Defaults to "test".
- foldername
Character string specifying the name of the folder to be created in the current working directory to store intermediate results. If NULL, a name is generated automatically.
- .modEnv
Optional internal environment used to store model indices and cached results across model-selection steps.
- verbose
Logical. If TRUE, print progress messages.
- ...
Additional arguments forwarded to mod.run().
Value
A list with the following elements:
results_table: A data.frame summarizing the evaluated models.
best_code: A named integer vector representing the selected model code.
best_row: A one-row data.frame corresponding to the selected model.
Details
This step is executed only when the starting model code specifies Michaelis–Menten elimination (mm = 1). If mm is not equal to 1 in the starting model, no model comparison is performed.
Examples
# \donttest{
dat <- pheno_sd
param_table <- initialize_param_table()
param_table$init[param_table$Name == "lcl"] <- log(0.008)
param_table$init[param_table$Name == "lvc"] <- log(0.6)
penalty.control <- penaltyControl()
penalty.control$penalty.terms <-
c("rse", "theta", "covariance", "shrinkage", "omega")
start.mod <- base_model("ivbase")
start.mod["mm"] <- 1L
step_iiv_km(
dat = dat,
start.mod = start.mod,
search.space = "ivbase",
param_table = param_table,
filename = "step_etakm_test",
penalty.control = penalty.control,
saem.control = nlmixr2est::saemControl(logLik = TRUE,nBurn=15,nEm=15)
)
#> [Success] Model file created:
#> /tmp/RtmpzBHrsN/mod1.txt
#> SAEM control (core) = niter=15|15; nBurn=15; nEm=15; seed=99; print=1
#> [Success] Model file created:
#> /tmp/RtmpzBHrsN/mod2.txt
#> $results_table
#> Step Penalty.terms
#> 1 IIV on Km rse, theta, covariance, shrinkage, omega
#> 2 IIV on Km rse, theta, covariance, shrinkage, omega
#> Model.name Model.code
#> 1 bolus_1cmpt_etaVmax_MMelim_uncorrelated_combined 1,0,0,0,0,0,0,1,0,3
#> 2 bolus_1cmpt_etaVmaxKM_MMelim_uncorrelated_combined 1,1,0,0,0,0,0,1,0,3
#> Fitness AIC BIC OFV
#> 1 31358.82 1330.561 1348.822 1033.690
#> 2 21527.68 1476.374 1497.678 1177.503
#>
#> $best_code
#> no.cmpt eta.km eta.vc eta.vp eta.vp2 eta.q eta.q2 mm mcorr rv
#> 1 1 0 0 0 0 0 1 0 3
#>
#> $best_row
#> Step Penalty.terms
#> 2 IIV on Km rse, theta, covariance, shrinkage, omega
#> Model.name Model.code
#> 2 bolus_1cmpt_etaVmaxKM_MMelim_uncorrelated_combined 1,1,0,0,0,0,0,1,0,3
#> Fitness AIC BIC OFV
#> 2 21527.68 1476.374 1497.678 1177.503
#>
# }