nlmixr2auto (version 1.0.0)

sf.operator: Stepwise model building operator for model selection

Description

Implements automated stepwise model selection for structural and statistical components of nonlinear mixed-effects models, evaluating the number of compartments, elimination type, inter-individual variability, correlation structures, and residual error models.

Usage

sf.operator(
  dat,
  start.mod = NULL,
  search.space = "ivbase",
  no.cores = NULL,
  param_table = NULL,
  steps = 123567,
  dynamic_fitness = TRUE,
  penalty.control = penaltyControl(),
  precomputed_results_file = NULL,
  foldername = NULL,
  filename = "test",
  .modEnv = NULL,
  verbose = TRUE,
  ...
)

Value

An object of class "sfOperatorResult" with the following elements:

• "Final Best Code": Named integer vector of the selected model code.

• "Final Best Model Name": Character string identifying the best model.

• "Stepwise Best Models": Data frame summarizing the best model selected at each executed step.

• "Stepwise History": Named list containing full results for each step using descriptive step names.

• "Model Run History": Data frame containing all model runs performed during the procedure.

Arguments

dat

A data frame containing pharmacokinetic data in standard nlmixr2 format, including "ID", "TIME", "EVID", and "DV", and may include additional columns.

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

param_table

Optional data frame of initial parameter estimates. If NULL, the table is generated by auto_param_table().

steps

Numeric or character vector defining the sequence of steps to be executed. Each digit corresponds to a specific step:

1

Number of compartments

2

Elimination type

3

IIV on Km

4

IIV on Ka

5

Forward selection of structural IIV

6

Correlation between random effects

7

Residual error model

dynamic_fitness

Logical; if TRUE, the set of penalty terms may change dynamically across steps.

penalty.control

An object created by penaltyControl() defining penalty terms used in the fitness calculation.

precomputed_results_file

Optional path to a CSV file of previously computed model results used for caching.

foldername

Character string specifying the name of the folder to be created in the current working directory to store intermediate results. If NULL, a name is generated automatically.

filename

Optional character string used as a prefix for output files. Defaults to "test".

.modEnv

Optional environment used internally to store model indices, cached parameter tables, and results across steps.

verbose

Logical. If TRUE, print progress messages.

...

Additional arguments passed to mod.run().

Author

Zhonghui Huang

Details

The stepwise procedure iterates over the specified steps in order. At each step, only a single component of the model is modified, while all other structural and statistical elements remain unchanged. Model comparison is based on a scalar fitness criterion returned by the estimation routine.

The order and inclusion of steps are controlled by the user via a numeric step code sequence. Steps that are not applicable to the current model configuration may be skipped automatically.

The final best model is defined as the model with the minimum fitness value in the last completed estimation round.

See Also

step_compartments, step_elimination, step_iiv_km, step_iiv_f, step_correlation, step_rv

auto_param_table, base_model, penaltyControl, mod.run, ppkmodGen, step_compartments, step_elimination, step_iiv_km, step_iiv_ka, step_iiv_f, step_correlation, step_rv

Examples

# \donttest{
out<-sf.operator(
  dat = pheno_sd,
  steps = 1234,
  search.space = "ivbase",
  saem.control = nlmixr2est::saemControl(
    seed = 1234,
    nBurn = 200,
    nEm   = 300,
    logLik = TRUE
  )
)
print(out)
# }