Expand declared non-normal random effect distributions into a model

Rewrites a ui that carries dist() declarations into an ordinary ui: the declared random effects become latent standard normals (a fixed identity omega) plus unconstrained correlation thetas, and the model block gains the phiU() + inverse CDF lines that recreate them under their original names. Everything downstream – rxSolve(), and every nlmixr2est estimation method – then sees a model it already knows how to handle.

Usage

rxEtaDistExpand(ui, param = c("cdf", "direct"))

Arguments

ui

rxode2 ui

param

How a declared random effect is represented for estimation.

"cdf" (default) is the construction described above: a standard normal latent, phiU(), the family's inverse CDF, and rxCor.* carrying a Gaussian copula. The estimator then sees an ordinary model with a fixed identity omega, and the non-normality lives in a decoder line.

"direct" leaves the declared random effect ALONE: no latent, no decoder, no phiU(). The eta itself is what the estimator samples or optimizes, and it carries the declared family as its prior rather than a variance. Its omega entry is a FIXED placeholder that an estimator on this route must ignore – an estimator that reads it as a Gaussian variance will silently fit the wrong model, so the route is opt-in per estimator.

The two are not interchangeable everywhere. For a CORRELATED block of declared random effects the CDF construction is not an alternative, it is the definition: a Gaussian copula with non-normal marginals IS eta = Q(phi(z)). Expressing that directly needs an explicit joint distribution (NoLimits.jl reaches for Copulas.SklarDist), which this does not have, so "direct" refuses a correlated declared block by name rather than dropping the correlation silently.

Value

the rewritten rxode2 ui, or ui itself when there is nothing to expand

Details

A ui with no declaration is returned unchanged.

Author

Matthew L. Fidler

Examples

# \donttest{
if (requireNamespace("lotri", quietly = TRUE) &&
      "lotriEtaDists" %in% getNamespaceExports("lotri")) {
one.cmt <- function() {
  ini({
    lclm <- log(5)
    lclrv <- log(0.09)
    tv <- 3.45
    eta.v ~ 0.1
    dist(eta.cl) ~ dgamma(shape=1/exp(lclrv),
                          rate=1/(exp(lclrv)*exp(lclm)))
    add.sd <- 0.7
  })
  model({
    cl <- eta.cl
    v <- exp(tv + eta.v)
    linCmt() ~ add(add.sd)
  })
}

rxEtaDistExpand(one.cmt())
}
# }