Skip to contents

Update omega (random-effect) initial values and freeze status

update_Omegas.Rd

Tidy/pipe-friendly updater for the covariance matrix of random effects (omegas). Complements randomEffect(), which remains the built-in structural setter for creating or changing diagonal vs. block membership.

Usage

update_Omegas(model, ..., freeze = NULL, unfreeze = NULL)

Arguments

model

Model object (built-in or textual)

...

Named diagonal specs and/or dimnamed matrices; see Details

freeze

Character vector of eta names whose containing section(s) should be frozen. Applicable to built-in models only.

unfreeze

Character vector of eta names whose containing section(s) should be unfrozen. Applicable to built-in models only.

Value

Modified NlmePmlModel object

Details

On built-in models, edit values or supply a full dimnamed matrix for an existing section, and use freeze=/unfreeze= to toggle section freeze status without changing topology.

On textual models, value/matrix edits go through TDL5 override. Freeze and unfreeze are not supported and raise an error. Frozen or same()-linked sections may reject value edits. The textual override rebuilds from the complete omega matrix as a single ranef(block(...)) clause, so section topology (diag vs block, multiple ranef() sections) is not preserved; use this path for numeric edits, not layout-sensitive textual models.

Each named argument in ... is either:

  • a diagonal spec keyed by eta name – a scalar, or a named vector with initial (alias value); or

  • a base R matrix() with matching row/column dimnames giving eta names, supplying the full covariance values for an existing block/diagonal section (the ... name itself is decorative).

Unlike update_Thetas(), a spec here cannot carry freeze: PML has no per-eta freeze inside a diag()/block() section, so freezing is necessarily a property of the whole section and is requested through freeze=/unfreeze= instead. A freeze field inside a spec raises an error naming that alternative.

Occasion random effects are supported for both value and matrix edits, targeting the covariate's reference level; a matrix edit must name every random effect of that occasion covariate, because the stored values cover its whole inter-occasion covariance matrix. Editing a same()-linked eta directly raises an error naming the reference level on built-in models, or a post-hoc error on textual models (which cannot detect same() ahead of time).

See also

randomEffect()

Examples

model <- pkmodel(numCompartments = 2, columnMap = FALSE, workingDir = tempdir())
model <- update_Omegas(model, nV = 0.15, nCl = 0.1)

# A dimnamed matrix sets a whole section at once; the dimnames identify the
# section, so the argument name is decorative.
model <- randomEffect(model,
  effect = c("nV", "nCl"), isDiagonal = FALSE, value = c(0.1, 0.01, 0.1)
)
blockOmega <- matrix(
  c(0.2, 0.03, 0.03, 0.15), nrow = 2,
  dimnames = list(c("nV", "nCl"), c("nV", "nCl"))
)
model <- update_Omegas(model, omegaBlock = blockOmega)

# freeze= acts on the whole section containing the named eta
model <- update_Omegas(model, freeze = "nV")