mvcontrast {emmeans}

Multivariate contrasts

Description

This function displays tests of multivariate comparisons or contrasts. The contrasts are constructed at each level of the variable in mult.name, and then we do a multivariate test that the vector of estimates is equal to null (zero by default). The F statistic and degrees of freedom are determined via the Hotelling distribution. that is, if there are m error degrees of freedom and multivariate dimensionality d, then the resulting F statistic has degrees of freedom (d, m - d + 1) as shown in Hotelling (1931).

Usage

mvcontrast(object, method = "eff", mult.name = object@roles$multresp,
  null = 0, by = object@misc$by.vars, adjust = c("sidak",
  p.adjust.methods), show.ests = FALSE, ...)

Arguments

object

An object of class emmGrid

method

A contrast method, per contrast.emmGrid

mult.name

Character vector of nNames of the factors whose levels define the multivariate means to contrast. If the model itself has a multivariate response, that is what is used. Otherwise, mult.name must be specified.

null

Scalar or conformable vector of null-hypothesis values to test against

by

Any by variable(s). These should not include the primary variables to be contrasted. For convenience, the by variable is nulled-out if it would result in no primary factors being contrasted.

adjust

Character value of a multiplicity adjustment method ("none" for no adjustment). The available adjustment methods are more limited that in contrast, and any default adjustment returned via method is ignored.

show.ests

Logical flag determining whether the multivariate means are displayed

...

Additional arguments passed to contrast

Value

An object of class summary_emm containing the multivariate test results; or a list of the estimates and the tests if show.ests is TRUE. The test results include the Hotelling T^2 statistic, F ratios, degrees of freedom, and P values.

Note

If some interactions among the primary and mult.name factors are absent, the covariance of the multivariate means is singular; this situation is accommodated, but the result has reduced degrees of freedom and a message is displayed. If there are other abnormal conditions such as non-estimable results, estimates are shown as NA.

While designed primarily for testing contrasts, multivariate tests of the mean vector itself can be implemented via method = "identity") (see the examples).

References

Hotelling, Harold (1931) "The generalization of Student's ratio", Annals of Mathematical Statistics 2(3), 360–378. doi:10.1214/aoms/1177732979

Examples

MOats.lm <- lm(yield ~ Variety + Block, data = MOats)
MOats.emm <- emmeans(MOats.lm, ~ Variety | rep.meas)
mvcontrast(MOats.emm, "consec", show.ests = TRUE)  # mult.name defaults to rep.meas

# Test each mean against a specified null vector
mvcontrast(MOats.emm, "identity", name = "Variety", 
           null = c(80, 100, 120, 140), adjust = "none")
# (Note 'name' is passed to contrast() and overrides default name "contrast")

# 'mult.name' need not refer to a multivariate response
mvcontrast(MOats.emm, "trt.vs.ctrl1", mult.name = "Variety")