contrasts {stats} | R Documentation

## Get and Set Contrast Matrices

### Description

Set and view the contrasts associated with a factor.

### Usage

    contrasts(x, contrasts = TRUE, sparse = FALSE)
    contrasts(x, how.many) <- value

### Arguments

`x` | a factor or a logical variable.
`contrasts` | logical. See ‘Details’.
`sparse` | logical indicating if the result should be sparse (of class `dgCMatrix`), using package Matrix.
`how.many` | How many contrasts should be made. Defaults to one less than the number of levels of `x`. This need not be the same as the number of columns of `value`.
`value` | either a numeric matrix (or a sparse or dense matrix of a class extending `dMatrix` from package Matrix) whose columns give coefficients for contrasts in the levels of `x`, or the (quoted) name of a function which computes such matrices.

### Details

If contrasts are not set for a factor the default functions from `options("contrasts")` are used.

A logical vector `x` is converted into a two-level factor with levels `c(FALSE, TRUE)` (regardless of which levels occur in the variable).

The argument `contrasts` is ignored if `x` has a matrix `contrasts` attribute set. Otherwise if `contrasts = TRUE` it is passed to a contrasts function such as `contr.treatment` and if `contrasts = FALSE` an identity matrix is returned. Suitable functions have a first argument which is the character vector of levels, a named argument `contrasts` (always called with `contrasts = TRUE`) and optionally a logical argument `sparse`.

If `value` supplies more than `how.many` contrasts, the first `how.many` are used. If too few are supplied, a suitable contrast matrix is created by extending `value` after ensuring its columns are contrasts (orthogonal to the constant term) and not collinear.

### References

Chambers, J. M. and Hastie, T. J. (1992) Statistical models. Chapter 2 of Statistical Models in S eds J. M. Chambers and T. J. Hastie, Wadsworth & Brooks/Cole.

### See Also

`C`, `contr.helmert`, `contr.poly`, `contr.sum`, `contr.treatment`; `glm`, `aov`, `lm`.

### Examples

    utils::example(factor)
    fff <- ff[, drop = TRUE]  # reduce to 5 levels.
    contrasts(fff) # treatment contrasts by default
    contrasts(C(fff, sum))
    contrasts(fff, contrasts = FALSE) # the 5x5 identity matrix

    contrasts(fff) <- contr.sum(5); contrasts(fff)  # set sum contrasts
    contrasts(fff, 2) <- contr.sum(5); contrasts(fff)  # set 2 contrasts
    # supply 2 contrasts, compute 2 more to make full set of 4.
    contrasts(fff) <- contr.sum(5)[, 1:2]; contrasts(fff)

    ## using sparse contrasts: % useful, once model.matrix() works with these :
    ffs <- fff
    contrasts(ffs) <- contr.sum(5, sparse = TRUE)[, 1:2]; contrasts(ffs)
    stopifnot(all.equal(ffs, fff))
    contrasts(ffs) <- contr.sum(5, sparse = TRUE); contrasts(ffs)

[Package stats version 3.3.0 Index]