Package lsmeans. February 15, 2013

Transcription

1 Type Package Title Least-squares means Version Date Encoding latin1 Author Russell V. Lenth Package lsmeans February 15, 2013 Maintainer Russ Lenth Suggests nlme, lme4, pbkrtest, multcomp Enhances multcomp Imports Matrix, multcomp LazyData yes Description This package provides the function lsmeans for outputting so-called least-squares means for factor combinations in an lm, lme, or lmer object. It can also compute contrasts or linear combinations of these least-squares means, and several standard contrast families are provided. License GPL-2 Repository CRAN Date/Publication :35:49 NeedsCompilation no R topics documented: lsmeans-package fiber lsmeans nutrition pairwise.lsmc

2 2 fiber Index 12 lsmeans-package Least-squares means Description Details This package provides the function lsmeans for outputting so-called least-squares means for factor combinations in an lm, lme, gls, or lmer object. It can also compute contrasts or linear combinations of these least-squares means, and several standard contrast families are provided. It may also be used for the obtaining linear predictors and contrasts thereof in glm and glmer objects. Popular adjustments for multiple-comparisons are provided; optionally, contrasts may instead be passed to glht, if the multcomp package is installed. In analyzing mer objects, if the pbkrtest package is installed, its vcovadj function is used to bias-adjust the covariance matrix and obtain degrees of freedom. Examples and discussion are available via vignette("using-lsmeans", package="lsmeans"). Package: Type: Version: Date: License: lsmeans Package See DESCRIPTION See DESCRIPTION GPL-2 See the documentation for lsmeans. Author(s) Russell V. Lenth Maintainer: Russ Lenth See Also nlme lme4 multcomp pbkrtest fiber Fiber data Description Fiber data from Montgomery Design (8th ed.), p.656 (Table 15.10). Useful as a simple analysis-ofcovariance example.

3 lsmeans 3 Usage fiber Format Details Source A data frame with 15 observations on the following 3 variables. machine a factor with levels A B C. The primary factor of interest. strength a numeric vector. The response variable. diameter a numeric vector. A covariate. The goal of the experiment is to compare the mean breaking strength of fibers produced by the three machines. When testing this, the technician also measured the diameter of each fiber, and this measurement may be used as a concomitant variable to improve precision of the estimates. Montgomery, D. C. (2013) Design and Analysis of Experiments (8th ed.). John Wiley and Sons, ISBN Examples require(lsmeans) fiber.lm <- lm(strength ~ diameter + machine, data=fiber) lsmeans(fiber.lm, pairwise ~ machine) lsmeans Least-squares means Description Usage Compute least-squares means for specified factors or factor combinations in a linear model, and optionally comparisons or contrasts among them. lsmeans(object, specs, adjust = c("auto","tukey","sidak", p.adjust.methods), conf =.95, at, trend, contr = list(), cov.reduce = function(x, name) mean(x), fac.reduce = function(coefs, lev) apply(coefs, 2, mean), glhargs = NULL, lf = FALSE,...) ## S3 method for class lsm print(x, omit = NULL,...) ## S3 method for class data.frame.lsm

4 4 lsmeans print(x,...) lsm(...) ## S3 method for class lsmlf glht(model, linfct,...) Arguments object specs A lm, aov (with no Error component), glm, lme, gls, lmer, or glmer object having at least one fixed factor among the predictors. A formula, or a list of formulas, specifying the desired families of least-squares means. The right-hand side of each formula specifies the desired factor levels. The optional left-hand side specifies what kind of comparisons or contrasts are desired. For example, ~ treatment requests least-squares means for each level of treatment, and pairwise ~ treatments requests those results, plus pairwise comparisons among them. As another example, in a three-factor model, trt.vs.ctrl1 ~ A B:C requests least-squares means for all combinations of factors A, B, and C, as well as treatment-minus-control comparisons of A for each combination of B and C, where the first level of A is considered the control level. adjust Adjustment method for the p values of tests of contrasts. "auto" uses the method returned in the "adjust" attribute of the contrast function; "tukey" computes p values using the Studentized range distribution with the number of means in the family; "sidak" replaces each p value by 1 - (1 - p)^c, where c is the number of contrasts; "none" makes no adjustments to the p values. In addition, the Bonferroni-inequality-based adjustment methods in p.adjust are available; many of those involve step-down testing with a stopping rule, whereas "tukey", "sidak", "bonferroni", and "none" anticipate that all contrasts will be tested. In many cases, these adjustments are only approximate, especially when the degrees of freedom vary greatly within the family of comparisons. For more accurate adjustments, use glhargs instead. conf at trend contr Desired confidence level for intervals. For robustness, you may specify either a fraction or a percentage; i.e.,.975 and 97.5 yield the same results. An optional named list or named vector of covariate values at which predictions are computed (give only one value for each covariate). If no value is found in at for a particular covariate, then cov.reduce is called. If non-missing and trend is the name of a numeric predictor or a term in object s model, then the linear trends for this predictor are estimated and compared instead of the least-squares means. This is useful in models where the specified variable or term interacts with one or more of the factors in the righthand side of specs. In multi-factor cases, sets of regression coefficients are averaged using fac.reduce, just as with least-squares means. An optional named list. Each entry is itself a list or a data.frame specifying contrast coefficients. If the left-hand side of a formula in specs matches a name in contr, then those contrasts are estimated with the specified leastsquares means. An error will result if the length or one or more contrast vectors mismatches the number of levels of the factor or factor combination. Actually,

5 lsmeans 5 cov.reduce fac.reduce glhargs lf model linfct it is not necessary that they be contrasts; one may use this argument to estimate arbitrary linear combinations of the least-squares means. A function with arguments x and name that should return the value to use in prediction for the covariate with name name and values x. By default, the mean is used. The name argument may help distinguish one covariate from another. A function of coefs and lev where lev is the level of a factor or factor combination at which a least-squares mean is calculated. The argument coefs is a matrix whose rows correspond to the combinations of all factors in the model other than those involved in the lsmeans specification. Each row has the coefficients for the linear combination of the regression coefficients to be used in that case. By default, these rows are averaged together (mimicking SAS), but the user may override that behavior. Besides lev, names(lev) will provide the name of the factor or factor combination, and the row.names of coefs provide the levels of the extraneous factors. If this is a list, the object and specified contrasts are passed to the function glht in the multcomp package, with the contents of glhargs as additional arguments. (If you do not wish to provide additional arguments, use glsargs=list().) If glhargs is left at NULL, or if the multcomp package is not installed, then glht is not called, and the contrast results are produced internally by lsmeans. This argument affects only the results from contrasts and not those for the lsmeans themselves. Note: If glhargs is used, the adjust argument is ignored. If only one set of lsmeans or contrasts thereof is desired, an alternative is to call glht with an lsm call as the linfct argument. If TRUE, the linear functions of the regression coefficients are returned unevaluated. model argument for glht linfct argument for glht... Additional argument(s) passed to the contrast function, or to glht; see Details. x omit Details Object of class "lsm" Indexes of elements of x that you do not want printed. Least-squares means, popularized by SAS, are predictions from a linear model at combinations of specified factors. SAS s documentation describes them as predicted population margins that is, they estimate the marginal means over a balanced population (SAS Institute 2012). In generalized linear models, least-squares means are marginal linear predictions that can be transformed back to the response scale via the inverse-link function. Unspecified factors and covariates are handled by summarizing the predictions over those factors and variables. For example, if the fitted model has formula response ~ x1 + x2 + treat where a1 and x2 are numeric and treat is a factor, the least-squares means will be the predicted response for each treatment, at some specified values of x1 and x2. By default, the means of the two covariates will be used, resulting in what ANOVA textbooks often call the adjusted means. We may use that at argument to instead make predictions at other values of x1 and x2. Now consider the model response ~ A + B + A:B, where A and B are both factors. If we ask for least-squares means for A, then at each level of A we are faced with a different prediction for each

6 6 lsmeans Value level of B. Blind (and default) use of least-squares means would result in these predictions being averaged together with equal weight, and this may be inappropriate, especially when the interaction effect is strong. (A warning is generated in such potentially inappropriate cases.) Like most statistical calculations, it is possible to use least-squares means inappropriately. The fac.reduce argument at least expands one s options in producing meaningful results in multi-factor situations. One other note concerning covariates: One must be careful with covariates that depend on one another. For example, if a model contains covariates x and xsq where xsq = x^2, the default behavior will make predictions at x = mean(x) and xsq = mean(xsq), which probably isn t a valid combination (we need x = mean(x) and xsq = mean(x)^2). The inconsistency is avoided if the model specifis poly(x,2) (or even x + I(x^2)) instead of x + xsq, because then only x is averaged, and everything remains consistent. The built-in contrast methods that can be used in specs formulas are pairwise, revpairwise, poly, trt.vs.ctrl, trt.vs.ctrl1, and trt.vs.ctrlk. They are implemented as functions having the same names with.lsmc added (e.g., pairwise.lsmc). Users may write additional.lsmc functions that generate custom families of contrasts. See the documentation for pairwise.lsmc for an example. When trend is specified and it names a predictor variable in the model, the trend is estimated using a difference quotient over 1/1000 the range of the predictor (centered at the predictor s at value or its cov.reduce result). If trend instead names a model term, then the trend is determined symbolically. It could be informative to run with lf=true. See the examples. Degrees of freedom are currently not provided for lme or glme objects, or for mer objects arising from generalized linear models; in those cases, asymptotic results are printed, and this fact is emphasized by displaying NA for the defrees of freedom. For linear mer objects, degrees of freedom are computed using the Kenward and Roger (1997) method, provided the pbkrtest package is installed (the package is loaded if needed). Moreover, in that case, the adjusted covariance matrix from the vcovadj() function in the pbkrtest package is used to calculate standard errors. See Halekoh and H?jsgaard (2012) and the documentation for KRmodcomp for more details. Degrees of freedom are not known to glht except in the case of lm objects. Note that glht requires the degrees of freedom to be an integer; accordingly, if df is included in glhargs, it is coerced to an integer value of max(1, as.integer(df +.2)). That is, it is forced to be at least 1, and it is taken up to the next higher integer if its fractional part is at least.8. For users of the package multcomp, linear functions corresponding to specs may be passed to glht in two different ways. One is to call glht from within lsmeans by specifying glhtargs. The other way is to call lsmeans from within glht by supplying a call to lsm in its linfct argument. The first way provides summary.glht objects for all contrast results (but not for the lsmeans). The second way passes just one set of linear functions to glht; in particular, only the first element of specs is used, and the last set of linear functions from that specification are given to glht. Thus, glht(model, lsm(~treat)) will estimate the lsmeans of treatments, while glht(model, lsm(pairwise~treat)) will estimate the pairwise comparisons. If the model contains a matrix among its predictors, each column is averaged using the function specified in cov.reduce. There is no provision for matrices in the at argument. If lf==false, lsmeans returns an object of class "lsm", which inherits from "list". Each element of the list is either of class data.frame.lsm or "summary.glht" (see the documentation for glht). (The latter occur only if glhargs is non-null.) Each element summarizes a family of least-squares

7 lsmeans 7 Note means or contrasts among them. Each data.frame.lsm element is an extension of a data.frame and contains lsmeans or contrast estimates and associated quantities. If lf==true, lsmeans returns a list of matrices containing the linear functions generated by specs. The "lsm" and "data.frame.lsm" classes each have only a print method, which exist to display results in the desired format. The lsm function returns an object of class "lsmlf", and may be used in a manner similar to mcp in a call to glht. This is implemented via the provided S3 method for glht for "lsmlf" objects. See the examples. The functions mcp (in multcomp)) and popmeans (in doby) also provide least-squares means, with a different user interface. Author(s) Russell V. Lenth, The University of Iowa References Halekoh, U. and H?jsgaard, S. (2012) A Kenward-Roger Approximation and parametric bootsrap methods for tests in linear mixed models the R package pbkrtest, submitted. Kenward, M.G. and Roger, J.H. (1997) Small sample inference for fixed effects from restricted maximum likelihood, Biometrics, 53, SAS Institute Inc. (2012) Online documentation; Shared concepts; LSMEANS statement, support.sas.com/documentation/cdl/en/statug/63962/html/default/viewer.htm#statug_ introcom_a htm, accessed August 15, 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 lsmeans (fiber.lm, trt.vs.ctrlk ~ machine) ### Factorial experiment warp.lm <- lm(breaks ~ wool * tension, data = warpbreaks) #-- We only need to see the wool*tension means listed once... print(lsmeans (warp.lm, list(pairwise ~ wool tension, poly ~ tension wool)), omit=3)

8 8 lsmeans ### 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)) # Compare with lmer result (if pbkrtest installed, provides df, bias-adjusted SEs) if (require(pbkrtest)) { require(lme4) Oats.lmer <- lmer(yield ~ factor(nitro) + Variety + (1 Block/Variety), subset = -c(1,2,3,5,8,13,21,34,55), data=oats) lsmeans(oats.lmer, list(poly ~ nitro, pairwise ~ Variety)) } # Using in conjunction with glht (note -- this does not use adjusted vcov) if (require(multcomp)) { # calling glht from lsmeans... lsmeans(oats.lmer, pairwise ~ Variety, glhargs=list(df=9)) # calling lsmeans from glht to get simultaneous CIs confint(glht(oats.lmer, linfct = lsm(~ Variety), df=9)) } # Custom contrasts lsmeans(oats.lmer, my.own ~ Variety, contr = list(my.own = list(g.vs.m = c(1,-1,0), GM.vs.V = c(.5,.5,-1)))) #### Examples with trends... # Model with interaction fiber.lm2 = lm(strength ~ diameter * machine, data = fiber) # Compare the linear trends for diameter lsmeans(fiber.lm2, pairwise ~ machine, trend = "diameter") # Model with log(diameter) as the covariate fiber.lm3 = lm(strength ~ log(diameter) * machine, data = fiber) # Compare the fitted linear trends for log(diameter) lsmeans(fiber.lm3, pairwise ~ machine, trend = "log(diameter)") # Compare the fitted linear trends for diameter itself # - this is done via a diff quotient - compare with fiber.lm2 results lsmeans(fiber.lm3, pairwise ~ machine, trend = "diameter") # Examine the linear functions generated for these examples lsmeans(fiber.lm2, ~ machine, trend = "diameter", lf = TRUE) lsmeans(fiber.lm3, ~ machine, trend = "log(diameter)", lf = TRUE) lsmeans(fiber.lm3, ~ machine, trend = "diameter", lf = TRUE)

9 nutrition 9 nutrition Nutrition data Description Usage Format Details Source This observational dataset involves three factors, but where several factor combinations are missing. It is used as a case study in Milliken and Johnson, Chapter 17, p.202. (You may also find it in the second edition, p.278.) nutrition A data frame with 107 observations on the following 4 variables. age a factor with levels Mother s age group. group a factor with levels FoodStamps NoAid. Whether or not the family receives food stamp assistance. race a factor with levels Black Hispanic White. Mother s race. gain a numeric vector (the response variable). Gain score (posttest minus pretest) on knowledge of nutrition. A survey was conducted by home economists to study how much lower-socioeconomic-level mothers knew about nutrition and to judge the effect of a training program designed to increase therir knowledge of nutrition. This is a messy dataset with several empty cells. Milliken, G. A. and Johnson, D. E. (1984) Analysis of Messy Data Volume I: Designed Experiments. Van Nostrand, ISBN Examples require(lsmeans) nutr.aov <- aov(gain ~ (group + age + race)^2, data = nutrition) # Summarize predictions for age group 3 nutr.lsm <- lsmeans(nutr.aov, list(pairwise ~ group race, pairwise ~ race group), at = list(age="3")) with(nutr.lsm[[1]], interaction.plot(group, race, lsmean, type="b")) # Hispanics seem exceptional; but, this doesn t test out due to very sparse data print(nutr.lsm, omit=3)

10 10 pairwise.lsmc pairwise.lsmc Contrast families Description Usage These functions return standard sets of contrast coefficients. The name of any of these functions (with the.lsmc omitted) may be used in the left-hand side of a spec formula in lsmeans. pairwise.lsmc(levs,...) revpairwise.lsmc(levs,...) 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,...) Arguments levs Vector of factor levels... Additional arguments, ignored but needed to make these functions interchangeable max.degree ref Details Value The maximum degree of the polynomial contrasts in poly.lsmc Reference level (or control group) in trt.vs.ctrl.lsmc pairwise.lsmc and revpairwise.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, wereas revpairwise.lsmc generates B-A, C-A, C-B, D-A, D-B, and D-C. 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. 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, ref=1), and trt.vs.ctrlk.lsmc is the same as trt.vs.ctrl, ref=length(levs)) 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.

11 pairwise.lsmc 11 Note You may create your own contrast functions, using these as guides. A function named mycont.lsmc may be invoked in lsmeans via lsmeans(object, mycontr ~ factor). The "desc" and "adjust" attributes are optional; 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) See Also Russell V. Lenth, The University of Iowa lsmeans Examples ### View orthogonal polynomials for 4 levels poly.lsmc(1:4) ## Not run: ### 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 } lsmeans(oats.lme, helmert ~ Variety) ## End(Not run)

12 Index Topic datasets fiber, 2 nutrition, 9 Topic htest lsmeans, 3 lsmeans-package, 2 pairwise.lsmc, 10 Topic models lsmeans, 3 lsmeans-package, 2 pairwise.lsmc, 10 Topic package lsmeans-package, 2 Topic regression lsmeans, 3 lsmeans-package, 2 pairwise.lsmc, 10 poly, 10 poly.lsmc (pairwise.lsmc), 10 popmeans, 7 print.data.frame.lsm (lsmeans), 3 print.lsm (lsmeans), 3 revpairwise.lsmc (pairwise.lsmc), 10 trt.vs.ctrl.lsmc (pairwise.lsmc), 10 trt.vs.ctrl1.lsmc (pairwise.lsmc), 10 trt.vs.ctrlk.lsmc (pairwise.lsmc), 10 vcovadj, 2 data.frame, 7 fiber, 2 glht, 2, 5 7 glht.lsmlf (lsmeans), 3 KRmodcomp, 6 lme4, 2 lsm (lsmeans), 3 lsmeans, 2, 3, 10, 11 lsmeans-package, 2 mcp, 7 multcomp, 2 nlme, 2 nutrition, 9 p.adjust, 4 pairwise.lsmc, 6, 7, 10 pbkrtest, 2 12