# contrast: Contrasts and linear functions of EMMs In emmeans: Estimated Marginal Means, aka Least-Squares Means

## 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

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13``` ```contrast(object, ...) ## S3 method for class 'emmGrid' contrast(object, method = "eff", interaction = FALSE, by, offset = NULL, scale = NULL, name = "contrast", options = get_emm_option("contrast"), type, adjust, simple, combine = FALSE, ratios = TRUE, parens, ...) ## 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 function of the same form, or 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, logical value, or list. 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, scale` Numeric vectors of the same length as each `by` group. The `scale` values, if supplied, multiply their respective linear estimates, and any `offset` values are added. Scalar values are also allowed. (These arguments are 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. `ratios` Logical value determining how log and logit transforms are handled. These transformations are exceptional cases in that there is a valid way to back-transform contrasts: differences of logs are logs of ratios, and differences of logits are odds ratios. If `ratios = TRUE` and summarized with `type = "response"`, `contrast` results are back-transformed to ratios whenever we have true contrasts (coefficients sum to zero). For other transformations, there is no natural way to back-transform contrasts, so even when summarized with `type = "response"`, contrasts are computed and displayed on the linear-predictor scale. Similarly, if `ratios = FALSE`, log and logit transforms are treated in the same way as any other transformation. `parens` character or `NULL`. If a character value, the labels for levels being contrasted are parenthesized if they match the regular expression in `parens` (via `grep`). The default is `emm_option("parens")`. Optionally, `parens` may contain second and third elements specifying what to use for left and right parentheses (default `"("` and `")"`). Specify `parens = NULL` or `parens = "a^"` (which won't match anything) to disable all parenthesization. `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. Specifically 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. Any named elements of `interaction` are assigned to contrast methods; others are assigned in order of appearance in `object@levels`. The contrast factors in the resulting `emmGrid` object are ordered the same as in `interaction`.

`interaction` may be a character vector or list of valid contrast methods (as documented for the `method` argument). If the vector or list is shorter than the number needed, it is recycled. Alternatively, if the user specifies `contrast = TRUE`, the contrast specified in `method` is used for all factors involved.

## 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

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34``` ```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(tension = "poly", wool = "consec"), by = NULL) tw.emm # see the estimates coef(tw.emm) # see the contrast coefficients # Use of scale and offset # an unusual use of the famous stack-loss data... mod <- lm(Water.Temp ~ poly(stack.loss, degree = 2), data = stackloss) (emm <- emmeans(mod, "stack.loss", at = list(stack.loss = 10 * (1:4)))) # Convert results from Celsius to Fahrenheit: confint(contrast(emm, "identity", scale = 9/5, offset = 32)) ```

emmeans documentation built on Oct. 25, 2020, 9:06 a.m.