Generate a population of ants (candidate models) for use in an ant colony optimization algorithm for pharmacometric model search.
Usage
createAnts(
search.space = "ivbase",
nants = 15,
init = FALSE,
nodeslst = NULL,
custom_config = NULL,
fixed = NULL
)Arguments
- search.space
Character, one of "ivbase" or "oralbase". Default is "ivbase".
- nants
Integer. Number of ants (candidate solutions) generated at each iteration. Defaults to 15.
- init
Logical. If TRUE, a subset of ants is initialized as fixed base models and the remaining ants are generated by probabilistic sampling. If FALSE, all ants are generated by probabilistic sampling.
- nodeslst
Data frame containing pheromone information used for probabilistic sampling. It must include node identifiers and associated sampling probabilities. This argument is required whenever random ants are generated.
- custom_config
Optional named list defining a custom parameter structure. If provided, the parameter names are taken from the names of this list. If NULL, a default parameter structure is used based on the selected search space.
- fixed
Optional list specifying fixed ants for initialization. The list may contain the following elements:
n: number of fixed ants.
mat: optional matrix specifying fixed ant encodings, with parameters in rows and ants in columns.
Value
A numeric matrix in which rows correspond to model parameters and columns correspond to individual ants. Column names identify ants sequentially.
Parameter values are encoded as integers. Binary indicators represent exclusion or inclusion of model components, categorical values represent multi-level structural choices, and the value -1 indicates that a parameter is not applicable for the given model structure.
Details
Each ant is represented as a column vector encoding discrete structural model decisions, including the number of compartments, inclusion of random effects, Michaelis–Menten elimination, correlation structures, and residual error models. The set of parameters included in the encoding depends on the selected search space.
Ants are generated using a combination of fixed initialization and pheromone-guided probabilistic sampling. When fixed initialization is enabled, a subset of ants corresponds to predefined base models, such as one- to three-compartment structures with different residual error models. The remaining ants are sampled according to probability distributions derived from pheromone weights stored in the node list.
Structural dependencies between parameters are enforced during generation. For example, parameters associated with peripheral compartments are only active when the number of compartments is sufficient, and parameters related to Michaelis–Menten elimination are only sampled when the corresponding mechanism is selected. Parameters that are not applicable for a given structure are encoded with a value of -1.
Examples
# Example 1: Use defaults (6 fixed base models)
nodes <- initNodeList(search.space = "ivbase", phi0 = 1)
createAnts(
search.space = "ivbase",
nants = 15,
init = TRUE,
nodeslst = nodes
)
#> ant1 ant2 ant3 ant4 ant5 ant6 ant7 ant8 ant9 ant10 ant11 ant12 ant13
#> no.cmpt 1 1 2 2 3 3 2 2 3 2 2 3 3
#> eta.km -1 -1 -1 -1 -1 -1 -1 1 -1 -1 -1 1 -1
#> eta.vc 0 0 0 0 0 0 0 1 0 0 1 1 1
#> eta.vp -1 -1 0 0 0 0 1 0 1 1 1 0 0
#> eta.vp2 -1 -1 -1 -1 0 0 -1 -1 1 -1 -1 1 1
#> eta.q -1 -1 0 0 0 0 1 1 0 1 0 1 0
#> eta.q2 -1 -1 -1 -1 0 0 -1 -1 0 -1 -1 0 0
#> mm 0 0 0 0 0 0 0 1 0 0 0 1 0
#> mcorr 0 0 0 0 0 0 1 1 0 1 1 0 0
#> rv 1 2 1 2 1 2 2 3 3 1 2 1 1
#> ant14 ant15
#> no.cmpt 2 1
#> eta.km -1 -1
#> eta.vc 0 1
#> eta.vp 0 -1
#> eta.vp2 -1 -1
#> eta.q 0 -1
#> eta.q2 -1 -1
#> mm 0 0
#> mcorr 1 0
#> rv 2 3
# Example 2: Custom number of fixed ants
createAnts(
search.space = "ivbase",
nants = 20,
init = TRUE,
nodeslst = nodes,
fixed = list(n = 10) # 10 fixed, mat = NULL (auto-generate)
)
#> ant1 ant2 ant3 ant4 ant5 ant6 ant7 ant8 ant9 ant10 ant11 ant12 ant13
#> no.cmpt 1 1 2 2 3 3 1 1 2 2 3 1 2
#> eta.km -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 1 -1
#> eta.vc 0 0 0 0 0 0 0 0 0 0 1 0 0
#> eta.vp -1 -1 0 0 0 0 -1 -1 0 0 1 -1 1
#> eta.vp2 -1 -1 -1 -1 0 0 -1 -1 -1 -1 0 -1 -1
#> eta.q -1 -1 0 0 0 0 -1 -1 0 0 1 -1 0
#> eta.q2 -1 -1 -1 -1 0 0 -1 -1 -1 -1 0 -1 -1
#> mm 0 0 0 0 0 0 0 0 0 0 0 1 0
#> mcorr 0 0 0 0 0 0 0 0 0 0 0 1 0
#> rv 1 2 1 2 1 2 1 2 1 2 2 3 3
#> ant14 ant15 ant16 ant17 ant18 ant19 ant20
#> no.cmpt 2 1 3 1 3 2 3
#> eta.km 0 1 -1 1 -1 0 -1
#> eta.vc 1 0 0 1 1 0 0
#> eta.vp 1 -1 0 -1 0 0 0
#> eta.vp2 -1 -1 1 -1 1 -1 0
#> eta.q 1 -1 0 -1 0 1 0
#> eta.q2 -1 -1 1 -1 1 -1 1
#> mm 1 1 0 1 0 1 0
#> mcorr 1 0 1 1 0 0 0
#> rv 3 2 3 3 2 3 3
# Example 3: Custom fixed models
my_models <- matrix(
c(1, -1, 0, -1, -1, -1, -1, 0, 0, 1,
2, -1, 1, 0, -1, 0, -1, 0, 0, 2,
3, -1, 1, 1, 0, 1, 0, 1, 1, 3),
nrow = 10, ncol = 3
)
rownames(my_models) <- c("no.cmpt", "eta.km", "eta.vc", "eta.vp",
"eta.vp2", "eta.q", "eta.q2", "mm", "mcorr", "rv")
createAnts(
search.space = "ivbase",
nants = 10,
init = TRUE,
nodeslst = nodes,
fixed = list(n = 3, mat = my_models)
)
#> ant1 ant2 ant3 ant4 ant5 ant6 ant7 ant8 ant9 ant10
#> no.cmpt 1 2 3 3 3 3 2 1 1 3
#> eta.km -1 -1 -1 -1 1 1 0 -1 -1 0
#> eta.vc 0 1 1 0 1 1 1 1 0 1
#> eta.vp -1 0 1 1 1 1 1 -1 -1 1
#> eta.vp2 -1 -1 0 1 0 1 -1 -1 -1 0
#> eta.q -1 0 1 0 1 0 0 -1 -1 0
#> eta.q2 -1 -1 0 1 0 0 -1 -1 -1 1
#> mm 0 0 1 0 1 1 1 0 0 1
#> mcorr 0 0 1 0 0 1 1 1 0 0
#> rv 1 2 3 2 2 3 3 3 2 2