Executes an NLME stepwise covariate search

Usage

stepwiseSearch(
  model,
  hostPlatform = NULL,
  params,
  covariateModel,
  stepwiseParams,
  runInBackground = FALSE,
  archiveResults = TRUE,
  runLabel = NULL,
  updateInitialEstimates = 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

Logical. When TRUE, the wrapper starts the engine asynchronously and returns a job object immediately; pass that object to collectJob() when the run has finished to obtain the typed result. When FALSE (the default), the wrapper blocks until the engine completes and returns the result directly.

Background execution is supported only on Linux hosts, whether local or remote: a local host whose hostType is "linux" (the default on Linux workstations), or a remote host with hostType "linux", "RHEL", or "UBUNTU". It is not supported on Windows (hostType = "windows", including the default local host when R runs on Windows): leave the argument at FALSE. Passing TRUE on a Windows host stops with an error. Remote Windows hosts are not supported at all.

archiveResults

Logical. When TRUE (default), NLME8 archives per-scenario results into a self-contained run folder under the model working directory. The returned data frame carries a searchRunDir attribute pointing to the archive folder. Archive failures are non-fatal (warn only).

runLabel

Optional character string appended to the auto-generated timestamp in the archive folder name, e.g. "baseModel" produces stepwise_20260319_143045_baseModel. Must contain only letters, digits, dots, hyphens, or underscores. If the resulting folder already exists, a numeric suffix (_1, _2, ...) is added with a warning. Ignored (with a warning) when archiveResults = FALSE.

updateInitialEstimates

Logical. When TRUE, after each stepwise selection the shared input model's initial estimates are rewritten from the winning scenario's dmp.txt so subsequent candidate runs start from the previous step's estimates. Speeds up convergence on later steps and tends to stabilise the search. Default FALSE preserves the existing behavior. Implementation lives in NLME8; this flag is forwarded via the NLME_SCM_UPDATE_INITIALS environment variable (also propagated to remote run scripts).

Notes:

When TRUE, the base (no-covariate) model runs on its own first and its converged estimates are written into the shared input model before the first forward-addition candidate batch, so that round starts from the base model's final estimates. When FALSE, the base model and the first-round candidates run together in a single parallel batch, because those candidate fits do not depend on the base estimates.
Every selection that updates the model invalidates the stepwise compile cache, so the next batch of candidate runs will recompile the NLME executable from the rewritten model. Expect a small per-step compile-time overhead in exchange for the convergence benefit.
The user's input .mdl file in the model working directory is snapshotted at the start of the search and restored on exit, so the working directory is left untouched regardless of how the search ends. The per-scenario archive (initial.mdl, wiped.mdl, final.mdl, etc.) is sourced from the per-scenario engine job directories and accurately reflects the evolving initials each scenario actually ran with.
Only candidate models that are evaluated for the first time after a selection take advantage of the carried-forward initials; any candidate whose covariate set was already evaluated in an earlier step is reused from the search history with its original estimates, so each unique covariate configuration is fit exactly once per search. This keeps each mask's OFV consistent across the forward and backward phases.

...

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, an scmSearchResult data frame is returned with stepwise search results, i.e. the "Overall" comma separated file, plus a custom print method and a searchType attribute. The data frame also carries the run context as attributes: params (resolved NlmeEngineExtraParams), runMode ("stepwise"), runTime (wall-clock list(start, end, elapsed) measured around the engine call), and RsNLMEVersion (the package version that produced the result). If archiving succeeds it also carries a searchRunDir attribute. Otherwise (when runInBackground = TRUE) the StepwiseNlmeJob class object is returned. Backgrounded jobs can be materialised later via collectJob, which produces the same scmSearchResult (with archive when archiveResults = TRUE). Use summary() for a structured digest (best scenario, top ranking, run context). Use scmSearchTable for a presentation data.frame (stepwise decision table, or shotgun ranking plus covariate effects).

Examples

if (FALSE) { # \dontrun{
# 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)
} # }

Executes an NLME stepwise covariate search

Usage

Arguments

Value

See also

Examples