emmeans (version 1.3.2)

contrast: 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 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 emmGrid
pairs(x, reverse = FALSE, ...)
# S3 method for 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.

Examples

# NOT RUN {
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.
# }
# 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
# }