R: Methods for obtaining analyses 'ref.grid' and 'lsmobj'...

contrast {lsmeans} | R Documentation

## Methods for obtaining analyses `ref.grid` and `lsmobj` objects

### Description

These methods provide for analyses of `ref.grid` objects, or follow-up analyses of `lsmobj` objects: Contrasts, pairwise comparisons, tests, and confidence intervals.

### Usage

    ## S3 method for class 'ref.grid'
    contrast(object, method = "eff", interaction = FALSE,
        by, offset = NULL, name = "contrast",
        options = getOption("lsmeans")$contrast, adjust, ...)
    ## S3 method for class 'lsm.list'
    contrast(object, ..., which = 1)

    ## S3 method for class 'ref.grid'
    test(object, null = 0, joint = FALSE,
        verbose = FALSE, rows, by,  ...)

    ## S3 method for class 'ref.grid'
    confint(object, parm, level = 0.95, ...)

    ## S3 method for class 'ref.grid'
    pairs(x, reverse = FALSE, ...)

    ## S3 method for class 'ref.grid'
    coef(object, ...)

### Arguments

`object, x` | An object of class `"ref.grid"` or its extension, `"lsmobj"`.
`method` | Character value giving the root name of a contast method (e.g. `"pairwise"`). Alternatively, a named list of contrast coefficients that must each conform to the number of least-squares means in each `by` group. This is just like the `contr` argument in `lsmeans`. To identify the available methods, see
    ls("package:lsmeans", pat=".lsmc")
You may define your own `.lsmc` function and use its root name as `method`. If `interaction` is of character type, this argument is ignored.
`interaction` | Character vector or logical value. In multi-factor situations with `interaction = FALSE`, the factor combinations are treated as levels of a single “uber-factor”, and the contrast specified in `method` is applied to it. Otherwise, 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.
`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. This argument is ignored when`interaction` is not `FALSE`.
`name` | Name to use to label the contrasts in table headings or subsequent contrasts of the returned object. This argument is ignored when`interaction` is not `FALSE`.
`options` | If non-`NULL`, a named `list` of arguments to pass to `update`, just after the object is constructed.
`adjust` | Method to use for adjusting P values. This is passed to `summary`. This argument is available in `contrast` for historical reasons; but it is better style to specify the adjustment method, along with other testing options such as `side`, as part of `options`.
`joint` | Logical value. If `FALSE`, the arguments are passed to `summary` with `infer=c(FALSE,TRUE)`. If `TRUE`, a joint test of the hypothesis L beta = null is performed, where L is `object@linfct` and beta is the vector of fixed effects estimated by `object@betahat`. This will be either an F test or a chi-square (Wald) test depending on whether degrees of freedom are available.
`rows` | Integer values. The rows of L to be tested in the joint test. If missing, all rows of L are used. If not missing, `by` variables are ignored.
`null` | Numeric value specifying the null value(s) being tested against. It may be either a single value, in which case it is used as the null value for all linear functions under test; or a numeric vector of length equal to the number of linear functions.
`parm` | This is ignored, but it is a required argument of the generic `confint` method.)
`verbose` | Logical value. If `TRUE` and `joint==TRUE`, a table of the effects being tested is printed.
`level` | Numeric value of the desired confidence level.
`which` | When `object` is a list of `lsmobj` objects, this specifies which member of the list is analyzed.
`reverse` | Logical value determining whether `"pairwise"` or `"revpairwise"` pairwise comparisons are generated.
`...` | Additional arguments passed to `summary` or to a contrast function.

### Details

Though `contrast` is ordinarily used to create true contrasts (whose coefficients sum to zero), it may be used to estimate any linear function of the LS means; and `offset` expands this capability further by allowing additive constants. `pairs` is equivalent to `contrast` with `method = "pairwise"`.

`confint` and `test` (when `JOINT==FALSE`) are equivalent to calling `summary` with `infer=c(TRUE,FALSE)` and `infer=c(FALSE,TRUE)`, respectively.

When using `test` to do a joint test of L beta = null, an error is thrown if any row of L is non-estimable. It is permissible for the rows of L to be linearly dependent as long as `null == 0`; a reduced set of contrasts is tested. Linear dependence and nonzero `null` cause an error.

### Value

`contrast` and `pairs` return an object of class `"lsmobj"`, which is an extension of `"ref.grid"`. Consequently, they may be used as arguments to other `"lsmobj"` or `"ref.grid"` methods. The user may, for example, compute contrasts of contrasts, or re-summarize a set of confidence intervals with a different `by` grouping or confidence level. The “grid” for the returned value is simply the set of variables that identify the results. For example, `contrast`'s return value is a reference grid for one factor named `contrast`.

`confint` and `test` (when `Joint==FALSE`) return an object of class `summary.ref.grid`. When `JOINT==TRUE`, `test` returns a `"summary.ref.grid"` object (extends `"data.frame"`) with the test statistic, degrees of freedom, and P value for each `by` group.

When `object` is the result of a call to `contrast` or `pairs`, the `coef` method returns a`data.frame`. The initial columns are the factor combinations that were contrasted (i.e. the grid for the `object` originally specified in the call to `contrast`), and the remaining columns (named `c.1`, `c.2`, ...) contain the contrast coefficients that were applied to the corresponding predictions. If `object` was not produced via `contrast`, `NULL` is returned, along with a message.

### Author(s)

Russell V. Lenth

### See Also

Additional `"lsmobj"` methods having their own help pages are `cld` and `glht`. Also, the `summary` and other methods for `"ref.grid"` objects also work for `"lsmobj"` objects.

### Examples

    require(lsmeans)
    warp.lm <- lm(breaks ~ wool*tension, data = warpbreaks)
    warp.lsm <- lsmeans(warp.lm, ~ tension | wool)

    # Polynomial contrasts of tension, by wool
    (warp.pl <- contrast(warp.lsm, "poly", name = "order"))
    # Same results with a different adjustment
    summary(warp.pl, adjust = "fdr")

    # Jointly test the tension effects for each wool
    test(warp.pl, joint = TRUE, by = "wool")

    # Compare the two contrasts for each order
    contrast(warp.pl, "revpairwise", by = "order")

    # User-provided contrasts, ignoring the previous by grouping
    contrast(warp.lsm,
        list(c1=c(1,0,0,-1,0,0), c2=c(1,1,1,-1,-1,-1)/3),
        by = NULL)

    # Compare consecutive tension*wool comb's as treatment with 6 levels
    contrast(warp.lsm, "consec", by = NULL)

    # Interaction contrasts (comparisons of linear and quadratic contrasts)
    (int.con <- contrast(warp.lsm, interaction = c("poly", "consec"), by = NULL))

    # See the contrast coefficients used by the previous call
    coef(int.con)

[Package lsmeans version 2.25-5 Index]