Evaluates whether correlation between inter-individual random effects (ETA correlation) should be included in the model.
Usage
step_correlation(
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 environment used to store model indices and cached results across steps.
- verbose
Logical. If TRUE, print progress messages.
- ...
Additional arguments passed to the model estimation function.
Value
A list with the following elements:
results_table: A data frame summarizing the evaluated models,
best_code: A named integer vector corresponding to the selected model code,
best_row: A one-row data frame containing the summary of the selected model.
Details
Two candidate models are constructed by toggling the correlation setting of inter-individual random effects in the model code. Model selection is based on comparison of Fitness values returned during estimation.
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["eta.vc"] <- 1L
step_correlation(
dat = dat,
start.mod = start.mod,
search.space = "ivbase",
param_table = param_table,
filename = "step_mcorr_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 Eta correlation rse, theta, covariance, shrinkage, omega
#> 2 Eta correlation rse, theta, covariance, shrinkage, omega
#> Model.name Model.code Fitness
#> 1 bolus_1cmpt_etaCLVC_FOelim_uncorrelated_combined 1,0,1,0,0,0,0,0,0,3 1289.223
#> 2 bolus_1cmpt_etaCLVC_FOelim_correlated_combined 1,0,1,0,0,0,0,0,1,3 1198.249
#> AIC BIC OFV
#> 1 1240.962 1259.223 944.0914
#> 2 1166.945 1188.249 868.0740
#>
#> $best_code
#> no.cmpt eta.km eta.vc eta.vp eta.vp2 eta.q eta.q2 mm mcorr rv
#> 1 0 1 0 0 0 0 0 1 3
#>
#> $best_row
#> Step Penalty.terms
#> 2 Eta correlation rse, theta, covariance, shrinkage, omega
#> Model.name Model.code Fitness
#> 2 bolus_1cmpt_etaCLVC_FOelim_correlated_combined 1,0,1,0,0,0,0,0,1,3 1198.249
#> AIC BIC OFV
#> 2 1166.945 1188.249 868.074
#>
# }