Executes an NLME simple estimation

Usage

fitmodel(
  model,
  hostPlatform = NULL,
  params,
  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.

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

Logical; if TRUE (default), the returned list is written to <workingDir>/fitmodel_<sanitizedModelName>_<YYYYMMDD_HHMMSS>.rds so the run becomes self-describing on disk. 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. For runInBackground = TRUE, the save happens at collectJob() time rather than when fitmodel() returns. A failing write produces a warning, never an error.

Value

if runInBackground is FALSE, a list with main resulted dataframes is returned:

Overall
ConvergenceData
residuals
Secondary
StrCovariate - if continuous covariates presented
StrCovariateCat - if categorical covariates presented
theta
posthoc table
posthocStacked table
Requested tables

nlme7engine.log textual output is returned and loaded with the main information related to fitting. dmp.txt structure with the results of fitting (including LL by subject information) is returned and loaded. These 2 files are returned and loaded irrespective of filesToReturn argument value.

For individual models, additional dataframe with partial derivatives is returned:

ParDer

For population models and the method specified is NOT Naive-Pooled, additional dataframes are returned:

omega
Eta
EtaStacked
EtaEta
EtaCov
EtaCovariate - if continuous covariates presented
EtaCovariateCat - if categorical covariates presented
bluptable.dat

If standard error computation was requested and it was successful, additional dataframes are returned:

thetaCorrelation
thetaCovariance
Covariance
omega_stderr

If nonparametric method was requested (numIterNonParametric > 0) and the method specified in engineParams is NOT Naive-Pooled, additional dataframes are returned:

nonParSupportResult
nonParStackedResult
nonParEtaResult
nonParOverallResult

if runInBackground is TRUE, a FitNlmeJob object is returned. Pass it to collectJob() when the engine has finished to materialise the same list described above.

`filesToReturn` with `Certara.Xpose.NLME`

If filesToReturn is used and "ConvergenceData.csv" and "residuals.csv" are not in the patterns, these files won't be returned and loaded. These files are essential for Certara.Xpose.NLME::xposeNlmeModel and Certara.Xpose.NLME::xposeNlme functions. This makes impossible to use the resulted object in Certara.Xpose.NLME functions.

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

Self-describing run context

The returned list also carries five run-context elements that make the object self-describing:

model - the input NlmePmlModel as it was at the start of the run (with @modelInfo@workingDir pointing at the artifacts).
params - the resolved NlmeEngineExtraParams actually used.
runMode - the string "fitmodel".
runTime - a list with start, end, and elapsed wall-clock times measured around the engine call. This is distinct from the engine-reported CPU time in nlme7engine.log.
RsNLMEVersion - the package version that produced the result.

No host, machine name, user name, password, or private key path is ever placed in the returned value or in the saved file.

Examples

if (FALSE) { # \dontrun{

 # Define the host
 host <- hostParams(sharedDirectory = tempdir(),
                    parallelMethod = "None",
                    hostName = "local",
                    numCores = 1)
 # Define the model
 model <- pkmodel(numComp = 2,
                  absorption = "FirstOrder",
                  ID = "Subject",
                  Time = "Act_Time",
                  CObs = "Conc",
                  Aa = "Amount",
                  data = pkData,
                  modelName = "PkModel",
                  workingDir = tempdir())

 Table01 <- tableParams(name = "SimTableObs.csv",
                        timesList = "0,1,2,4,4.9,55.1,56,57,59,60",
                        variablesList = "C, CObs",
                        timeAfterDose = FALSE,
                        forSimulation = FALSE)

 # Update fixed effects
 model <- fixedEffect(model,
                     effect = c("tvV", "tvCl", "tvV2", "tvCl2"),
                     value = c(16, 41, 7, 14))

 # Define the engine parameters
 params <- engineParams(model)
 # Fit model
 res <- fitmodel(model = model,
                 hostPlatform = host,
                 params = params,
                 simpleTables = Table01)
} # }