vcc: Equality and scaling constraints between variance parameters

In sommer: Solving Mixed Model Equations in R

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: each member equals scale times the first member of its group (natural scale). 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.

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 Oct. 24, 2026, 1:08 a.m.