R: Contrast families

contrast-methods {emmeans} | R Documentation

## Contrast families

### Description

Functions with an extension of `.emmc` provide for named contrast families. One of the standard ones documented here may be used, or the user may write such a function.

### Usage

    pairwise.emmc(levs, ...)

    revpairwise.emmc(levs, ...)

    tukey.emmc(levs, reverse = FALSE)

    poly.emmc(levs, max.degree = min(6, k - 1))

    trt.vs.ctrl.emmc(levs, ref = 1, reverse = FALSE)

    trt.vs.ctrl1.emmc(levs, ref = 1, ...)

    trt.vs.ctrlk.emmc(levs, ref = length(levs), ...)

    dunnett.emmc(levs, ref = 1, ...)

    eff.emmc(levs, ...)

    del.eff.emmc(levs, ...)

    consec.emmc(levs, reverse = FALSE, ...)

    mean_chg.emmc(levs, reverse = FALSE, ...)

### Arguments

`levs` | Vector of factor levels
`...` | Additional arguments, passed to related methods as appropriate
`reverse` | Logical value to determine the direction of comparisons
`max.degree` | Integer specifying the maximum degree of polynomial contrasts
`ref` | Integer(s) specifying which level(s) to use as the reference

### Details

Each standard contrast family has a default multiple-testing adjustment as noted below. These adjustments are often only approximate; for a more exacting adjustment, use the interfaces provided to `glht` in the multcomp package.

`pairwise.emmc`, `revpairwise.emmc`, and `tukey.emmc` generate contrasts for all pairwise comparisons among estimated marginal means at the levels in levs. The distinction is in which direction they are subtracted. For factor levels A, B, C, D, `pairwise.emmc` generates the comparisons A-B, A-C, A-D, B-C, B-D, and C-D, whereas `revpairwise.emmc` generates B-A, C-A, C-B, D-A, D-B, and D-C. `tukey.emmc` invokes `pairwise.emmc` or `revpairwise.emmc` depending on `reverse`. The default multiplicity adjustment method is `"tukey"`, which is only approximate when the standard errors differ.

`poly.emmc` generates orthogonal polynomial contrasts, assuming equally-spaced factor levels. These are derived from the `poly` function, but an ad hoc algorithm is used to scale them to integer coefficients that are (usually) the same as in published tables of orthogonal polynomial contrasts. The default multiplicity adjustment method is `"none"`.

`trt.vs.ctrl.emmc` and its relatives generate contrasts for comparing one level (or the average over specified levels) with each of the other levels. The argument `ref` should be the index(es) (not the labels) of the reference level(s). `trt.vs.ctrl1.emmc` is the same as `trt.vs.ctrl.emmc` with a reference value of 1, and `trt.vs.ctrlk.emmc` is the same as `trt.vs.ctrl` with a reference value of `length(levs)`. `dunnett.emmc` is the same as `trt.vs.ctrl`. The default multiplicity adjustment method is `"dunnettx"`, a close approximation to the Dunnett adjustment.

`consec.emmc` and `mean_chg.emmc` are useful for contrasting treatments that occur in sequence. For a factor with levels A, B, C, D, E, `consec.emmc` generates the comparisons B-A, C-B, and D-C, while `mean_chg.emmc` generates the contrasts (B+C+D)/3 - A, (C+D)/2 - (A+B)/2, and D - (A+B+C)/3. With `reverse = TRUE`, these differences go in the opposite direction.

`eff.emmc` and `del.eff.emmc` generate contrasts that compare each level with the average over all levels (in `eff.emmc`) or over all other levels (in `del.eff.emmc`). These differ only in how they are scaled. For a set of k EMMs, `del.eff.emmc` gives weight 1 to one EMM and weight -1/(k-1) to the others, while `eff.emmc` gives weights (k-1)/k and -1/k respectively, as in subtracting the overall EMM from each EMM. The default multiplicity adjustment method is `"fdr"`. This is a Bonferroni-based method and is slightly conservative; see `p.adjust`.

### Value

A data.frame, each column containing contrast coefficients for levs. The "desc" attribute is used to label the results in emmeans, and the "adjust" attribute gives the default adjustment method for multiplicity.

### Examples

    warp.lm <- lm(breaks ~ wool*tension, data = warpbreaks)
    warp.emm <- emmeans(warp.lm, ~ tension | wool)
    contrast(warp.emm, "poly")

    ### Setting up a custom contrast function
    helmert.emmc <- function(levs, ...) {
        M <- as.data.frame(contr.helmert(levs))
        names(M) <- paste(levs[-1],"vs earlier")
        attr(M, "desc") <- "Helmert contrasts"
        M
    }
    contrast(warp.emm, "helmert")
    ## Not run:
    # See what is used for polynomial contrasts with 6 levels
    emmeans:::poly.emmc(1:6)

    ## End(Not run)

[Package emmeans version 1.1.3 Index]