compare_prmNlme: Compare NLME parameter estimates across multiple runs

In Certara.Xpose.NLME: Enhances 'xpose' Diagnostics for Pharmacometric Models from 'Certara.RsNLME' and Phoenix NLME

Compare NLME parameter estimates across multiple runs

Description

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.

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().

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.

See Also

get_summaryNlme(), get_prmNlme(), get_overallNlme(), xposeNlme()

Examples

## Not run: 
# 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)

## End(Not run)

Certara.Xpose.NLME documentation built on Oct. 1, 2026, 1:08 a.m.