Runs candidate models with one, two, and three compartments by modifying only the compartment setting in the current model code.
Usage
step_compartments(
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 folder name for storing intermediate results. If
NULL(default),tempdir()is used for temporary storage. If specified, a cache directory is created in the current working directory.- .modEnv
Internal environment used to store model indices and cached results across steps.
- verbose
Logical. If TRUE, print progress messages.
- ...
Additional arguments passed to mod.run. These may include custom_base, which is used to initialize the baseline model when no best_code is present in start.mod.
Value
A list with the following elements:
results_table: a data frame with one row per candidate model, including model description and fit statistics
best_code: named integer vector corresponding to the best candidate
best_row: one-row data frame containing the best candidate summary
Details
Three candidate models are created by modifying only the number of compartments in the starting model code. The candidate codes are evaluated sequentially, and a results table containing model names, model codes, Fitness values, and information criteria is returned for logging and decision making.
Examples
# \donttest{
dat <- pheno_sd
string <- c(1, 0, 0, 0, 0, 0, 0, 0, 0, 1)
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")
step_compartments(
dat = dat,
search.space = "ivbase",
param_table = param_table,
filename = "step_cmpt_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
#> [Success] Model file created:
#> /tmp/RtmpzBHrsN/mod3.txt
#> $results_table
#> Step Penalty.terms
#> 1 No. of compartments rse, theta, covariance
#> 2 No. of compartments rse, theta, covariance
#> 3 No. of compartments rse, theta, covariance
#> Model.name Model.code Fitness
#> 1 bolus_1cmpt_etaCL_FOelim_uncorrelated_combined 1,0,0,0,0,0,0,0,0,3 1303.125
#> 2 bolus_2cmpt_etaCL_FOelim_uncorrelated_combined 2,0,0,0,0,0,0,0,0,3 31347.169
#> 3 bolus_3cmpt_etaCL_FOelim_uncorrelated_combined 3,0,0,0,0,0,0,0,0,3 51360.189
#> AIC BIC OFV
#> 1 1277.908 1293.125 983.0373
#> 2 1305.865 1327.169 1006.9943
#> 3 1322.798 1350.189 1019.9274
#>
#> $best_code
#> no.cmpt eta.km eta.vc eta.vp eta.vp2 eta.q eta.q2 mm mcorr rv
#> 1 0 0 0 0 0 0 0 0 3
#>
#> $best_row
#> Step Penalty.terms
#> 1 No. of compartments rse, theta, covariance
#> Model.name Model.code Fitness
#> 1 bolus_1cmpt_etaCL_FOelim_uncorrelated_combined 1,0,0,0,0,0,0,0,0,3 1303.125
#> AIC BIC OFV
#> 1 1277.908 1293.125 983.0373
#>
# }