Implements an ant colony optimization algorithm to explore model space and identify the best-performing model given pre-defined fitness function.
Usage
aco.operator(
dat,
param_table = NULL,
search.space = c("ivbase", "oralbase"),
no.cores = NULL,
aco.control = acoControl(),
penalty.control = penaltyControl(),
precomputed_results_file = NULL,
foldername = NULL,
filename = "test",
seed = 1234,
.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.
- param_table
Optional data frame of initial parameter estimates. If NULL, the table is generated by
auto_param_table().- 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().- aco.control
A list of ACO control parameters defined by
acoControl(). Includes:nants - number of ants per iteration.
niter - maximum number of iterations.
rho - pheromone evaporation rate.
phi0 - initial pheromone level.
phi_min, phi_max - bounds for pheromone levels.
alpha - pheromone weight exponent.
elite - proportion of best solutions preserved each iteration.
prob.min - minimum sampling probability.
diff_tol - threshold for significant fitness difference.
- 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.
- 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.- filename
Optional character string used as a prefix for output files. Defaults to "test".
- seed
Integer. Random seed controlling the random sampling steps of the ant colony optimization operator for reproducible runs. Default is 1234.
- .modEnv
Optional environment used internally to store model indices, cached parameter tables, and results across steps.
- verbose
Logical. If TRUE, print progress messages.
- ...
Additional arguments passed to
mod.run().
Value
An object of class "acoOperatorResult", containing:
$`Final Selected Code`- Vector representation of the best model.$`Final Selected Model Name`- Human-readable name of the selected model.$`Model Run History`- Data frame of model runs across iterations.$`Node Run History`- History of pheromone probabilities for each iteration.
Details
The ACO approach uses a colony of "ants" to stochastically sample models, evaluate their fitness, and update pheromone trails that guide future searches. This iterative process balances exploration of new models with exploitation of promising candidates.
Examples
# \donttest{
# Example usage with phenotype dataset
outs <- aco.operator(
dat = pheno_sd,
param_table = NULL,
search.space = "ivbase",
aco.control = acoControl(),
saem.control = nlmixr2est::saemControl(
seed = 1234,
nBurn = 200,
nEm = 300,
logLik = TRUE
)
)
#>
#>
#> Infometrics Value
#> ---------------------------------------- ---------------
#> Dose Route bolus
#> Dose Type combined_doses
#> Number of Subjects 59
#> Number of Observations 155
#> Subjects with First-Dose Interval Data 35
#> Observations in the First-Dose Interval 35
#> Subjects with Multiple-Dose Data 56
#> Observations after Multiple Doses 120
#> ---------------------------------------- ------
#> Estimating half-life....................
#> Half-life estimation complete: Estimated t1/2 = 16.44 h
#> Evaluating the predictive performance of calculated one-compartment model parameters....................
#> Error in loadNamespace(x): there is no package called ‘progress’
print(outs)
#> Error: object 'outs' not found
# }