Implements a forward selection procedure to assess the inclusion of inter-individual variability on structural pharmacokinetic parameters.
Usage
step_iiv_f(
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 for storing intermediate results across model runs.
- verbose
Logical. If TRUE, print progress messages.
- ...
Additional arguments passed to the model estimation function.
Value
A list with three elements:
results_table: A data frame summarizing all models evaluated during the forward selection process.
best_code: A named integer vector corresponding to the selected model.
best_row: A one-row data frame containing the results of the selected model.
Details
The procedure begins with an initial model and proceeds iteratively. At each step, candidate models are generated by adding exactly one additional IIV (random-effect) term while keeping all other aspects of the model unchanged. If any candidate improves the chosen fitness criterion, the best-improving candidate becomes the new reference model for the next iteration. The algorithm stops when no further improvement is achieved. The set of parameters eligible for IIV depends on the number of compartments:
One-compartment models: clearance and central volume
Two-compartment models: clearance, central volume, peripheral volume, and inter-compartmental clearance
Three-compartment models: clearance, central volume, peripheral volumes, and inter-compartmental clearances
Examples
# \donttest{
dat <- Bolus_2CPT[Bolus_2CPT$SD==1,]
param_table <- initialize_param_table()
param_table$init[param_table$Name == "lcl"] <- log(4)
param_table$init[param_table$Name == "lvc2cmpt"] <- log(70)
param_table$init[param_table$Name == "lvp2cmpt"] <- log(40)
param_table$init[param_table$Name == "lq2cmpt"] <- log(4)
penalty.control <- penaltyControl()
penalty.control$penalty.terms <-
c("rse", "theta", "covariance", "shrinkage", "omega")
start.mod <- base_model("ivbase")
start.mod["no.cmpt"] <- 2L
step_iiv_f(
dat = dat,
start.mod = start.mod,
search.space = "ivbase",
param_table = param_table,
filename = "step_eta_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
#> [Success] Model file created:
#> /tmp/RtmpzBHrsN/mod4.txt
#> [Success] Model file created:
#> /tmp/RtmpzBHrsN/mod5.txt
#> [Success] Model file created:
#> /tmp/RtmpzBHrsN/mod6.txt
#> [Success] Model file created:
#> /tmp/RtmpzBHrsN/mod7.txt
#> $results_table
#> Step Penalty.terms
#> 1 IIV (forward) rse, theta, covariance, shrinkage, omega
#> 2 IIV (forward) rse, theta, covariance, shrinkage, omega
#> 3 IIV (forward) rse, theta, covariance, shrinkage, omega
#> 4 IIV (forward) rse, theta, covariance, shrinkage, omega
#> 5 IIV (forward) rse, theta, covariance, shrinkage, omega
#> 6 IIV (forward) rse, theta, covariance, shrinkage, omega
#> 7 IIV (forward) rse, theta, covariance, shrinkage, omega
#> Model.name Model.code
#> 1 bolus_2cmpt_etaCL_FOelim_uncorrelated_combined 2,0,0,0,0,0,0,0,0,3
#> 2 bolus_2cmpt_etaCLVC_FOelim_uncorrelated_combined 2,0,1,0,0,0,0,0,0,3
#> 3 bolus_2cmpt_etaCLVP_FOelim_uncorrelated_combined 2,0,0,1,0,0,0,0,0,3
#> 4 bolus_2cmpt_etaCLQ_FOelim_uncorrelated_combined 2,0,0,0,0,1,0,0,0,3
#> 5 bolus_2cmpt_etaCLVC_FOelim_uncorrelated_combined 2,0,1,0,0,0,0,0,0,3
#> 6 bolus_2cmpt_etaCLVCVP_FOelim_uncorrelated_combined 2,0,1,1,0,0,0,0,0,3
#> 7 bolus_2cmpt_etaCLVCQ_FOelim_uncorrelated_combined 2,0,1,0,0,1,0,0,0,3
#> Fitness AIC BIC OFV
#> 1 26505.58 26465.45 26505.58 22261.09
#> 2 25987.92 25942.06 25987.92 21735.70
#> 3 26427.91 26372.05 26417.91 22165.69
#> 4 26438.10 26382.25 26428.10 22175.89
#> 5 25987.92 25942.06 25987.92 21735.70
#> 6 26088.01 26026.42 26078.01 21818.06
#> 7 26092.20 26030.61 26082.20 21822.25
#>
#> $best_code
#> no.cmpt eta.km eta.vc eta.vp eta.vp2 eta.q eta.q2 mm mcorr rv
#> 2 0 1 0 0 0 0 0 0 3
#>
#> $best_row
#> Step Penalty.terms
#> 2 IIV (forward) rse, theta, covariance, shrinkage, omega
#> Model.name Model.code Fitness
#> 2 bolus_2cmpt_etaCLVC_FOelim_uncorrelated_combined 2,0,1,0,0,0,0,0,0,3 25987.92
#> AIC BIC OFV
#> 2 25942.06 25987.92 21735.7
#>
# }