Run a genetic algorithm to search for an optimal PK model structure within a predefined search space using nlmixr2-based model fitting and penalties.
Usage
ga.operator(
dat,
param_table = NULL,
search.space = c("ivbase", "oralbase"),
no.cores = NULL,
ga.control = gaControl(),
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().- ga.control
A list of GA control parameters, generated by
gaControl(). Includes:npop - number of individuals (chromosomes) per generation.
niter - maximum number of generations.
pcross - crossover probability.
pmut - per-bit mutation probability.
diff_tol - significance difference threshold used for ranking.
nls - frequency (in generations) of running local exhaustive search around the best current model.
- 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 genetic algorithm operator for reproducible runs. Default is 1234.
- .modEnv
Optional environment used to store run state and cached results. If NULL, a new environment is created.
- verbose
Logical. If TRUE, print progress messages.
- ...
Additional arguments passed to
mod.run().
Value
An object of class "gaOperatorResult" containing:
Final Selected Code: data frame with the best binary encoding.
Final Selected Model Name: model identifier for the best encoding.
Model Run History: data frame of fitted models and fitness values.
Selection History: list of per-generation results.
Details
The algorithm evolves a population of binary-encoded candidate models over multiple generations using tournament selection, crossover, mutation, and local search. Candidate encodings are validated and then evaluated by fitting models and applying user-defined penalties. The best individual is carried forward to the next generation.
Examples
# \donttest{
# Example usage with phenotype dataset
outs <- ga.operator(
dat = pheno_sd,
param_table = NULL,
search.space = "ivbase",
ga.control = gaControl(),
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
# }