get_summaryNlme: Build a parameter summary table for an NLME 'xpdb'

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

Build a parameter summary table for an NLME xpdb

Description

Produces a single tibble combining fixed effects, random effects, residual errors, and secondary parameters, along with their estimates and ⁠%RSE⁠ on the chosen scale. Shrinkage for random effects and residual errors is also included. The transform applied to each row controls both the displayed Estimate and the corresponding ⁠%RSE⁠, which is computed on the transformed scale via the delta method. Built-in presets carry analytic derivatives; for transforms outside the catalog, supply a custom fn with its derivative dfn.

Usage

get_summaryNlme(
  xpdb,
  .problem = 1,
  .subprob = 0,
  .method = NULL,
  transform = list(),
  units = list(),
  shrinkage = c("engine", "sd", "var"),
  digits = NULL,
  append_flag = TRUE,
  emit_advisories = TRUE
)

## S3 method for class 'summaryNlme'
print(x, ...)

Arguments

xpdb	An xpose_data object created by xposeNlme() or xposeNlmeModel().
.problem	Problem number (default 1). Mirrors get_prmNlme().
.subprob	Subproblem number (default 0). Mirrors get_prmNlme().
.method	Estimation method filter (default NULL). Mirrors get_prmNlme().
transform	Named list of per-parameter transforms keyed by prmTable$label. Each value is either a preset string from the section's catalog or a list(fn = ..., dfn = ..., name = ...) spec, where the optional name sets the scale flag appended to the parameter name.
units	Named character vector keyed by prmTable$label that populates or overrides the Unit column with physical units for matching rows.
shrinkage	Shrinkage calculation method, one of "engine" (default), "sd", or "var". "engine": uses the standard-deviation-based shrinkage values reported directly by the engine (read from xpdb$summary) – eta shrinkage 1 - SD(\eta)/\omega (with \omega = \sqrt{\Omega}, the model standard deviation) and eps shrinkage 1 - SD(IWRES). Note the engine computes the eta SD with denominator n (population) but the eps SD with denominator n - 1 (sample). "sd": recomputes the standard-deviation-based shrinkage using R's sd() (denominator n - 1). This differs from "engine" only for eta shrinkage, since the engine's eps path already uses n - 1. "var": recomputes a variance-based shrinkage using R's var() (denominator n - 1) – eta shrinkage 1 - Var(\eta)/\Omega and eps shrinkage 1 - Var(IWRES). The recompute paths ("sd" / "var") use subject-level etas for eta shrinkage when the model has random effects (skipped for naive-pooled or any other no-ranef() fit) and the IWRES column in xpdb$data for eps shrinkage; multi-residual models additionally need the embedded PML source to map each ObsName row to its driving sigma.
digits	Optional significant-digits count. When non-NULL, signif() is applied to the stored numeric Estimate, ⁠%RSE⁠, and ⁠Shrinkage (%)⁠, and the print.summaryNlme method shows that many significant figures (by setting pillar.sigfig for the duration of the print). NULL (default) keeps full precision in both the stored values and the printed display.
append_flag	When TRUE (default), the scale flag (⁠CV%⁠ / SD / custom name) is appended to Parameter for non-identity transforms.
emit_advisories	When TRUE (default), the residual-transform advisory message and the per-sigma type warnings are emitted. Set to FALSE to silence both.
x	A summaryNlme tibble returned by get_summaryNlme().
...	Further arguments passed to the underlying tibble print method.

Details

Default transforms per section:

• Fixed effects: raw.

• Random effects (omegas): lognormal_cv, defined as 100 \sqrt{\exp(\omega^2) - 1}, where \omega^2 is the variance stored in prmTable$value.

• Residual error (sigmas): multiplicative_cv (100\sigma). This default is applied uniformly to every sigma, regardless of the error-model shape declared in PML – and choosing the wrong scale doesn't correct itself, it just mislabels the number. For purely additive or combined error models the %CV label is misleading – override with ⁠transform = list(<sigma> = "raw")⁠ (the engine reports the residual error as a standard deviation) or a custom fn.

  When the PML source is available, each sigma's shape is inferred directly from its observe() expression by differentiating it with respect to the error variable (base R's stats::D()) and checking whether that derivative is a constant (additive error) or proportional to the noise-free prediction with no curvature (proportional error – the one shape multiplicative_cv is exact for). This inference is syntax-only and best-effort: it works directly on whatever PML the xpdb happens to embed, without assuming it came from any particular model-building tool. The advisory message is skipped only when every defaulted sigma is proven proportional; it fires for additive error, for any other non-proportional shape (combined, power, ...), and whenever the shape can't be determined at all (a function outside D()'s derivative table, unusual syntax, or no PML source) – in that last case the safer default is to warn rather than assume. An extra per-sigma warning fires for any sigma whose inferred role is additive or otherwise non-proportional. Set emit_advisories = FALSE to silence both the message and the per-sigma warnings, or options(xposeNlme.summary.quiet_default_warning = TRUE) to silence only the message. get_bootSummaryNlme()'s bootResult-only and embedded-fitSummary input modes have no PML to check either, so they inherit this same "no PML source" behaviour: the default message always fires for a defaulted sigma, while the per-sigma warning (which needs a known shape to name) stays silent.

• Secondary: raw.

Built-in preset catalog:

• Fixed effects: raw (custom fn always available).

• Random effects: raw, lognormal_cv, normal_sd. normal_sd returns the standard deviation \sqrt{\Omega} (i.e. fn = sqrt(value)), not the variance.

• Residual error: raw, log_additive_cv, multiplicative_cv. log_additive_cv is 100 \sqrt{\exp(\sigma^2) - 1} and multiplicative_cv is 100\sigma.

Custom transform spec: ⁠transform = list(<label> = list(fn = function(x) ..., dfn = function(x) ..., name = ...))⁠. dfn is optional; when omitted, %RSE falls back to the raw scale and a single warning per call lists the affected parameters. name is the optional scale flag appended to the parameter name; a custom transform supplied without name triggers a warning and leaves the name unflagged.

Scale flag and units: when a non-identity transform is active the scale label is appended to Parameter in parentheses – ⁠nV (CV%)⁠, CEps (SD), or the custom name. Identity / raw rows keep the bare name. The Unit column carries physical units only (user units or the model's structural-parameter units) and is dropped when every row is dimensionless.

Off-diagonal omega/sigma rows are excluded entirely. transform and units are keyed by prmTable$label (the PML-source name – tvCl, nV, CEps); names not present among the labels emit a single warning per call and are ignored.

Value

A tibble (class summaryNlme) with columns Section, Parameter (carrying a ⁠(CV%)⁠ / (SD) / custom scale flag when a non-identity transform is active), Estimate, ⁠%RSE⁠, ⁠Shrinkage (%)⁠, and – only when at least one row resolves to a non-empty physical unit – Unit. The summaryNlme class carries a print method that honours the digits argument for displayed precision.

See Also

get_prmNlme(), get_overallNlme(), get_etaSubjectNlme()

Examples

## Not run: 
# 1) Default output on a log-normal IIV + proportional error model.
xp <- xposeNlmeModel(fit)
get_summaryNlme(xp)

# 2) Per-parameter override on an additive error model. The engine
#    reports residual error as a standard deviation, so `raw` shows the
#    SD directly (no misleading %CV flag).
get_summaryNlme(
  xp,
  transform = list(EEps = "raw"),
  units     = list(EEps = "ng/mL")
)

# 3) Custom transform for combined add-mult error.
get_summaryNlme(
  xp,
  transform = list(
    CEps = list(
      fn  = function(s) 100 * s,
      dfn = function(s) 100
    )
  )
)

## End(Not run)

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