Executes an NLME shotgun covariate search

Usage

shotgunSearch(
  model,
  hostPlatform = NULL,
  params,
  covariateModel,
  runInBackground = FALSE,
  archiveResults = TRUE,
  runLabel = NULL,
  ...
)

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

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 shotgun_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.

...

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 shotgun 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 ("shotgun"), 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 ShotgunNlmeJob 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 = 2,
                 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("V2", "Cl2"),
                      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
host <- hostParams(parallelMethod = "MULTICORE",
                   hostName = "local",
                   numCores = 8,
                   sharedDirectory = tempdir())

# Define the engine parameters
params <- engineParams(model, fastOptimization = TRUE, numIterations = 7)

# Define covariate model
cp <- covariateModel(model)

# Perform shotgun search
OverallDF <-  shotgunSearch(model = model,
                            hostPlatform = host,
                            params = params,
                            covariateModel = cp,
                            runInBackground = FALSE)
} # }

Executes an NLME shotgun covariate search

Usage

Arguments

Value

See also

Examples