Skip to contents

Update fixed-effect (theta) initial values, bounds, freeze, and enable

update_Thetas.Rd

Tidy/pipe-friendly updater for one or more fixed effects (thetas) on built-in and textual (edited) models. Complements fixedEffect(), which remains the built-in structural setter when units are needed or when configuring thetas during model construction. This function does not set units.

Usage

update_Thetas(model, ...)

Arguments

model

Model object (built-in or textual)

...

Named theta specs; see Details

Value

Modified NlmePmlModel object

Details

Each named argument in ... specifies the theta to update and its new spec, which may be:

  • a scalar numeric, which sets the initial value only;

  • an unnamed length-3 numeric vector c(lower, initial, upper), which sets the lower bound, initial value, and upper bound;

  • a named vector with any of lower, initial (alias value), upper, freeze (alias frozen), enable. Assign a logical value to freeze: freeze = TRUE freezes the associated fixed effect so that it is not estimated, whereas freeze = FALSE unfreezes it so that it can be estimated. Assign a non-negative whole number to enable; this enables the associated covariate effect, using the assigned value as the enable ID, so that it can be tested during covariate search procedures.

Omitted fields are preserved from the current model. A name that is not a fixed effect of model raises an error, so a typo is caught rather than reported as an applied edit.

enable applies to textual models only; built-in models have no enable slot, so a warning is issued and the field is ignored. Assigning a non-negative whole number enables the associated covariate effect and uses that number as the enable ID. enable = FALSE (or NA, or NULL) removes the enable flag, disabling the covariate effect. A negative number, a fraction such as 1.8, or a bare enable = TRUE, which carries no ID, raises an error instead of being truncated or ignored.

Supply enable = FALSE, NULL, or TRUE through a list rather than c(). Because c() coerces logicals to numbers and drops NULL, a vector would silently turn the request into something else: TRUE becomes the valid enable ID 1, FALSE becomes the valid enable ID 0 (leaving the effect enabled), and NULL disappears entirely (leaving the flag in place). All three are therefore rejected inside c(), with a message naming the list form to use, for example list(initial = 10, enable = FALSE). An enable ID and enable = NA are unaffected by coercion and may be given either way.

A bound the spec omits is preserved, and a bound the model does not have stays absent rather than being reported as -Inf/Inf. Passing -Inf as lower, or Inf as upper, explicitly removes that bound on built-in and textual models alike.

See also

fixedEffect()

Examples

model <- pkmodel(columnMap = FALSE, workingDir = tempdir())
model <- update_Thetas(model,
  tvV = 15,
  tvCl = c(lower = 0, initial = 5, upper = 20)
)
initFixedEffects(model)
#>  tvV tvCl 
#> "15"  "5" 

# -Inf / Inf remove a bound that is currently set
model <- update_Thetas(model, tvCl = c(lower = -Inf))