R: Contrasts and linear functions of EMMs

contrast {emmeans} | R Documentation

## Contrasts and linear functions of EMMs

### Description

These methods provide for follow-up analyses of `emmGrid` objects: Contrasts, pairwise comparisons, tests, and confidence intervals. They may also be used to compute arbitrary linear functions of predictions or EMMs.

### Usage

    contrast(object, ...)

    ## S3 method for class 'emmGrid'
    contrast(object, method = "eff", interaction = FALSE, by,
      offset = NULL, name = "contrast", options = get_emm_option("contrast"),
      type, adjust, simple, combine = FALSE, ...)

    ## S3 method for class 'emmGrid'
    pairs(x, reverse = FALSE, ...)

    ## S3 method for class 'emmGrid'
    coef(object, ...)

### Arguments

`object` | An object of class `emmGrid`
`...` | Additional arguments passed to other methods
`method` | Character value giving the root name of a contrast method (e.g. `"pairwise"` – see emmc-functions). Alternatively, a named `list` of coefficients (for a contrast or linear function) that must each conform to the number of results in each `by` group. In a multi-factor situation, the factor levels are combined and treated like a single factor.
`interaction` | Character vector or logical value. If this is specified, `method` is ignored. See the “Interaction contrasts” section below for details.
`by` | Character names of variable(s) to be used for “by” groups. The contrasts or joint tests will be evaluated separately for each combination of these variables. If `object` was created with by groups, those are used unless overridden. Use `by = NULL` to use no by groups at all.
`offset` | Numeric vector of the same length as each `by` group. These values are added to their respective linear estimates. (It is ignored when `interaction` is specified.)
`name` | Character name to use to override the default label for contrasts used in table headings or subsequent contrasts of the returned object.
`options` | If non-`NULL`, a named `list` of arguments to pass to `update.emmGrid`, just after the object is constructed.
`type` | Character: prediction type (e.g., `"response"`) – added to `options`
`adjust` | Character: adjustment method (e.g., `"bonferroni"`) – added to `options`
`simple` | Character vector or list: Specify the factor(s) not in `by`, or a list thereof. See the section below on simple contrasts.
`combine` | Logical value that determines what is returned when `simple` is a list. See the section on simple contrasts.
`x` | An `emmGrid` object
`reverse` | Logical value - determines whether to use `"pairwise"` (if `TRUE`) or `"revpairwise"` (if `FALSE`).

### Value

`contrast` and `pairs` return an object of class `emmGrid`. Its grid will correspond to the levels of the contrasts and any `by` variables. The exception is that an `emm_list` object is returned if `simple` is a list and `complete` is `FALSE`.

`coef` returns a `data.frame` containing the object's grid, along with columns named `c.1, c.2, ...` containing the contrast coefficients. If

### Pairs method

The call `pairs(object)` is equivalent to `contrast(object, method = "pairwise")`; and `pairs(object, reverse = TRUE)` is the same as `contrast(object, method = "revpairwise")`.

### Interaction contrasts

When `interaction` is specified, interaction contrasts are computed: Contrasts are generated for each factor separately, one at a time; and these contrasts are applied to the object (the first time around) or to the previous result (subsequently). (Any factors specified in `by` are skipped.) The final result comprises contrasts of contrasts, or, equivalently, products of contrasts for the factors involved. Processing is done in the order of appearance in `object@levels`. With `interaction = TRUE`, `method` (if specified as character) is used for each contrast. If `interaction` is a character vector, the elements specify the respective contrast method(s); they are recycled as needed.

### Simple contrasts

`simple` is essentially the complement of `by`: When `simple` is a character vector, `by` is set to all the factors in the grid except those in `simple`. If `simple` is a list, each element is used in turn as `simple`, and assembled in an `"emm_list"`. To generate all simple main effects, use `simple = "each"` (this works unless there actually is a factor named `"each"`). Note that a non-missing `simple` will cause `by` to be ignored.

Ordinarily, when `simple` is a list or `"each"`, the return value is an `emm_list` object with each entry in correspondence with the entries of `simple`. However, with `combine = TRUE`, the elements are all combined into one family of contrasts in a single `emmGrid` object using `rbind.emmGrid`.. In that case, the `adjust` argument sets the adjustment method for the combined set of contrasts.

### Note

When `object` has a nesting structure (this can be seen via `str(object)`), then any grouping factors involved are forced into service as `by` variables, and the contrasts are thus computed separately in each nest. This in turn may lead to an irregular grid in the returned `emmGrid` object, which may not be valid for subsequent `emmeans` calls.

### Examples

    warp.lm <- lm(breaks ~ wool*tension, data = warpbreaks)
    warp.emm <- emmeans(warp.lm, ~ tension | wool)
    contrast(warp.emm, "poly")    # inherits 'by = "wool"' from warp.emm
    pairs(warp.emm)               # ditto
    contrast(warp.emm, "eff", by = NULL)  # contrasts of the 6 factor combs
    pairs(warp.emm, simple = "wool") # same as pairs(warp.emm, by = "tension")

    # Do all "simple" comparisons, combined into one family
    pairs(warp.emm, simple = "each", combine = TRUE)

    ## Not run:

    ## Note that the following are NOT the same:
    contrast(warp.emm, simple = c("wool", "tension"))
    contrast(warp.emm, simple = list("wool", "tension"))
    ## The first generates contrasts for combinations of wool and tension
    ##   (same as by = NULL)
    ## The second generates contrasts for wool by tension, and for
    ##   tension by wool, respectively.

    ## End(Not run)

    # An interaction contrast for tension:wool
    tw.emm <- contrast(warp.emm, interaction = c("poly", "consec"), by = NULL)
    tw.emm          # see the estimates
    coef(tw.emm)    # see the contrast coefficients

[Package emmeans version 1.1.3 Index]