lsmeans (version 2.10)

lsmeans: Least-squares means

Description

Compute least-squares means for specified factors or factor combinations in a linear model, and optionally comparisons or contrasts among them.

Usage

## S3 method for class 'character':
lsmeans(object, specs, ...)
## (used when 'specs' is 'character')

## S3 method for class 'character.ref.grid':
lsmeans(object, specs, by = NULL, 
    fac.reduce = function(coefs) apply(coefs, 2, mean), contr, 
    options = getOption("lsmeans")$lsmeans, ...)
## (used when 'object' is a 'ref.grid' and 'specs' is 'character')
    
## S3 method for class 'list':
lsmeans(object, specs, ...)
## (used when 'specs' is a 'list')

## S3 method for class 'formula':
lsmeans(object, specs, contr.list, trend, ...)
## (used when 'specs' is a 'formula')

lstrends(model, specs, var, delta.var = 0.01 * rng, data, ...)

Arguments

object

An object of class ref.grid; or a fitted model object that is supported, such as the result of a call to lm or lmer.

specs

A character vector specifying the names of the predictors over which LS-means are desired. specs may also be a formula or a list (optionally named) of valid specs. Use of formulas is describ

by

A character vector specifying the names of predictors to condition on.

fac.reduce

A function that combines the rows of a matrix into a single vector. This implements the ``marginal averaging'' aspect of least-squares means. The default is the mean of the rows. Typically if it is overridden, it would be some kind of weighted mean of the

contr

A list of contrast coefficients to apply to the least-squares means -- or the root name of an .lsmc function that returns such coefficients. In addition, contr = "cld" is an alternative way to invoke the

contr.list

A named list of lists of contrast coefficients, as for contr. This is used only in the formula method; see Details below.

options

If non-NULL, a named list of arguments to pass to update, just after the object is constructed.

trend

Including this argument is an alternative way of calling lstrends with it as its var argument.

model

A supported model object.

var

Character giving the name of a variable with respect to which a difference quotient of the linear predictors is computed. In order for this to be useful, var should be a numeric predictor that interacts with at least one factor in specs

delta.var

The value of h to use in forming the difference quotient (f(x+h) - f(x))/h. Changing it (especially changing its sign) may be necessary to avoid numerical problems such as logs of negative numbers. The default value is 1/100 of the range

data

As in ref.grid, you may use this argument to supply the dataset used in fitting the model, for situations where it is not possible to reconstruct the data. Otherwise, leave it missing.

...

Additional arguments passed to other methods or to ref.grid.

Value

• An object of class lsmobj -- except when specs is a list or a formula having a left-hand side, a list of slmobj objects. A number of methods are provided for further analysis, including summary, confint, test, contrast, pairs, and cld.

Details

Least-squares means are predictions from a linear model over a reference grid, or marginal averages thereof. They have been popularized by SAS (SAS Institute, 2012). The ref.grid function identifies/creates the reference grid upon which lsmeans is based. If specs is a formula, it should be of the form contr ~ specs | by. The formula is parsed and then used as the arguments contr, specs, and by as indicated. The left-hand side is optional, but if specified it should be the name of a contrast family (e.g., pairwise) or of a sub-list of contr.list. Operators like * or : are necessary to delineate names in the formulas, but otherwise are ignored. A number of standard contrast families are provided. They can be identified as functions having names ending in .lsmc -- use ls("package:lsmeans", pat=".lsmc") to list them. See the documentation for pairwise.lsmc and its siblings for details. You may write your own .lsmc function for custom contrasts. For models fitted using the lme4 package, degrees of freedom are obtained using the Kenward-Roger (1997) method as implemented in the package pbkrtest, if it is installed. If pbkrtest is not installed, the degrees of freedom are set to NA and asymptotic results are displayed. You may also, if you like, disable the use of pbkrtest via lsm.options(disable.pbkrtest=TRUE) (this does not disable the pbkrtest package entirely, just its use in lsmeans). The df argument in the lsmeans or ref.grid call (or later in update or summary) may be used to specify some other degrees of freedom. Specifying df is not equivalent to disabling pbkrtest, because if not disabled, it also makes a bias adjustment to the covariance matrix.

References

Kenward, M.G. and Roger, J.H. (1997) Small sample inference for fixed effects from restricted maximum likelihood, Biometrics, 53, 983--997. SAS Institute Inc. (2012) Online documentation; Shared concepts; LSMEANS statement, http://support.sas.com/documentation/cdl/en/statug/63962/HTML/default/viewer.htm#statug_introcom_a0000003362.htm, accessed August 15, 2012.

See Also

pairwise.lsmc, glht

Examples

require(lsmeans)

### Covariance example (from Montgomery Design (8th ed.), p.656)
# Uses supplied dataset 'fiber'
fiber.lm <- lm(strength ~ diameter + machine, data = fiber)

# adjusted means and comparisons, treating machine C as control
( fiber.lsm <- lsmeans (fiber.lm, "machine") )
contrast(fiber.lsm, "trt.vs.ctrlk")
# Or get both at once using
#     lsmeans (fiber.lm, "machine", contr = "trt.vs.ctrlk")

### Factorial experiment
warp.lm <- lm(breaks ~ wool * tension, data = warpbreaks)
( warp.lsm <- lsmeans (warp.lm,  ~ wool | tension,
    options = list(estName = "pred.breaks")) )
pairs(warp.lsm) # remembers 'by' structure
contrast(warp.lsm, method = "poly", by = "wool")

### Unbalanced split-plot example ###
#-- The imbalance is imposed deliberately to illustrate that
#-- the variance estimates become biased
require(nlme)
Oats.lme <- lme(yield ~ factor(nitro) + Variety, 
    random = ~1 | Block/Variety, 
    subset = -c(1,2,3,5,8,13,21,34,55), data = Oats)
lsmeans(Oats.lme, list(poly ~ nitro, pairwise ~ Variety))

# Model with a quadratic trend for 'nitro'
Oatsq.lme <- update(Oats.lme, . ~ nitro + I(nitro^2) + Variety)
# Predictions at each unique 'nitro' value in the dataset
lsmeans(Oatsq.lme, ~ nitro, cov.reduce = FALSE)

# Trends
fiber.lm <- lm(strength ~ diameter*machine, data=fiber)
# Obtain slopes for each machine ...
( fiber.lst <- lstrends(fiber.lm, "machine", var="diameter") )
# ... and pairwise comparisons thereof
pairs(fiber.lst)

# Suppose we want trends relative to sqrt(diameter)...
lstrends(fiber.lm, ~ machine | diameter, var = "sqrt(diameter)", 
    at = list(diameter = c(20,30)))
    
# See also many other examples in documentation for 
# 'contrast', 'cld', 'glht', 'lsmip', 'ref.grid', 'MOats',
# 'nutrition', etc., and in the vignettes