nlmixr2auto (version 1.0.0)

aco.operator: ACO operator for model selection

Description

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,
  ...
)

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.

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().

Author

Zhonghui Huang

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.

See Also

acoControl, penaltyControl, auto_param_table, mod.run, ppkmodGen

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
  )
)
print(outs)
# }