Obtain estimated marginal means (EMMs) for many linear, generalized
linear, and mixed models. Compute contrasts or linear functions of EMMs,
trends, and comparisons of slopes. Plots and other displays.
Least-squares means are discussed, and the term "estimated marginal means"
is suggested, in Searle, Speed, and Milliken (1980) Population marginal means
in the linear model: An alternative to least squares means, The American
Statistician 34(4), 216-221
Estimated marginal means (EMMs, previously known as least-squares means in the context of traditional regression models) are derived by using a model to make predictions over a regular grid of predictor combinations (called a reference grid). These predictions may possibly be averaged (typically with equal weights) over one or more of the predictors. Such marginally-averaged predictions are useful for describing the results of fitting a model, particularly in presenting the effects of factors. The emmeans package can easily produce these results, as well as various graphs of them (interaction-style plots and side-by-side intervals).
Estimation and testing of pairwise comparisons of EMMs, and several other
types of contrasts, are provided. There is also a
cld method for display of
Two-way support of the
glht function in the multcomp package.
For models where continuous predictors interact with factors, the package's
emtrends function works in terms of a reference grid of predicted slopes of
trend lines for each factor combination.
Vignettes are provided on various aspects of EMMs and using the package. See the CRAN page
The package incorporates support for many types of models, including
standard models fitted using
glm, and relatives,
various mixed models, GEEs, survival models, count models,
ordinal responses, zero-inflated models, and others. Provisions for
some models include special modes for accessing different types of
predictions; for example, with zero-inflated models, one may opt for
the estimated response including zeros, just the linear predictor,
or the zero model.
For details, see
vignette("models", package = "emmeans")
Various Bayesian models (carBayes, MCMCglmm, MCMCpack) are supported by way of creating a posterior sample of least-squares means or contrasts thereof, which may then be examined using tools such as in the coda package.
Package developers may provide emmeans support for their models by
emm_basis methods. See
vignette("extending", package = "emmeans")
CRAN The latest CRAN version may be found at https://CRAN.R-project.org/package=emmeans. Also at that site, formatted versions of this package's vignettes may be viewed.
Github To install the latest development version from Github, install the newest version (definitely 2.0 or higher) of the devtools package; then run
devtools::install_github("rvlenth/emmeans", dependencies = TRUE, build_opts = "")### To install without vignettes (faster):devtools::install_github("rvlenth/emmeans")
Note: If you are a Windows user, you should also first download and
install the latest version of
For the latest release notes on this development version, see the NEWS file
do.call(order, ...), to prevent problems with factor names like
methodthat are argument names for these functions (#94)
summary.emmGrid()whereby transformations of class
update.emmGrid(..., levels = levs)whereby we can easily relabel the reference grid and ensure that the
rolesslots stay consistent. Added vignette example.
emmeans(). We now ensure that the original order of the reference grid is preserved. Previously, the grid was re-ordered if any numeric or character levels occurred out of order, per
CLD()due to its misleading display of pairwise-comparison tests.
betaregobjects, where the wrong
termscomponent was sometimes used.
byvariables are present (#98).
pwpp()function to plot P values of comparisons
summary(..., adjust = "scheffe"). We now actually compute and use the rank of the matrix of linear functions to obtain the F numerator d.f., rather than trying to guess the likely correct value.
contrast()results if they are later used by
emmeans(). This was first noticed with ordinal models in
nnet::multinomsupport when there are 2 outcomes (#19)
famSizenow correct when
includeis used in a contrast function (see #68)
aovListobjects, in part due to the popularity of
afex::aov_ez()which uses these models.
emm_options(opt.digits = FALSE)
includeargument to most
emmeans()when two-sided formulas are present
clmsupport when model is rank-deficient
regrid(..., transform = "log")error when there are existing non-estimable cases (issue #65)
manovaobject no longer requires
CLDfatal error when
sort = TRUE(#77)
contrast()mis-labeled estimates when levels varied among
bygroups (most prominently this happened in
CLD(..., details = TRUE))
aovlistsupport so it re-fits the model when non-sum-to-zero contrasts were used
print.summary_emm()now cleans up numeric columns with
update(), and addition of
covnestargument for whether to include covariates when auto-detecting nesting
hpd.summary()and handoff to it from
...where it shouldn't
CLD()now works for MCMC models (uses frequentist summary)
ref.grid()put to final rest, and we no longer support packages that provide
.emm_basis()to provide access for extension developers to all available methods
.all.vars()that could cause errors when response variable has a function call with character constants.
regrid()(so results match
type = "response").
plot.emmGrid(..., comparisons = TRUE, type = "response")produced incorrect comparison arrows; now fixed
df$y ~ df$treat + df[["cov"]]. This had failed previously for two obscure reasons, but now works correctly.
simplify.namesoption for above types of models
emm_options()with no arguments now returns all options in force, including the defaults. This makes it more consistent with
emtrends(); produced incorrect results in models with offsets.
qdrg()function (quick and dirty reference grid) for help with unsupported model objects
cld()has been deprecated in favor of
CLD(). This had been a headache. multcomp is the wrong place for the generic to be; it is too fancy a dance to export
cldwith or without having multcomp installed.
xtending.Rmdvignette on how to export methods
cldregarding comparing only 1 EMM
cld.emm_listnow returns results only for
object[[ which ]], along with a warning message.
cld ~ group, a vestige of lsmeans as it did not work correctly (and was already undocumented)
Suggests(dozens and dozens fewer dependencies)
lmemodels in "models" vignette
excludeargument to most
.emmcfunctions: allows user to omit certain levels when computing contrasts
hpd.summary()function for Bayesian models to show HPD intervals rather than frequentist summary. Note:
summary()automatically reroutes to it. Also
Surv()was interpreted as a response transformation.
cld()is applied to an
ref_grid()(scalar offset only) and to
emmeans()(vector offset allowed) -- (issue #18)
[.summary_emmto choose whether to retain its class or coerce to a
data.frame(relates to issue #14)
trt.vs.ctrland relatives (#27)
termsis accessed with
lmeobjects to make it more robust
emmeans:::convert_scripts()renames output file more simply
[method for class
contrast- essentially the complement of
ylevslist of length > 1; also slight argument change:
weightswas ignored when
dataargument, if supplied to a data.frame (
recover_data()doesn't like tibbles...)
emmGridobjects, making it often possible to pass it directly to other functions as a
bywas ignored for interaction contrasts
as.glht()where it choked on
df = Inf
joint_tests()function tests all [interaction] contrasts
gamlssobjects (but doesn't support smoothing). Additional argument is
what = c("mu", "sigma", "nu", "tau")It seems to be flaky when the model of interest is just
emm_options(summary = ...)to work as advertised.
emm()as had been intended as alternative to
multcomp::glht()(result of ditto).
Infto display d.f. for asymptotic (z) tests. (
NAwill still work too but
Infis a better choice for consistency and meaning.)
recover_data()now throws an error when it finds recovered data not reproducible
vcov()calls to comply with recent R-devel changes
This is the initial major version that replaces the lsmeans package. Changes shown below are changes made to the last real release of lsmeans (version 2.27-2). lsmeans versions greater than that are transitional to that package being retired.
emmip(), etc. But
lstrends(), etc. as well as
pmmeans()etc. are mapped to their corresponding
ref.grid -> ref_grid,
lsm.options -> emm_options, etc.
lsmobjare gone. Both are replaced by class
as.emmGrid()function is provided to convert old objects to class
lmerMod models. Also added options
lmerTest.limit, similar to those for pbkrtest.
emmmeans()methods is now top-down rather than convoluted intermingling of S3 methods
-s in labels to
/s to emphasize that thnese results are ratios.
ref_grid. (Can be disabled via
emmip()are now ggplot2-based. Old lattice-based functionality is still available too, and there is a
graphics.engineoption to choose the default.
Enhanceswhen not needed for building/testing
New developments will take place in emmeans, and lsmeans will remain static and eventually will be archived.