###### Description

vcm.lm constructs 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

*κ*is the

_{n}*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 *κ* 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

An *r* x *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