Tabu search operator for model selection

Performs tabu search to explore the pharmacometric model space and identify the best-performing model. Supports both IV and Oral search spaces.

Usage

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

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

start.mod

A named integer vector specifying the starting model code. If NULL, a base model is generated using base_model().

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

tabu.control

A list of Tabu Search control parameters from tabuControl:

tenure

Integer. Number of iterations a move remains tabu.

niter

Integer. Maximum number of search iterations.

start.point

Optional initial model code vector.

policy

Character. Tabu restriction policy: move or attribute. See Details.

nsize

Optional integer. Maximum number of neighbors randomly sampled from the full neighborhood (candidate list strategy).

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 tabu operator for reproducible runs. Default is 1234.

.modEnv

Environment for storing intermediate 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 tabuOperatorResult, containing:

Final Selected Code

Vector representation of the best model.

Final Selected Model Name

Selected best model (human-readable).

Model Run History

Data frame of all model evaluations with fitness values.

Search History

List with iteration-level history: starting.points.history, local.best.history, tabu.elements.history, neighbors.history.

Details

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.

See also

tabuControl for control parameters, detect_move for move detection, is_move_tabu for tabu checking, perturb_2bit for perturbation

Author

Zhonghui Huang

Examples

# \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
  )
)
#> 
#> 
#> 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
# }