lsmeans (version 2.23)

contrast: 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

"contrast"(object, method = "eff", interaction = FALSE,  by, offset = NULL, name = "contrast",  options = getOption("lsmeans")$contrast, adjust, ...)
"contrast"(object, ..., which = 1)
"test"(object, null = 0, joint = FALSE, verbose = FALSE, rows, by,  ...)
"confint"(object, parm, level = 0.95, ...)
"pairs"(x, reverse = FALSE, ...)

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 wheninteraction 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 wheninteraction 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.

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.

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.

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)
contrast(warp.lsm, interaction = c("poly", "consec"), by = NULL)