Residual variance formula term

Defines the Gaussian residual variance model as part of an stLMM formula. Omitting the term is equivalent to writing resid() or resid(model = "tau_sq"): one global residual variance tau_sq is estimated.

Usage

resid(model = c("tau_sq", "constant", "fixed", "group", "scaled"), group,
  variance, vhat, n = NULL, prior = c("default", "ig", "shannon"),
  method, shape = 4, center = c("mean", "mode"), shrinkage = 10,
  kappa_log_prior = c(mean = 0, sd = 1), tau0_sq_log_prior = NULL,
  starting = NULL, tuning = 0.1)

Arguments

model: Residual variance model. "tau_sq" and "constant" estimate one global Gaussian residual variance. "fixed" uses fixed row-specific variances. "group" estimates one residual variance per group. "scaled" estimates a low-dimensional scaling model for supplied row-specific variances.
group: Grouping variable for sampled group-specific residual variances.
variance: Numeric vector or expression evaluated in the model data giving one residual variance per row. This is used by model = "fixed", model = "group" with direct-estimate-informed priors, and model = "scaled". Variances for observed response rows must be finite and positive. Missing response rows may have missing variances because they do not enter the likelihood.
vhat: Alias for variance, useful when the supplied variances are direct-estimate variances. For grouped direct-estimate-informed residual variances, this is supplied per row and must be constant within group for observed rows.
n: Optional effective sample size. For prior = "shannon", this is group-level. For model = "scaled", this is row-level and controls shrinkage toward a common residual scale.
prior: Prior construction for model = "group" when variance is supplied. "ig" uses a constant-shape inverse-gamma prior centered on the supplied variance. "shannon" uses the effective-sample-size construction described below.
method: Alias for prior; retained only to make the argument name read naturally when comparing constant-shape and Shannon-style constructions.
shape: Inverse-gamma shape for prior = "ig".
center: Whether the constant-shape inverse-gamma prior mean or mode is centered on variance.
shrinkage: Positive constant controlling how quickly the sample-size aware scaled model trusts variance. The weight is n / (n + shrinkage).
kappa_log_prior: Mean and standard deviation of the normal prior on log(kappa).
tau0_sq_log_prior: Optional mean and standard deviation of the normal prior on log(tau0_sq) for the sample-size aware scaled model. If omitted, the prior is centered on the median observed variance.
starting: Optional starting values for residual variance parameters used by the grouped direct-estimate-informed and scaled models. For model = "group" without variance, supply starting values through starting = list(resid = list(tau_sq = value)) in stLMM.
tuning: Initial log-scale Metropolis proposal scale for sampled residual variance parameters.

Details

resid() is an stLMM formula term, not the usual fitted-model resid() or residuals() extractor. Only one resid() term is allowed, and it cannot be used in interactions. The formula term selects the residual variance model; corresponding priors, starting values, and tuning values are supplied through the resid block in priors, starting, and tuning. Gaussian residual variance models are not used with Polya-Gamma likelihoods such as family = "binomial" or family = "negative_binomial".

resid(model = "tau_sq") estimates one scalar residual variance. Use priors = list(resid = list(tau_sq = ig(shape, scale))) or priors = list(resid = list(tau_sq = half_t(df, scale))) to place a prior on this variance model.

resid(model = "fixed", variance = vhat) uses observed-row precision obs_precision_i = 1 / vhat_i. When this model is used, tau_sq is not sampled. Prediction of new response draws with y_samples = TRUE requires residual variance information for the prediction rows.

resid(model = "group", group = g) estimates one residual variance per group. Priors are supplied through priors$resid; use priors = list(resid = list(tau_sq = ig(shape, scale))) to apply one prior to all groups, or supply a named list with one prior per group. Starting values and tuning values are supplied through starting$resid$tau_sq and tuning$resid$tau_sq; scalars are recycled over groups and named vectors or lists may be used when group-specific values are needed. Values marked with fixed are held fixed, assigned zero tuning, and do not require residual group priors.

resid(model = "group", group = g, variance = vhat, prior = "ig") also estimates one residual variance per group, but constructs inverse-gamma priors from externally supplied group-level variance information. For prior = "ig", shape is the inverse-gamma shape and the scale is chosen so either the prior mean or prior mode equals vhat. With prior = "shannon", the prior is IG(n / 2, (n - 1) * vhat / 2) and requires n > 1; larger n gives a more concentrated prior around the supplied direct-estimate variance. Starting values for this direct-estimate-informed grouped model are supplied with the starting argument inside resid(...).

resid(model = "scaled", variance = vhat) estimates a low-dimensional multiplier for direct-estimate variances. Without n, the model is tau_i^2 = kappa * vhat_i. With n, the model uses log(tau_i^2) = log(kappa) + w_i log(vhat_i) + (1 - w_i) log(tau0_sq) where w_i = n_i / (n_i + shrinkage). The positive parameters kappa and tau0_sq are sampled on the log scale, so zero or negative residual variances are not possible. Starting values for these parameters are supplied with the starting argument inside resid(...).

Value

An object of class stLMM_residual that encodes the residual variance model selected by the formula term. The object is intended for use inside stLMM formulas and stores the residual model type plus the user-supplied grouping, variance, starting-value, and tuning information needed when the model frame is built.

Examples

area <- rep(letters[1:3], each = 2)
vhat <- rep(c(0.2, 0.4, 0.6), each = 2)
n_eff <- rep(c(10, 20, 30), each = 2)

resid()
#> $type
#> [1] "global_tau"
#> 
#> $label
#> [1] "resid()"
#> 
#> attr(,"class")
#> [1] "stLMM_residual"
resid(model = "fixed", variance = vhat)
#> $type
#> [1] "fixed_variance"
#> 
#> $variance_expr
#> vhat
#> 
#> $variance_label
#> [1] "vhat"
#> 
#> $env
#> <environment: 0x564303555110>
#> 
#> attr(,"class")
#> [1] "stLMM_residual"
resid(model = "group", group = area)
#> $type
#> [1] "group_variance"
#> 
#> $group_expr
#> area
#> 
#> $label
#> [1] "resid(model = 'group', group = area)"
#> 
#> $env
#> <environment: 0x564303555110>
#> 
#> attr(,"class")
#> [1] "stLMM_residual"
resid(model = "group", group = area, variance = vhat, prior = "ig", shape = 6)
#> $type
#> [1] "group_ig_variance"
#> 
#> $group_expr
#> area
#> 
#> $vhat_expr
#> vhat
#> 
#> $n_expr
#> NULL
#> 
#> $method
#> [1] "constant"
#> 
#> $shape
#> [1] 6
#> 
#> $center
#> [1] "mean"
#> 
#> $starting
#> NULL
#> 
#> $tuning
#> [1] 0.1
#> 
#> $label
#> [1] "resid(model = 'group', group = area, variance = vhat)"
#> 
#> $env
#> <environment: 0x564303555110>
#> 
#> attr(,"class")
#> [1] "stLMM_residual"
resid(model = "scaled", variance = vhat, n = n_eff)
#> $type
#> [1] "scaled_variance"
#> 
#> $vhat_expr
#> vhat
#> 
#> $n_expr
#> n_eff
#> 
#> $has_n
#> [1] TRUE
#> 
#> $shrinkage
#> [1] 10
#> 
#> $kappa_log_prior
#> [1] 0 1
#> 
#> $tau0_sq_log_prior
#> NULL
#> 
#> $starting
#> NULL
#> 
#> $tuning
#> [1] 0.1
#> 
#> $label
#> [1] "resid(model = 'scaled', variance = vhat, n = n_eff)"
#> 
#> $env
#> <environment: 0x564303555110>
#> 
#> attr(,"class")
#> [1] "stLMM_residual"