Skip to contents

Stepwise model building operator for model selection

Source: R/sf.operator.R
sf.operator.Rd

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

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

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.

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

Author

Zhonghui Huang

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
  )
)
#> 
#> 
#> 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(out)
#> Error: object 'out' not found
# }