vcc: Equality and scaling constraints between variance parameters

vccR Documentation

Equality and scaling constraints between variance parameters

Description

The vcc argument of mmes constrains groups of covariance parameters to be equal or to keep fixed ratios. Parameters are identified through the vcParams table.

Details

Parameters are estimated on transformed scales that guarantee valid covariance matrices (log for variances, atanh or bounded logits for correlations). A constraint is enforced exactly when it is affine on that scale, which covers equalities of any parameter and ratios of positive parameters (a log-scale offset). Relations such as \sigma^2_3=\sigma^2_1+\sigma^2_2 are not affine on the log scale and are not supported.

Internally the free working parameters are written as w=o+T\phi. Each average-information update is projected onto this set in the information metric, which equals the constrained Newton step, and then repaired exactly; both the Henderson and the direct engines support constraints. The covariance of the estimates is T(T^\top\mathcal{I}T)^{-1}T^\top, so constrained parameters share their standard errors.

The vcParams table

mmes(..., control = mmes_control(output = list(setup = TRUE)))$vcParams (before fitting) and fit$vcParams (after fitting) list every covariance parameter with columns index, term, parameter, kind, start (natural scale), free, structure and position (and group when constraints were used). kind is "scale" for the variance scale (sigma2) owned by each vsm() term, or the transform used to estimate the parameter: "exp" (positive quantities such as ranges and variance ratios), "identity" (e.g. Cholesky or factor-analytic loadings), "tanh" or "bounded_logit" (correlation-type parameters).

Specifying constraints

vcc is a data frame with columns

parameter

the index of the parameter, or its name "term:parameter" (e.g. "vsm(ism(B)):sigma2"); the parameter name alone is accepted when unique.

group

parameters with the same group value are constrained together.

scale

optional, default 1: members divided by their respective scale values are equal on the natural scale. Relative to the first member, the ratio is scale / scale[1]. Scaling is allowed for "scale", "exp" and "identity" parameters; correlation-type parameters can only be equated.

All members of a group must have the same kind: variance scales can be constrained with other variance scales, and other parameters with parameters estimated through the same transform. If any member of a group is fixed, the whole group is fixed at the value implied by that member. Starting values of the members are made consistent with the first (or fixed) member. Multiple fixed members must imply the same value. Correlations with bounded logit transforms must have identical bounds to be equated.

Native Laplace GLMMs

Native Laplace ML supports these constraints for random covariance parameters, including ordinal, nominal and mixed familym() responses. Use the same family and method$integration="laplace" when requesting output$setup=TRUE: the returned vcParams table contains random covariance parameters, plus actual Gaussian observation-residual parameters when structured Gaussian blocks are requested. The latter are reported for inspection and uncertainty but are not accepted as vcc members. The synthetic Gaussian preparation residual scale is always excluded. Parameter indices from a Gaussian setup are not interchangeable with this table. Family dispersion, NB2 shape, thresholds and zero-inflation coefficients are not part of vcc.

The likelihood is optimized in the independent coordinates \phi; native scores are pulled back with T^\top. Parameter counts for logLik(), AIC and BIC count only independent estimated coordinates. Numerical observed information, covariance standard errors, prediction uncertainty and PEV remain post-fit calculations. Their Jacobians propagate uncertainty through the same constraint map and the natural-scale transformations; no Hessian is computed during fitting.

Likelihood comparisons through anova() still require nested fixed effects with the same covariance constraints. Comparing different variance constraint spaces is not supported by this fixed-effects comparison.

See Also

mmes, vsm, covparams_mmes

Examples

data(DT_yatesoats, package = "enhancer")
DT <- DT_yatesoats
p <- mmes(Y ~ V * N,
  random = ~ B + B:MP,
  rcov = ~ units,
  data = DT,
  control = mmes_control(output = list(setup = TRUE)))
p$vcParams
# block and whole-plot variances equal
m1 <- mmes(Y ~ V * N,
  random = ~ B + B:MP,
  rcov = ~ units,
  data = DT,
  vcc = data.frame(parameter = c(1, 2), group = 1),
  control = mmes_control(diagnostics = list(verbose = FALSE)))
# block variance twice the whole-plot variance
m2 <- mmes(Y ~ V * N,
  random = ~ B + B:MP,
  rcov = ~ units,
  data = DT,
  vcc = data.frame(parameter = c("vsm(ism(B:MP)):sigma2", "vsm(ism(B)):sigma2"),
                            group = 1, scale = c(1, 2)),
  control = mmes_control(diagnostics = list(verbose = FALSE)))
unlist(m2$covPar)

sommer documentation built on Nov. 14, 2026, 5:07 p.m.