Creates xpose database from Certara.RsNLME output files

Imports results of an NLME run into xpose database Use to import NLME model output files into xpdb object that is compatible with existing model diagnostic function in Xpose package.

Usage

xposeNlme(
  dir = "",
  modelName = "",
  dmpFile = "dmp.txt",
  dmp.txt = NULL,
  dataFile = "data1.txt",
  logFile = "nlme7engine.log",
  ConvergenceData = NULL,
  progresstxt = NULL
)

Arguments

dir: Path to NLME Run directory. Current working directory is used if dir not given.
modelName: name of the model to be written in xpdb$summary$value with run label
dmpFile: NLME generated output file.
dmp.txt: NLME generated output from dmpFile (substitutes dmpFile if presented).
dataFile: Input file for NLME Run.
logFile: engine log file
ConvergenceData: optional convergence info, as either a data frame (the long-format Scenario, Iter, Parameter, Value shape returned by Certara.RsNLME::fitmodel()) or a path to a CSV with the same columns (e.g. "ConvergenceData.csv"). When NULL (the default), dir is scanned for ConvergenceData.csv, then progresstxt / progress.txt is used as a fallback.
progresstxt: optional NLME-generated progress.txt with convergence info. Useful for SCM scenario folders and Phoenix temporary result folders where progress.txt is retained and ConvergenceData.csv may be absent. For normal Certara.RsNLME::fitmodel() keep-dirs prefer ConvergenceData.csv (auto-scanned) or ConvergenceData=; the job-folder progress.txt is usually deleted after summarize. When NULL (the default), progress.txt is only used as a fallback if ConvergenceData is not supplied and no ConvergenceData.csv is found in dir. An explicit path forces that file even if a CSV is also present; a missing explicit path is an error.

Value

xpdb object

Details

Not all functionality from the xpose package is supported.

Bootstrap working directories are not a supported xposeNlme() source: artifacts may be overwritten or replicate-concatenated (dmp.txt, progress.txt). When bootstrap markers are detected (Boot*.csv, bootstrap_nlme7engine.log, bootstrap_*.rds):

last-replicate dmp.txt typically has no residuals table and no residuals.csv – import stops with a message pointing at get_bootSummaryNlme;
if a residuals table is already present (embedded or leftover residuals.csv from a prior fitmodel()), import continues after a warning. Those CSVs may belong to a different fit (including different initial estimates, or bootstrap(..., overwriteFitDir = TRUE) that overwrote dmp.txt without replacing the CSVs). GOF is not the bootstrap last replicate.

For bootstrap parameter summaries, use get_bootSummaryNlme on the bootstrap() return value (not this directory). For GOF / convergence plots, import the original fit with xposeNlme() on the fit folder or xposeNlmeModel on the fit result.

Run metadata is stored in the summary tibble of the returned xpdb object (xpdb$summary, or rendered with summary(xpdb)). On this file-based entry point, every metadata row beyond the long-standing descr/ofv/method/runtime set is parsed from nlme7engine.log only – ode_solver, stderr_algorithm, stderr_method, xnorderagq, and fastOptimization appear when the log records them (missing fields are silently omitted, never an error), and the method row discriminates FOCE-ELS from LAPLACIAN using the log's Hessian-variant flag. stderr_algorithm and stderr_method are both omitted entirely for IT2S-EM (which cannot estimate standard errors); xnorderagq and fastOptimization only ever appear for FOCE-ELS/LAPLACIAN, and xnorderagq is further omitted when the log shows OuterAD (which forces the adaptive Gaussian quadrature order to 1 internally). epsshk/etashk are likewise omitted when not applicable (no residual-error model / the NAIVE-POOLED method, respectively).

xposeNlme() deliberately never reads rtol, atol, or nmxstep (not written to the engine log), never reads runtime_wallclock, RsNLMEVersion, timestart, or timestop (only known to Certara.RsNLME at fit time, not to the engine). Arguments files are intentionally not read, because requested settings can differ from the engine run.

Examples

if (FALSE) { # \dontrun{
# files in arguments supposed to be in the current working directory;
# ConvergenceData.csv (if present) is picked up automatically:
xp <- xposeNlme(
  dir = getwd(),
  modelName = "PMLModel",
  dmpFile = "dmp.txt",
  dataFile = "data1.txt",
  logFile = "nlme7engine.log"
)

# SCM / Phoenix folders that retain progress.txt but not
# ConvergenceData.csv:
xp <- xposeNlme(
  dir = "~/scm_archive/cstep000__0",
  modelName = "Base",
  dataFile = "../data1.txt",
  progresstxt = "progress.txt"
)

# using dmp.txt structure and Convergence Data loaded previously:
xp <- xposeNlme(
  dir = "~/Model1/",
  modelName = "Model1",
  dmp.txt = dmp.txt,
  dataFile = "Data.csv",
  logFile = "nlme7engine.log",
  ConvergenceData = ConvergenceData
)

# explore unique covariate plots specific to Certara.Xpose.NLME:
nlme.cov.splom(xp, covColNames = c("AGE", "WT"))
nlme.par.vs.cov(xp, covColNames = c("AGE", "WT"))

res_vs_cov(xp, covariate = "AGE", res = "IWRES")

# or use existing plotting functions from the xpose package
library(xpose)
dv_vs_pred(xp)
res_vs_idv(xp)
} # }