Runs a 1-bit neighbourhood local search on a binary-coded model string and returns a data frame of candidate models with their computed fitness (and ranks).
Usage
runlocal(
dat,
param_table = NULL,
search.space = c("ivbase", "oralbase"),
no.cores = NULL,
start.string = NULL,
diff_tol = 1,
penalty.control = penaltyControl(),
precomputed_results_file = NULL,
foldername = NULL,
filename = "test",
.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().- start.string
Optional numeric/integer vector of 0 or 1 values giving the starting binary code.
- diff_tol
A numeric value specifying the significance difference threshold. Values within this threshold are considered equal and receive the same rank. Default is 1.
- 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".
- .modEnv
Optional environment used to persist state across calls (e.g., cached parameter tables and precomputed results). When
NULL, a new environment is created.- verbose
Logical. If TRUE, print progress messages.
- ...
Additional arguments passed to
mod.run().
Value
A data frame where each row corresponds to a unique candidate model. Columns include the binary encoding (one column per bit), the computed "fitness", and the resulting "rank".
Details
For each position in the starting binary code, runlocal() constructs a
candidate by flipping that single bit (a 1-bit flip proposal). Some model
components are encoded by linked two-bit schemes (e.g., "no.cmpt1"/"no.cmpt2"
and "rv1"/"rv2"); when a proposal targets the second bit of a linked pair,
a feasibility rule is applied to maintain a valid encoding.
Each candidate is then canonicalised/validated using
validStringbinary before evaluation. Fitness is obtained by
calling mod.run for each candidate and results are ranked using
rank_new.
If ".modEnv" is supplied and contains the GA iteration counter ".modEnv$r", local search does not advance this counter; implementations may decrement ".modEnv$r" (with a lower bound of 1) so that local search does not consume a GA "round".
Examples
# \donttest{
dat <- pheno_sd
# Example best model binary code
current_code <- c(1, 0, 1, 0, 0, 0, 1, 0, 0, 1, 1, 0)
param_table <- initialize_param_table()
param_table$init[param_table$Name == "lcl"] <- log(0.008)
param_table$init[param_table$Name == "lvc"] <- log(0.6)
# Run local search
result_local <- runlocal(
dat = dat,
search.space = "ivbase",
start.string = current_code,
filename = "local_search_test",
saem.control = nlmixr2est::saemControl(logLik = TRUE,nBurn=15,nEm=15)
)
#>
#>
#> 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(result_local)
#> Error: object 'result_local' not found
# }