vcm.lm {asreml} | R Documentation

## Specify constraints among variance parameters.

### Description

Construct a constraints matrix that specifies linear constraints among variance parameters.

### Usage

    vcm.lm(
      form,
      data,
      drop.unused.levels = TRUE,
      intercept = FALSE,
      na.action = na.fail
    )

### Arguments

`form` | A model formula including at least one factor with up to n_c levels, where n_c is the number of variance parameters to be considered in the constrained set.
`data` | A data frame with a factor `Vparameter`, whose levels are taken from the full set of variance parameters, in which to resolve the names in `form`.
`drop.unused.levels` | If `TRUE` (the default), unused levels in factors are removed.
`intercept` | if `FALSE` (the default), the intercept is not included in the call to `model.matrix` when forming the constraints matrix.
`na.action` | The default, `na.fail`, is to terminate abnormally if missing values are present.

### Details

Variance parameter constraints are specified through a design matrix M from a simple linear model. Let κ be the r-vector of original variance parameters (for either the sigma or gamma parameterisation) from which we wish to specify linear relationships of the form κ = M κ_n, where κ_n is the c-vector of parameters in the new set. In the simple case where the r parameters are constrained to be equal, c = 1, the r original parameters are all equal to the one new parameter and M will contain a column of ones.

The matrix M is given as the value to the `vcm` argument of `asreml`. M must have a `dimnames` attribute with the names of K as its row names.

A data frame containing a factor, `Vparameter`, whose levels are the r names of the variance parameters is returned by `asreml` when `start.values=TRUE`. The matrix M is obtained from a call to `model.matrix` using `form` and additional factors derived from or interacting with `Vparameter`.

### Value

A r \times c matrix M specifying the variance parameter constraints where c is the length of the reduced vector of variance parameters. In a simple case with r parameters and the r-1 and r parameters are constrained to be equal, then c = r-1 and the j^{th} (1, = j < c) column of M has 1 in the j^{th} row and zero elsewhere; the c^{th} column has 1 in the c = (r-1) and r rows and zero elsewhere.

### Examples

    # Suppose there are 4 variance parameters: g1, g2, g3, and g4,
    # and we wish to constrain 2 & 3 to be equal

    # generate gg as though from asreml(..., start.values=TRUE)

    gg <- data.frame(Vparameter = c('g1','g2','g3','g4'),
                            fac = factor(c(1,2,2,3)))
    M <- vcm.lm(~fac, data=gg)
    # M
    #    fac1 fac2 fac3
    # g1    1    0    0
    # g2    0    1    0
    # g3    0    1    0
    # g4    0    0    1

[Package asreml version 4.1.0.176 Index]