Compare NLME parameter estimates across multiple runs — compare

Builds a single wide table comparing parameter estimates (and optional %RSE) across two or more NLME runs, alongside a block of run-level diagnostics (-2LL, OFV diff, method, RetCode, condition, condition basis, nSub, nObs, and total runtime). It is the multi-model sibling of get_summaryNlme(): where get_summaryNlme() summarises one xpose_data object, compare_prmNlme() lines several up side by side for run-record style model comparison.

Usage

compare_prmNlme(
  x = NULL,
  dir = ".",
  runs = NULL,
  auto_detect = TRUE,
  max_runs = NULL,
  transform = c("untransformed", "sqrt_om2", "sqrt_exp_om2_minus_1"),
  param_order = c("original", "alphabetical"),
  rse_separate = FALSE,
  drop_dOFV = FALSE,
  output_file = NULL,
  format = c("column", "row"),
  log_file = "Table_log.txt"
)

Arguments

x: Optional named list of xpose_data objects (or a single xpose_data). When supplied, dir / runs / auto_detect are ignored. List names become the column headers and must be unique.
dir: Directory scanned for runs when x is NULL (default the working directory).
runs: Optional character vector of run names (subfolders of dir) to load explicitly, in the given order. Overrides auto-detection.
auto_detect: Logical; when x and runs are NULL, scan dir for completed runs (default TRUE).
max_runs: Optional cap on the number of successfully loaded runs to include. NULL or "" includes all runs. Failed imports do not count toward the cap.
transform: One of "untransformed" (default), "sqrt_om2", or "sqrt_exp_om2_minus_1"; applied to diagonal OMEGA only.
param_order: One of "original" (default: first run's model order, with parameters unique to later runs appended in those runs' order) or "alphabetical".
rse_separate: Logical; when TRUE, %RSE is shown in its own set of rows (suffixed " (RSE)") rather than in-line with each estimate. Accepts the strings "YES"/"NO" for backward compatibility.
drop_dOFV: Logical; when TRUE, omit the OFV diff row. Accepts "YES"/"NO".
output_file: Optional path; when set, the full table is written as a CSV in the chosen format.
format: One of "column" (default, models as columns) or "row" (models as rows, transposed). Controls the CSV layout and is stored on the returned object so as_flextable.prmComparisonNlme() defaults to the same orientation.
log_file: Name of the excluded-run log written into dir during auto-detection (default "Table_log.txt"). Set to NULL to disable.

Value

A tibble of class prmComparisonNlme with a Description column followed by one column per run, carrying n_header, n_rse, nModels, run_labels, and format attributes.

Details

Runs can be supplied three ways:

As a pre-built named list of xpose_data objects (or a single xpose_data) via x. List names become the column labels.
By explicit run name via runs, loaded from dir with xposeNlme().
By auto-detection (auto_detect = TRUE, the default when x and runs are both NULL): dir is scanned for model files (*.mdl or *.mmdl, case-insensitive) whose same-named run output folder exists, in alphanumeric order. Name each model so its output folder matches the model file (e.g. run001.mmdl beside a run001/ folder). A run is only included when its nlme7engine.log is present; runs that fail to load are recorded in log_file (written into dir) and skipped.

The transform setting affects only diagonal OMEGA rows. Diagonal SIGMA rows are kept on the reported get_prmNlme() scale (for CEps this is the SD scale), so SIGMA values and %RSE do not change across transformation settings. %RSE on transformed OMEGA is propagated with the delta method.

The returned object carries n_header / n_rse attributes marking the leading diagnostic block and the trailing RSE block, which as_flextable.prmComparisonNlme() uses to draw separators. Rendering with flextable and CSV export via output_file are both optional; the core computation depends only on packages already imported by Certara.Xpose.NLME.

Timing

The diagnostic row total runtime (sec) is engine-reported CPU time: the sum of the runtime and covtime rows in xpdb$summary, which are parsed from nlme7engine.log at import. That total can differ substantially from the wall-clock elapsed time shown by print.rsnlme_fit / a fit object's runTime (especially on multi-core runs). See also get_overallNlme() for the same distinction, including optional runtime_wallclock when an xpdb was built via xposeNlmeModel().

Examples

if (FALSE) { # \dontrun{
# 1) Compare two already-imported runs.
xp1 <- xposeNlme(dir = "run001")
xp2 <- xposeNlme(dir = "run002")
compare_prmNlme(list(run001 = xp1, run002 = xp2))

# 2) Auto-detect every completed run under the working directory,
#    put %RSE on its own rows, and write a CSV.
tbl <- compare_prmNlme(
  rse_separate = TRUE,
  output_file  = "TableofParameters.csv"
)

# 3) Render the comparison as a flextable (requires the flextable and
#    officer packages).
flextable::as_flextable(tbl)
} # }