Executes an NLME stepwise covariate search

Usage

stepwiseSearch(
  model,
  hostPlatform = NULL,
  params,
  covariateModel,
  stepwiseParams,
  runInBackground = FALSE,
  ...
)

Arguments

model: PK/PD model class object.
hostPlatform: Host definition for model execution. See hostParams. If missing, multicore local host with 4 threads is used.
params: Engine parameters. See engineParams. If missing, default parameters generated by engineParams(model) are used.
covariateModel: Covariate Effects Model providing the relationship between covariates and structural parameters to test (covariateModel(model)).
stepwiseParams: Stepwise parameters defining decision tree. See StepwiseParams
runInBackground: Set to TRUE to run in background and return prompt.
...: Additional arguments for hostParams or arguments available inside engineParams functions. If engineParams arguments are supplied through both params argument and additional argument (i.e., ellipsis), then the arguments in params will be ignored and only the additional arguments will be used with warning. If hostParams arguments are supplied through both the hostPlatform argument and the ellipses, values supplied to hostPlatform will be overridden by additional arguments supplied via the ellipses e.g., ....

Value

if runInBackground = FALSE, a data frame is returned with stepwise search results, i.e. "Overall" comma separated file. Otherwise the StepwiseNlmeJob class object is returned.

Examples

# \donttest{
# Define the model
model <- pkmodel(numCompartments = 1,
                 data = pkData,
                 ID = "Subject",
                 Time = "Act_Time",
                 A1 = "Amount",
                 CObs = "Conc",
                 workingDir = tempdir())

# Add Gender covariate of type categorical
model <- addCovariate(model,
                      covariate = "Gender",
                      type = "Categorical",
                      effect = c("V", "Cl"),
                      levels = c(0, 1),
                      labels = c("Female", "Male"))

# Add Bodyweight covariate of type continuous
model <- addCovariate(model,
             covariate = "BodyWeight",
             type = "Continuous",
             direction = "Backward",
             center = "Mean",
             effect = c("V", "Cl"))

# Define the host
defaultHost <- hostParams(parallelMethod = "MULTICORE",
                   hostName = "local",
                   numCores = 8,
                   sharedDirectory = tempdir())

# Define the engine parameters
params <- engineParams(model, numIterations = 6)

# Define covariate model
cp <- covariateModel(model)

# Define the stepwise parameters
sp <- StepwiseParams(0.01, 0.001, "-2LL")

# Perform stepwise search
OverallDF <-  stepwiseSearch(model = model,
                      hostPlatform = defaultHost,
                      params = params,
                      covariateModel = cp,
                      stepwiseParams = sp,
                      runInBackground = FALSE)
#> Stepwise Job
#> 
#> NLME Job
#> 
#> Preparing files for Stepwise Covariate Search run
#> 
#> ----------------------------------------------------------------------
#> Processing scenarios:
#> "Base Model, no covariates", " V-Gender", " V-BodyWeight", " Cl-Gender", " Cl-BodyWeight"
#> ----------------------------------------------------------------------
#> 
#> Compiling 1 of 1 NLME models
#> TDL5 version: 25.7.1.1
#> 
#> Status: OK
#> License expires: 2026-08-06
#> Refresh until: 2025-09-05 07:01:25
#> Current Date: 2025-08-06
#> The model compiled
#> 
#> Num Jobs/Completed/Failed:5/0/0
#> 
#> Num Jobs/Completed/Failed:5/0/0
#> 
#> Num Jobs/Completed/Failed:5/0/0
#> 
#> Num Jobs/Completed/Failed:5/0/0
#> 
#> Num Jobs/Completed/Failed:5/0/0
#> 
#> Num Jobs/Completed/Failed:5/5/0
#> 
#> Trying to generate job results...
#> Done generating job results.
#> Find effect to add that reduces -2LL the most:
#> cstep001  V-Gender 1000     2304.989457 ( 2298.354560 +6.634897 ) < 2318.629980 )
#> cstep002  V-BodyWeight 0100   X 2326.824177 ( 2320.189280 +6.634897 ) > 2318.629980 )
#> cstep003  Cl-Gender 0010   X 2360.440537 ( 2353.805640 +6.634897 ) > 2318.629980 )
#> cstep004  Cl-BodyWeight 0001   X 2328.560277 ( 2321.925380 +6.634897 ) > 2318.629980 )
#> cstep001  V-Gender 1000 chosen, -2LL = 2298.354560
#> ----------------------------------------------------------------------
#> Processing scenarios:
#> " V-Gender V-BodyWeight", " V-Gender Cl-Gender", " V-Gender Cl-BodyWeight"
#> ----------------------------------------------------------------------
#> 
#> Compiling 1 of 1 NLME models
#> TDL5 version: 25.7.1.1
#> 
#> Status: OK
#> License expires: 2026-08-06
#> Refresh until: 2025-09-05 07:01:25
#> Current Date: 2025-08-06
#> The model compiled
#> 
#> Num Jobs/Completed/Failed:3/0/0
#> 
#> Num Jobs/Completed/Failed:3/0/0
#> 
#> Num Jobs/Completed/Failed:3/0/0
#> 
#> Num Jobs/Completed/Failed:3/0/0
#> 
#> Num Jobs/Completed/Failed:3/0/0
#> 
#> Num Jobs/Completed/Failed:3/3/0
#> 
#> Trying to generate job results...
#> Done generating job results.
#> Find effect to add that reduces -2LL the most:
#> cstep005  V-Gender V-BodyWeight 1100   X 2306.569717 ( 2299.934820 +6.634897 ) > 2298.354560 )
#> cstep006  V-Gender Cl-Gender 1010   X 2330.298417 ( 2323.663520 +6.634897 ) > 2298.354560 )
#> cstep007  V-Gender Cl-BodyWeight 1001   X 2308.244297 ( 2301.609400 +6.634897 ) > 2298.354560 )
#> 
#> No effect chosen to add
#> Find effect to subtract that increases -2LL the least:
#> cstep000  0000   X 2307.802414 ( 2318.629980 -10.827566 ) > 2298.354560 )
#> 
#> No effect chosen to subtract
#> 
#> Scenario to use = cstep001  V-Gender 1000
#> 
#> Summarizing stepwise covariate search results for 8 scenarios
#> 
#> Finished summarizing results. Transferring data and loading the results...
# }

Executes an NLME stepwise covariate search

Usage

Arguments

Value

See also

Examples