Executes an NLME simple estimation with sort keys and given scenarios

Usage

sortfit(
  model,
  hostPlatform = NULL,
  params,
  sortColumns,
  scenarios = list(),
  simpleTables,
  runInBackground = FALSE,
  filesToReturn = "*",
  ...,
  saveResult = TRUE
)

Arguments

model

PK/PD model class object.

hostPlatform

Host definition for model execution. See hostParams. If missing, PhoenixMPIDir64 is given and MPI is installed, MPI local host with 4 threads is used. If MPI is not found, local host without parallelization is used.

params

Engine parameters. See engineParams. If missing, default parameters generated by engineParams(model) are used.

sortColumns

List of sort columns. See SortColumns. If missing, empty sort columns argument is used and NLME dataset is used as is.

scenarios

List of scenarios with different sets of covariates. See NlmeScenario If missing, all covariates effects are considered as enabled.

simpleTables

Optional list of simple tables. See tableParams. By default a table named 'posthoc.csv' is returned with structural parameters values for all source data rows.

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.

filesToReturn

Used to specify which files to be outputted to the model directory and loaded as returned value. By default, all the applicable files listed in the Value section will be outputted to the model directory and loaded as returned value. Only those files listed in the Value section can be specified. Simple regex patterns are supported for the specification.

...

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

saveResult

When TRUE (the default), collectJob() writes a self-describing <workingDir>/sortfit_<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, the same named list of data frames fitmodel produces, with scenario and sort columns appended (see Details). The list carries params, runMode = "sortfit", runTime, and RsNLMEVersion attributes. Otherwise a SortByNlmeJob object; materialise later via collectJob(), which produces the same result list (and writes the RDS when saveResult = TRUE).

Details

All the results in tabular format have scenario column and sorts columns appended. The resulted logs (nlme7engine.log, err1.txt, dmp.txt, out.txt) are appended with a row delimiter where the name of the Scenario and sort values are specified.

Non-loaded but returned files

The non-loaded but returned files in the model working directory are:

err1.txt - concatenated for all runs detailed logs for all steps of optimization,
out.txt - general pivoted information about results,
doses.csv - information about doses given for all subjects,
iniest.csv - information about initial estimates

Examples

if (FALSE) { # \dontrun{
input_data <- pkData

model <-
  pkmodel(numCompartments = 2,
          data = input_data,
          ID = "Subject",
          Time = "Act_Time",
          A1 = "Amount",
          CObs = "Conc",
          workingDir = tempdir())

model <-
  addCovariate(model,
               covariate = "BodyWeight",
               direction = "Backward",
               center = "Mean",
               effect = c("V", "Cl"))

# multicore
multicoreHost <-
   hostParams(parallelMethod = "Multicore",
              hostName = "multicore",
              numCores = 4,
              sharedDirectory = tempdir())

# specify scenarios
CovariateEffectNames <- listCovariateEffectNames(model)
combinations <-
  combn(c("", CovariateEffectNames),
        length(CovariateEffectNames),
        simplify = FALSE)

scenarioNames <-
  lapply(combinations,
         function(x) {paste(x, collapse = " ")})

scenarios <-
  lapply(scenarioNames,
         function(x, CovariateEffectNames) {
           CovariateCombinations <- unlist(strsplit(x, " ", fixed = TRUE))
           scenarioIndex <-
             paste(which(CovariateEffectNames %in% CovariateCombinations,
                         arr.ind = TRUE),
                         collapse = ", ")
           NlmeScenario(trimws(x), scenarioIndex)
         },
         CovariateEffectNames)

res <-
  sortfit(model,
          hostPlatform = multicoreHost,
          params = engineParams(model, numIterations = 5, fastOptimization = TRUE),
          sortColumns = SortColumns("Gender"),
          scenarios = scenarios)

} # }