lsmeans (version 2.19)

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, weights, ...)
## (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, ...)

lsmobj(bhat, V, levels, linfct, df = NA, post.beta = matrix(NA), ...)

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. Many fitted-model objects are supported; see link{models} for details.

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.

weights

Numeric vector, numeric matrix, or character string specifying weights to use in averaging predictions. If a vector, its length must equal the number of predictions to be averaged to obtain each least-squares mean. If a matrix, each row of the matrix is u

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.

bhat

Numeric. Vector of regression coefficients.

V

Square matrix. Covariance matrix of bhat

levels

Named list or vector. Levels of factor(s) that define the estimates defined by linfct. If not a list, we assume one factor named "level"

linfct

Matrix. Linear functions of bhat for each combination of levels

df

Numeric or function with arguments x,dfargs). If a number, that is used for the degrees of freedom. If a function, it should return the degrees of freedom for sum(x*bhat); if additional parameters are needed, include them in

post.beta

Matrix whose columns comprise a sample from the posterior distribution of the regression coefficients (so that typically, the column averages will be bhat). A 1 x 1 matrix of NA indicates that such a sample is unavailable.

...

Additional arguments passed to other methods or to ref.grid. For example, vcov. may be used to override the default covariance estimate, and some models allow additional options. Some models r

Value

• When specs is a character vector or one-sided formula, an object of class lsmobj. A number of methods are provided for further analysis, including summary, confint, test, contrast, pairs, and cld. When specs is a list or a formula having a left-hand side, the eturn value is an lsm.list object, which is simply a list of lsmobj objects. Methods for lsm.list objects are the same as those for lsmobj, but they apply to only one member of the list, determined by its which argument.

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. The function lsmobj may be used to construct an object just like one returned by lsmeans from user-specified coefficients, covariance matrix, levels (or row labels), linear functions for each row, and degrees of freedom. After the object is constructed, it is updateed with any additional arguments in ....

References

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

models, 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)
(Oats.anal <- lsmeans(Oats.lme, list(poly ~ nitro, pairwise ~ Variety)))


### Issues with lists of specs
test(Oats.anal)                # Uses 1st element by default
confint(Oats.anal, which = 4)  # or confint(Oats.anal[[4]])

# These two calls apply the "bonf" adjustment to different elements...
lsmeans(warp.lm, eff ~ wool, adjust = "bonf") 
lsmeans(warp.lm, eff ~ wool, options = list(adjust = "bonf"))
# Advice: Do one thing at a time if you want non-default adjustments
#   e.g., wool.lsm <- lsmeans(warp.lm, ~ wool)
#         summary(wool.lsm, adjust = "bonf")
#         contrast(wool.lsm, "eff", adjust = "sidak")


### Weights
# See what's being averaged over in the above
lsmeans(Oats.lme, ~ nitro, cov.reduce = FALSE, weights = "show.levels")

# Give three times the weight to Marvellous
lsmeans(Oats.lme, ~ nitro, cov.reduce = FALSE, weights = c(1,3,1))


### Model with a quadratic trend for 'nitro'
# Also illustrates use of `params` argument to list non-predictors
deg = 2
Oatsq.lm <- lm(yield ~ Block + poly(nitro, deg) + Variety, data = Oats)
# Predictions at each unique 'nitro' value in the dataset
lsmeans(Oatsq.lm, ~ nitro, cov.reduce = FALSE, params = "deg")


### 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)))

# Given summary statistics for 4 cities computed elsewhere, 
# obtain multiple comparisons of their means using the
# Satterthwaite method
ybar <- c(47.6, 53.2, 88.9, 69.8)
s <-    c(12.1, 19.5, 22.8, 13.2)
n <-    c(44,   11,   37,   24)
se2 = s^2 / n
Satt.df <- function(x, dfargs)
    sum(x * dfargs$v)^2 / sum((x * dfargs$v)^2 / (dfargs$n - 1))
city.lsm <- lsmobj(bhat = ybar, V = diag(se2),
    levels = list(city = LETTERS[1:4]), linfct = diag(c(1,1,1,1)),
    df = Satt.df, dfargs = list(v = se2, n = n), estName = "mean")
city.lsm
contrast(city.lsm, "revpairwise")
    
    
# See also many other examples in documentation for 
# 'contrast', 'cld', 'glht', 'lsmip', 'ref.grid', 'MOats',
# 'nutrition', etc., and in the vignettes