Executes an NLME profile perturbation

Executes an NLME profile perturbation. Foreground runs return a typed profileResult data frame; background runs return a ProfileNlmeJob that the user materialises later via collectJob().

Usage

profilePertubate(
  model,
  hostPlatform = NULL,
  params = NULL,
  profiles,
  sortColumns = SortColumns(""),
  scenarios = list(),
  runInBackground = FALSE,
  ...,
  saveResult = TRUE
)

Arguments

model

PK/PD model. Required; profile cannot run without a model to derive the working directory and dataset from.

hostPlatform

How to execute the run (NlmeParallelHost).

params

Engine parameters (NlmeEngineExtraParams). Defaults to engineParams(model) when NULL.

profiles

Profiles to perturbate (ProfileParameters).

sortColumns

Optional list of columns to sort and fit (SortColumns).

scenarios

Optional list of scenarios to fit (NlmeScenario).

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.

...

Reserved for future use.

saveResult

When TRUE (the default), collectJob() saves a self-describing <workingDir>/profile_<sanitizedModelName>_<YYYYMMDD_HHMMSS>.rds alongside the result. sanitizedModelName is derived from model@modelInfo@modelName by replacing every character outside [A-Za-z0-9._-] with _; if the result is empty or contains no alphanumerics, the literal string model is used instead. The timestamp is the wall-clock start of the engine call, formatted as YYYYMMDD_HHMMSS in the local time zone. Honoured on both foreground and background paths (background runs save the RDS at the user-facing collectJob(job) call).

Value

If runInBackground = FALSE, an annotated profileResult data frame (Scenario, Theta, Estimate, LogLik, RetCode, Delta, Percent columns plus optional sort columns; carries params, runMode = "profile", runTime, RsNLMEVersion, and profileRunDir attributes). Otherwise a ProfileNlmeJob object; materialise later via collectJob(), which produces the same profileResult (and writes the RDS when saveResult = TRUE).

See also

collectJob, fitmodel, stepwiseSearch, hostParams, engineParams

Examples

if (FALSE) { # \dontrun{
  model <- pkmodel(
    parameterization = "Clearance",
    numCompartments = 2,
    data = pkData,
    ID = "Subject",
    Time = "Act_Time",
    A1 = "Amount",
    CObs = "Conc",
    workingDir = tempdir()
  )

  host <- hostParams(
    sharedDirectory = tempdir(),
    parallelMethod = "MULTICORE",
    hostName = "local",
    numCores = 4
  )

  profile1 <- ProfileVar("tvV",  9.548, "-2,2")
  profile2 <- ProfileVar("tvCl", 0.919, "-0.5,1.5")
  profiles <- ProfileParameters("USE_DELTA", c(profile1, profile2))

  result <- profilePertubate(
    model        = model,
    hostPlatform = host,
    params       = engineParams(model, method = 3, numIterations = 1),
    profiles     = profiles
  )
} # }