normalize_etas: 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
)

Value

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

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.

Examples

Run this code

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)