Creates xpose database from Certara.RsNLME objects

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

Usage

xposeNlmeModel(model, fitmodelOutput)

Arguments

model

NlmePmlModel model class object generated by Certara.RsNLME package. Optional when fitmodelOutput is a self-describing fit (carries $model); in that case the model is read from fitmodelOutput$model. When both are supplied, the explicit model argument wins.

fitmodelOutput

the output object of Certara.RsNLME::fitmodel() run. Newer versions of Certara.RsNLME return a self-describing list that carries the model and the resolved engine parameters; in that case xposeNlmeModel(fitmodelOutput) can be called with a single argument.

Value

xpdb object

Details

Not all functionality from the xpose package is supported.

Run metadata is stored in the summary tibble of the returned xpdb object. Access it directly with xpdb$summary or render it to the console with summary(xpdb). This is distinct from get_overallNlme(), which returns the Overall.csv fit-statistics table (objective function, AIC, BIC, and similar).

When fitmodelOutput is a self-describing fit that carries $params, $runTime, and/or $RsNLMEVersion, the summary tibble gains additional rows: ode_solver, rtol, atol, nmxstep, stderr_algorithm, stderr_method, xnorderagq, fastOptimization, runtime_wallclock, and RsNLMEVersion, plus timestart / timestop at the global problem. stderr_algorithm is the standard-error algorithm (Hessian / Sandwich / Fisher Score / Auto-Detect / None); stderr_method is the finite-difference scheme used for the standard-error computation (params@xstderr: none / central-difference / forward-difference) and is shown when the finite-difference flag is nonzero (IFLAGSTDERR / params@xstderr), even if the algorithm name could not be resolved (e.g. Auto-Detect with no resolution prose). Both SE rows are omitted for IT2S-EM, which cannot estimate standard errors. xnorderagq and fastOptimization only ever appear for FOCE-ELS/LAPLACIAN; xnorderagq is further omitted when the engine actually ran with OuterAD (which forces the adaptive Gaussian quadrature order to 1 internally). ode_solver, stderr_algorithm, and fastOptimization always reflect the engine's actual run (preferring nlme7engine.log over the params request whenever the log has the relevant flag) – params is only used as a fallback when the log lacks the flag (e.g. no log file at all).

The file-based xposeNlme(dir = ...) entry point recovers ode_solver, stderr_algorithm, stderr_method, xnorderagq, and fastOptimization from nlme7engine.log when the log records them, but never rtol, atol, nmxstep, runtime_wallclock, RsNLMEVersion, timestart, or timestop – those are not written to the engine log, only resolved by Certara.RsNLME at fit time. xposeNlme() also never reads args/params files (for example nlmeargs.txt, jobArgsCombined.txt, jobControlFile.txt): those record requested settings, which can go stale relative to what the engine actually ran, so surfacing them in xp$summary would be misleading. See xposeNlme for the full file-path contract.

The runtime row reports engine-reported CPU time, which sums across workers and can exceed the actual wait on multi-core runs; runtime_wallclock reports the elapsed wall-clock time from fitmodelOutput$runTime$elapsed and is generally smaller on multi-core runs.

Examples

if (FALSE) { # \dontrun{
library(Certara.RsNLME)
library(Certara.Xpose.NLME)

model <- pkmodel(
  parameterization = "Clearance",
  numCompartments = 2,
  data = pkData,
  ID = "Subject",
  Time = "Act_Time",
  A1 = "Amount",
  CObs = "Conc"
)

fit <- fitmodel(model)

# Two-argument form (works with all RsNLME versions):
xp <- xposeNlmeModel(model = model, fitmodelOutput = fit)

# One-argument form (RsNLME with self-describing fitmodel output):
xp <- xposeNlmeModel(fit)
} # }