Performs tabu search to explore the pharmacometric model space and identify the best-performing model. Supports both IV and Oral search spaces.
tabu.operator(
dat,
param_table = NULL,
start.mod = NULL,
search.space = c("ivbase", "oralbase"),
no.cores = NULL,
tabu.control = tabuControl(),
penalty.control = penaltyControl(),
precomputed_results_file = NULL,
foldername = NULL,
filename = "test",
seed = 1234,
.modEnv = NULL,
verbose = TRUE,
...
)An object of class tabuOperatorResult, containing:
Vector representation of the best model.
Selected best model (human-readable).
Data frame of all model evaluations with fitness values.
List with iteration-level history:
starting.points.history, local.best.history,
tabu.elements.history, neighbors.history.
A data frame containing pharmacokinetic data in standard nlmixr2 format, including "ID", "TIME", "EVID", and "DV", and may include additional columns.
Optional data frame of initial parameter estimates. If NULL,
the table is generated by auto_param_table().
A named integer vector specifying the starting model
code. If NULL, a base model is generated using base_model().
Character, one of "ivbase" or "oralbase". Default is "ivbase".
Integer. Number of CPU cores to use. If NULL, uses
rxode2::getRxThreads().
A list of Tabu Search control parameters from
tabuControl:
Integer. Number of iterations a move remains tabu.
Integer. Maximum number of search iterations.
Optional initial model code vector.
Logical. If TRUE, allows aspiration criterion.
Character. Tabu restriction policy: move or
attribute. See Details.
Optional integer. Maximum number of neighbors randomly sampled from the full neighborhood (candidate list strategy).
A list of penalty control parameters defined by
penaltyControl(), specifying penalty values used for model diagnostics
during fitness evaluation.
Optional path to a CSV file of previously computed model results used for caching.
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.
Optional character string used as a prefix for output files. Defaults to "test".
Integer. Random seed controlling the random sampling steps of the tabu operator for reproducible runs. Default is 1234.
Environment for storing intermediate results. If NULL,
a new environment is created.
Logical. If TRUE, print progress messages.
Additional arguments passed to mod.run().
Zhonghui Huang
This function implements tabu search for pharmacometric model structure optimization. Models are encoded as bit vectors representing structural and statistical components.
Neighbor Generation and Validation
Each iteration generates neighbors by one-bit flips, then validates them
using validStringcat(). The algorithm maintains both:
neighbors_orig: Original neighbors (before validation) →
used to detect intended moves
neighbors_val: Validated neighbors (after validation) →
used for fitness evaluation
This separation is critical because validation may introduce secondary changes.
For example, changing no.cmpt from 2 to 3 might force eta.vp = 0
to maintain model legality. The tabu list records only the intended change
(no.cmpt), not validation side effects (eta.vp).
Tabu List Policies
Two restriction policies are available:
"move": Forbids specific transitions (e.g., no.cmpt: 2 -> 3
and 3 -> 2). Stores both forward and reverse moves.
"attribute": Forbids setting a parameter to a specific value
regardless of origin (e.g., any move setting no.cmpt = 3).
Both policies use the same data structure (element, from,
to, tabu.iteration.left). For attribute-based policy, the
from field is stored for record-keeping but only to is used
in tabu checking.
Aspiration Criterion When enabled, tabu moves are allowed if they produce a solution better than the global best.
Perturbation If the search returns to a previous starting point (cycling detected), a 2-bit perturbation is applied to escape the local region.
tabuControl for control parameters,
detect_move for move detection,
is_move_tabu for tabu checking,
perturb_2bit for perturbation
# \donttest{
# Example usage with phenotype dataset
outs <- tabu.operator(
dat = pheno_sd,
param_table = NULL,
search.space = "ivbase",
tabu.control = tabuControl(),
saem.control = nlmixr2est::saemControl(
seed = 1234,
nBurn = 200,
nEm = 300,
logLik = TRUE
)
)
print(outs)
# }
Run the code above in your browser using DataLab