Skip to contents

Build a fused fit + bootstrap parameter summary

get_bootSummaryNlme.Rd

Companion to get_summaryNlme() for Certara.RsNLME::bootstrap() results. Combines original-fit columns (Estimate, %RSE, Shrinkage (%)) with per-replicate bootstrap columns (Bootstrap estimate (<metric>), Bootstrap <pct>% CI) using the same transform / shrinkage machinery.

Usage

get_bootSummaryNlme(
  bootResult,
  xpdb = NULL,
  transform = list(),
  units = list(),
  metric = c("Median", "Mean"),
  ci_level = NULL,
  return_code_ok = 1:3,
  digits = 3
)

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

Arguments

bootResult

Object returned by Certara.RsNLME::bootstrap() (an rsnlme_boot list of CSV-derived tables). Must carry at least BootOverall (with Replicate + ReturnCode columns), BootThetaStacked, and BootOmegaStacked.

xpdb

Optional xpose_data object from xposeNlme() / xposeNlmeModel(). When supplied, used as the original-fit source.

transform

Named list of per-parameter transforms keyed by parameter label. Same contract as get_summaryNlme()'s transform argument: 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 (a warning fires for a custom transform supplied without name). Applied to both the original-fit rows and the per-replicate bootstrap pool.

units

Named character vector (or list of length-1 character) keyed by parameter label, overriding the real-units Unit column for any row. Forwarded to get_summaryNlme() (m3) / the fitSummary pipeline (m2) and applied to the bootstrap-only output on m1. Keys not present in the relevant section emit a single warning and are ignored.

metric

"Median" (default) or "Mean" – statistic for the Bootstrap estimate (<metric>) column.

ci_level

Numeric in (0, 1); width of the percentile CI. When NULL (default) it inherits the bootstrap run's confidenceLevel (stored on bootResult), falling back to 0.95 when that metadata is absent. An explicit value always overrides.

return_code_ok

Integer vector of ReturnCode values to accept; replicates outside this set are dropped. Defaults to 1:3.

digits

Significant-digits count applied via signif() to the bootstrap columns and, when an original-fit summary is present, to the stored numeric Estimate, %RSE, and Shrinkage (%). Defaults to 3. The print.bootSummaryNlme method also honours digits for displayed precision (by setting pillar.sigfig for the duration of the print), so the original-fit columns show the same number of significant figures on screen as are stored – matching the pre-formatted bootstrap columns, which already carry digits in their character values.

x

A bootSummaryNlme tibble returned by get_bootSummaryNlme().

...

Further arguments passed to the underlying tibble print method.

Value

A tibble (class bootSummaryNlme) with Section, Parameter (carrying a (CV%) / (SD) / custom scale flag when a non-identity transform is active), optional original-fit columns (Estimate, %RSE, Shrinkage (%)), an optional real-units Unit column, and the two bootstrap columns (the CI formatted as "lo - hi"). Carries the attributes n_used, n_total, ci_level, return_code_ok, transform, metric, fitSource ("xpdb" / "embedded" / "none"). The bootSummaryNlme class carries a print method that honours the digits argument for displayed precision.

Details

Three input modes drive what columns appear in the output:

m1: bootResult only

No original-fit source; output is bootstrap-only – Section, Parameter, optional Unit, Bootstrap estimate (<metric>), and Bootstrap <pct>% CI. A message() notes that original-fit columns are unavailable and how to include them (initialEstimates = TRUE or xpdb). The residual-transform advisory (see below) still fires, since the default's fitness can't be ruled out without PML either way.

m2: bootResult carries an embedded fitSummary

fitSummary is the original-fit source (when initialEstimates = TRUE was used on the bootstrap call). Omega off-diagonal covariance rows (Diagonal = FALSE) are dropped so the original-fit side stays variance-scale, matching m3's "off-diagonals excluded" contract; older fitSummary tables without a Diagonal column are treated as diagonal-only.

m3: explicit xpdb argument

Original-fit columns come from get_summaryNlme(xpdb, ...). If bootResult$fitSummary is also non-NULL a one-shot warning fires and xpdb wins.

Per-replicate filtering: replicates whose BootOverall$ReturnCode falls outside return_code_ok are dropped silently before the metric and percentile CI are computed. The BootOverall table on the rsnlme_boot is the single source of truth – no on-disk reads.

The CI bounds are the empirical (1 - ci_level) / 2 and 1 - (1 - ci_level) / 2 quantiles of the kept replicates, computed with stats::quantile()'s default method (type 7).

Soft-degrade for missing stacks: BootSigmaStacked and BootSecondaryStacked are net-new in the corresponding Certara.NLME8 release. When either is NULL (older NLME8 build) the function emits NA bootstrap cells for that section and a single warning naming the missing stacks plus the installed Certara.NLME8 version. BootThetaStacked and BootOmegaStacked predate the new release and are always available.

Output formatting (shared with get_summaryNlme()): when a non-identity transform is active the values are shown on the transformed scale only, and the scale label is appended to the shared Parameter name in parentheses – nV (CV%), CEps (SD), or a custom name for list(fn=, dfn=, name=) specs. Identity / raw rows keep the bare name. The Unit column carries real units only and is dropped when every row is dimensionless. The bootstrap CI is a single character column formatted as "lo - hi" (a dash range, no brackets). Numeric digits is applied via signif() to both the bootstrap columns and, when present, the original-fit Estimate, %RSE, and Shrinkage (%).

Residual-shape advisories: a per-sigma warning fires when PML classifies a sigma as additive or otherwise non-proportional while it is reported with the multiplicative_cv default. Classification requires PML, which is only available when xpdb is supplied (m3); on m1/m2 no per-sigma warning is emitted. The general default-transform message() is broader: it fires for any defaulted sigma that isn't proven proportional, which on m1/m2 (no PML to check) means it always fires – mirroring get_summaryNlme()'s own no-PML behaviour. Set options(xposeNlme.summary.quiet_default_warning = TRUE) to silence it.

See also

get_summaryNlme()

Examples

if (FALSE) { # \dontrun{
fit_boot <- Certara.RsNLME::bootstrap(model, ...)

# m1: bootstrap-only summary, no fit source.
get_bootSummaryNlme(fit_boot)

# m2: fused summary using the bootstrap's embedded fitSummary
# (initialEstimates = TRUE on the bootstrap call).
fit_boot_init <- Certara.RsNLME::bootstrap(model,
                                           initialEstimates = TRUE, ...)
get_bootSummaryNlme(fit_boot_init)

# m3: fused summary against an explicit xpdb -- preferred when the
# xpdb has its own provenance (covariates, residuals, posthoc) that
# fitSummary doesn't capture.
xp <- xposeNlmeModel(fit_model)
get_bootSummaryNlme(fit_boot, xpdb = xp)

# Custom transform on a sigma applied to both original-fit and
# bootstrap columns; `name` sets the scale flag on the parameter name.
get_bootSummaryNlme(
  fit_boot_init,
  transform = list(
    CEps = list(
      fn  = function(s) 200 * s,
      dfn = function(s) 200,
      name = "2xCV%"
    )
  )
)
} # }