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
grouping symbols.
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 lm
, 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
writing recover_data
and 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
Rtools
.
For the latest release notes on this development version, see the NEWS file
do.call(paste, ...)
and do.call(order, ...)
,
to prevent problems with factor names like method
that are argument names
for these functions (#94)summary.emmGrid()
whereby transformations of class
list
were ignored.update.emmGrid(..., levels = levs)
whereby we can easily
relabel the reference grid and ensure that the grid
and roles
slots
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 order()
CLD()
due to its
misleading display of pairwise-comparison tests.betareg
objects, where the wrong terms
component was
sometimes used.by
variables are present (#98).pwpp()
function to plot P values of comparisonssummary(..., 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 prob
mode (#83).sommer::mmer
, MuMIn::averaging
, and
mice::mira
objectsnnet::multinom
support when there are 2 outcomes (#19)gls
objectsfamSize
now correct when exclude
or include
is used in
a contrast function (see #68)aovList
objects, in part
due to the popularity of afex::aov_ez()
which uses these models.emm_options(opt.digits = FALSE)
include
argument to most .emmc
functions (#67)ref
, exclude
, and include
in
.emmc
functions (#68)...
arguments in emmeans()
when two-sided formulas are presentclm
support when model is rank-deficientregrid(..., transform = "log")
error when there are
existing non-estimable cases (issue #65)brmsfit
support (#43)mgcv::gam
and mgcv::gamm
models.my.vcov()
now passes ...
to clientsmanova
object no longer requires data
keyword (#72)aovlist
models (#73)CLD
fatal error when sort = TRUE
(#77)lme
objects (#75)"mvt"
adjustment ignored by
groupingcontrast()
mis-labeled estimates when levels varied among by
groups
(most prominently this happened in CLD(..., details = TRUE)
)aovlist
support so it re-fits the model when non-sum-to-zero
contrasts were usedprint.summary_emm()
now cleans up numeric columns with zapsmall()
nesting
in ref_grid()
and update()
,
and addition of covnest
argument for whether to include covariates
when auto-detecting nestinghpd.summary()
and handoff to it from summary()
ref_grid()
ignored mult.levs
...
where it shouldn'tCLD()
now works for MCMC models (uses frequentist summary)opt.digits
optionref.grid()
put to final rest, and we no
longer support packages that provide recover.data
or lsm.basis
methods.recover_data()
and .emm_basis()
to provide
access for extension developers to all available methodsinst/extdata
.all.vars()
that could cause errors when response variable
has a function call with character constants.regrid()
(so results match summary()
labeling with type = "response"
).plot.emmGrid(..., comparisons = TRUE, type = "response")
produced incorrect comparison arrows; now fixeddf$y ~ df$treat + df[["cov"]]
. This had
failed previously for two obscure reasons, but now works correctly.simplify.names
option for above types of modelsemm_options()
with no arguments now returns all options in force,
including the defaults. This makes it more consistent with options()
emtrends()
; produced incorrect results in models with offsets.update.emmGrid()
and emm_options()
qdrg()
function (quick and dirty reference grid) for help with
unsupported model objectscld()
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 cld
with or without having
multcomp installed.xtending.Rmd
vignette on how to export methodsrevpairwise.emmc
and cld
regarding comparing only 1 EMMcld.emm_list
now returns results only for object[[ which[1] ]]
,
along with a warning message.emmeans
specs like cld ~ group
, a vestige of lsmeans
as it did not work correctly (and was already undocumented)Suggests
(dozens and dozens fewer dependencies)lme
models in "models" vignette.emmc
functions (#22)exclude
argument to most .emmc
functions: allows
user to omit certain levels when computing contrastshpd.summary()
function for Bayesian models to show HPD intervals
rather than frequentist summary. Note: summary()
automatically
reroutes to it. Also plot()
and emmip()
play along.nlme::lme
modelsSurv()
was interpreted
as a response transformation.cld()
is applied to an emm_list
(issue #24)offset
argument to ref_grid()
(scalar offset only) and to
emmeans()
(vector offset allowed) -- (issue #18)[.summary_emm
to choose whether to
retain its class or coerce to a data.frame
(relates to issue #14)reverse
option for trt.vs.ctrl
and relatives (#27)terms
is accessed with lme
objects to make
it more robustemmeans:::convert_scripts()
renames output file more simply[
method for class summary_emm
simple
argument for contrast
- essentially the complement of by
joint_tests()
ref_grid()
accept ylevs
list of length > 1;
also slight argument change: mult.name
-> mult.names
emmeans()
wherein weights
was ignored
when specs
is a list
data
argument, if supplied to a data.frame
(recover_data()
doesn't like tibbles...)as.data.frame
method for emmGrid
objects, making it
often possible to pass it directly to other functions as a data
argument.contrast()
where by
was ignored for
interaction contrastsas.glht()
where it choked on df = Inf
data
or subset
joint_tests()
function tests all [interaction] contrastsgamlss
objects (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 ~ 1
.emmeans()
might pass data
to contrast()
summary.emmGrid()
emm_options(summary = ...)
to work as
advertised.emmGrid()
function to emm()
as had been intended
as alternative to mcp()
in multcomp::glht()
(result of ditto).cld.emm_list()
Inf
to display d.f. for asymptotic (z) tests. (NA
will
still work too but Inf
is a better choice for consistency and meaning.)recover_data()
now throws an error when it finds recovered data not reproduciblevcov()
calls to comply with recent R-devel changesThis 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.
emmeans()
, emtrends()
, emmip()
, etc.
But lsmeans()
, lstrends()
, etc. as well as pmmeans()
etc. are
mapped to their corresponding emxxxx()
functions.ref.grid -> ref_grid
, lsm.options -> emm_options
, etc.ref.grid
and lsmobj
are gone.
Both are replaced by class emmGrid
. An as.emmGrid()
function
is provided to convert old objects to class emmGrid
.lmerMod models
. Also added options disable.lmerTest
and lmerTest.limit
, similar to those for pbkrtest.neuralgia
and pigs
datasetsemmmeans()
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 emm_options()
)plot()
and emmip()
are now ggplot2-based.
Old lattice-based functionality is still available too,
and there is a graphics.engine
option to choose the default.Suggests
pkgs to Enhances
when not needed for
building/testingNew developments will take place in emmeans, and lsmeans will remain static and eventually will be archived.