R: Contrast families

pairwise.lsmc {lsmeans} | R Documentation

## Contrast families

### Description

These functions return standard sets of contrast coefficients. The name of any of these functions (with the `.lsmc` omitted) may be used as the `method` argument in `contrast`, or as the `contr` argument or left-hand side of a `spec` formula in `lsmeans`.

### Usage

    pairwise.lsmc(levs, ...)
    revpairwise.lsmc(levs, ...)
    tukey.lsmc(levs, reverse = FALSE)

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

    trt.vs.ctrl.lsmc(levs, ref = 1)
    trt.vs.ctrl1.lsmc(levs, ...)
    trt.vs.ctrlk.lsmc(levs, ...)
    dunnett.lsmc(levs, ref = 1)

    consec.lsmc(levs, reverse = FALSE, ...)
    mean_chg.lsmc(levs, reverse = FALSE, ...)

    eff.lsmc(levs, ...)
    del.eff.lsmc(levs, ...)

### Arguments

`levs` | Vector of factor levels
`...` | Additional arguments, ignored but needed to make these functions interchangeable
`max.degree` | The maximum degree of the polynomial contrasts in `poly.lsmc`
`reverse` | Logical value to determine the direction of comparisons, e.g., pairwise (if `TRUE`) or reverse-pairwise (if `FALSE`) comparisons.
`ref` | Reference level (or control group) in `trt.vs.ctrl.lsmc`

### Details

Each 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.lsmc`, `revpairwise.lsmc`, and `tukey.lsmc` generate contrasts for all pairwise comparisons among least-squares means at the levels in `levs`. The distinction is in which direction they are subtracted. For factor levels A, B, C, D, `pairwise.lsmc` generates the comparisons A-B, A-C, A-D, B-C, B-D, and C-D, whereas `revpairwise.lsmc` generates B-A, C-A, C-B, D-A, D-B, and D-C. `tukey.lsmc` invokes `pairwise.lsmc` or `revpairwise.lsmc` depending on `reverse`. The default multiplicity adjustment method is `"tukey"`, which is approximate when the standard errors differ.

`poly.lsmc` 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.lsmc` 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.lsmc` is the same as `trt.vs.ctrl` with a reference value of `1`, and `trt.vs.ctrlk.lsmc` is the same as `trt.vs.ctrl` with a reference value of `length(levs)`. `dunnett.lsmc` is the same as `trt.vs.ctrl`. The default multiplicity adjustment method is `"dunnettx"`, a close approximation to the Dunnett adjustment.

`consec.lsmc` and `mean_chg.lsmc` are useful for contrasting treatments that occur in sequence. For a factor with levels A, B, C, D, E, `consec.lsmc` generates the comparisons B-A, C-B, and D-C, while `mean_chg.lsmc` 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.lsmc` and `del.eff.lsmc` generate contrasts that compare each level with the average over all levels (in `eff.lsmc`) or over all other levels (in `del.eff.lsmc`). These differ only in how they are scaled. For a set of k lsmeans, `del.eff.lsmc` gives weight 1 to one lsmean and weight -1/(k-1) to the others, while `eff.lsmc` gives weights (k-1)/k and -1/k respectively, as in subtracting the overall lsmean from each lsmean. 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 `lsmeans`, and the `"adjust"` attribute gives the default adjustment method for multiplicity.

### Note

You may create your own contrast functions, using these as guides. A function named `mycontr.lsmc` may be invoked in `lsmeans` via, e.g.,

    lsmeans(\var{object}, mycontr ~ \var{factor})

The `"desc"`, `"adjust"`, and `"offset"` attributes are optional; if present, these are passed to `contrast`. If absent, the root name of the function is used as `"desc"`, and no adjustment is requested for p values. See the examples.

### Author(s)

Russell V. Lenth

### See Also

`lsmeans`, `glht`

### Examples

    ### View orthogonal polynomials for 4 levels
    poly.lsmc(1:4)

    ### Setting up a custom contrast function
    helmert.lsmc <- function(levs, ...) {
      M <- as.data.frame(contr.helmert(levs))
      names(M) <- paste(levs[-1],"vs earlier")
      attr(M, "desc") <- "Helmert contrasts"
      M
    }
    warp.lm <- lm(breaks ~ wool*tension, data = warpbreaks)
    lsmeans(warp.lm, helmert ~ tension | wool)

[Package lsmeans version 2.25-5 Index]