R: Specify constraints among variance components

vcm.lm {asreml} | R Documentation

## Specify constraints among variance components

### Description

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

### 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`, unused levels in factors are removed (default = `TRUE`).
`intercept` | if `FALSE`, the intercept is not included in the call to `model.matrix` when forming the constraints matrix (default = `FALSE`).
`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 `F` from a simple linear model. Let `\kappa` 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 `\kappa = F \kappa_n`, where `\kappa_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 `F` will contain a column of ones.

The matrix `F` is given as the value to the `vcm` argument of `asreml`. `F` must have a `dimnames` attribute with the names of `\kappa` 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 `F` is obtained from a call to `model.matrix` using `form` and additional factors derived from or interacting with `Vparameter`.

### Value

An `r \times c` matrix `F` 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 `F` 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 four variance parameters: g1, g2, g3, and g4,
    # and we wish to constrain g2 & g3 to be equal (note these are in
    # positions 2 and 3).

    # 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)))
    F <- vcm.lm(~fac, data = gg)
    # F
    #    fac1 fac2 fac3
    # g1    1    0    0
    # g2    0    1    0
    # g3    0    1    0
    # g4    0    0    1

[Package asreml version 4.2.0.480 Index]