normalize_etas: Normalize etas by their omega- or empirical-SD-implied scale

In xpose.xtras: Extra Functionality for the 'xpose' Package

Normalize etas by their omega- or empirical-SD-implied scale

Description

Sets xpdb$normalize_etas, a top-level slot (alongside eg ⁠$covs⁠, see add_cov_association()) consumed by eta_grid()/ eta_vs_cov_grid()/eta_vs_contcov()/eta_vs_catcov(): each selected eta is divided by its typical scale – by default the standard deviation implied by its associated diagonal omega estimate (sqrt(omega)), same as recalc_shk() uses – before being plotted, so etas modeled on very different scales (eg a normally-distributed eta next to a log-normal one with a much larger omega) can be compared on one shared plot without the larger-scale eta dominating.

normalise_etas() is an alias, for the British/rest-of-world spelling.

Usage

normalize_etas(
  xpdb,
  ...,
  .use_sd = FALSE,
  .problem = NULL,
  .subprob = NULL,
  .method = NULL,
  quiet
)

normalise_etas(
  xpdb,
  ...,
  .use_sd = FALSE,
  .problem = NULL,
  .subprob = NULL,
  .method = NULL,
  quiet
)

Arguments

xpdb	<xpose_dataxpose::xpose_data> or xp_xtras object
...	<tidyselect> Which eta column(s) to (re)compute a normalization factor for. Defaults to every eta column for .problem.
.use_sd	<logical> If TRUE, normalize by the empirical standard deviation of each eta's individual estimates instead of the omega-implied one; see Details. Defaults to FALSE.
.problem	<numeric> Problem number to use. Uses the xpose default if not provided.
.subprob	<numeric> Subproblem number to use. Uses the xpose default if not provided.
.method	<character> Method to use. Uses the xpose default if not provided.
quiet	<logical> Silence extra debugging output

Details

This only ever affects how those four plotting functions display etas – it never modifies xpdb$data, so get_data() and every other consumer of the eta columns keep seeing the raw (unnormalized) values.

⁠$normalize_etas⁠ is a plain top-level slot rather than an xpdb$options entry – unlike most options, its value is one number per eta rather than a single setting, and folding a handful of high-precision numbers per eta into print.xpose_data()'s single-line ⁠Options:⁠ summary made that summary unreadable for models with more than a couple of etas.

The default (omega-based) scale relies on the same internal name/numbering match between eta columns and diagonal omega estimates (see recalc_shk()'s Details for when that can fail, eg unconventional eta naming that isn't a nlmixr2-style direct match to a parameter table name and also doesn't follow NONMEM's ⁠ETA<k>⁠/ETA(k) numbering). When that match fails, or there simply is no reliable omega for these etas (eg a hand-built or simulated xpdb), .use_sd = TRUE sidesteps it entirely, scaling by the empirical standard deviation of each eta's own individual estimates instead – at the cost of that scale itself being sample-dependent (and shrinkage- deflated) rather than reflecting the model's estimated random-effect variance.

Calling normalize_etas() again merges into (rather than replacing) any previously-set factors, via utils::modifyList() – so ... can be used to (re)compute just a subset of etas, eg after refitting. To turn normalization off again, assign directly: xpdb$normalize_etas$ETA1 <- NULL for a single eta, or xpdb$normalize_etas <- NULL for all of them.

Value

xp_xtras object, with the computed factors set under ⁠$normalize_etas⁠ (not ⁠$options⁠ – see Details)

See Also

recalc_shk(), which uses the same omega-matching logic

Examples

xpdb_norm <- normalize_etas(xpdb_x)
eta_grid(xpdb_norm)

# Just a subset of etas...
normalize_etas(xpdb_x, ETA1)

# By empirical SD instead, eg if the omega match fails or is unreliable
normalize_etas(xpdb_x, .use_sd = TRUE)

xpose.xtras documentation built on Sept. 1, 2026, 5:08 p.m.