emmeans is a continuation of the lsmeans package. The name is changed for two reasons:
ref.grid
and lsmobj
, and it was confusing to some users that they needed to use primarily ref.grid
methods to summarize lsmobj
objects. The emmeans package has only an emmGrid
class that covers both of the old classes. Changing the name of the package at the same time as the object classes are changed makes for a cleaner transition.For the most part, all that most users need to do to transition from using the lsmeans package is to use require(emmeans)
or library(emmeans)
to load the package. With that one change, almost all of the code in the using-lsmeans vignette runs without alteration, and almost all examples from the help system for lsmeans also work as-is. Even though we now emphasize using the emmeans()
function and related “em” functions, lsmeans()
and its relatives are still available as wrappers for the new functions.
That said, here are a few changes that former lsmeans users may need to be aware of:
emmeans:::convert_scripts()
that may be used to convert old scripts that used lsmeans to use emmeans instead. See more belowSome functions are deprecated, e.g. ref.grid()
, lsm.options()
, etc. They will work, but you will get a deprecated message advising you to use ref_grid()
and emm_options()
, etc.1
While the functions lsmeans()
, lsmip()
, etc. will continue to be provided, all the help-page and vignette descriptions refer to their new counterparts emmeans()
, emmip()
, etc. So you will need to get accustomed to new terminology like “EMMs”, even if you don’t choose to use it in your own work.2
lsmeans::
, or calls to require(lsmeans)
or library(lsmeans)
, obviously you need to change these to use emmeans
instead..emmc
instead of lsmc
. See the example under help("contrast-methods")
.ref.grid
or lsmobj
objects), they should still work in emmeans. The issue you may face, though, is that the lsmeans package could get loaded simply because these objects are present, and put in the search()
path. To make sure you’re using the new package, convert the objects to class emmGrid
– e.g., my_new_ref_grid <- as.emmGrid(my.old.ref.grid)
. Running the non-exported function emmeans:::convert_workspace()
may be used to convert all the objects in an environment (the global one by default) and clean out any dependencies on lsmeans. See more belowemmip()
and plot()
functions use graphics from the ggplot2 package by default. If you prefer the lattice graphics produced by the lsmeans package, they are still available: Use emm_options(graphics.engine = "lattice")
to change the default, or add engine = "lattice"
to the call to for a particular plot.vignette("models")
rather than the help page of the same name. It includes a quick reference chart at the beginning that should prove helpful.vignette("basics")
to obtain an overview. The vignette index has links to all the vignettes.lsmeans
and ref.grid
have been remapped to emmeans
and ref_grid
respectively. For example, calling lsm.options(lsmeans = ...)
remaps as emm_options(emmeans = ...)
. See help("emm_options", package = "emmeans")
and help("lsm.options", package = "lsmeans")
for explanations of these options.The degrees-of-freedom saga, continued… Initially, lsmeans used the pbkrtest package to compute degrees of freedom (via the Kenward-Roger method) for lme4::lmerMod
models. Later, the default was changed to the Satterthwaite method, implemented in the lmerTest package. Both methods are problematic; but I have decided to revert to the Kenward-Roger method as the system default. The default may be changed via emm_options(lmer.df = ...)
. See vignette("models")
for details.
The user may run
emmeans:::convert_scripts()
to convert R scripts or R Markdown files to use emmeans functions. (This is a non-exported function – you need three :
s in there.)
lsmeans()
or pmmeans()
to be replaced by calls to emmeans()
(it’s your choice; the former still work).-emm
added to the root name; for example, myfile.R
is converted and saved as myfile-emm.R
.The conversion routines will convert the following to their emmeans
counterparts:
require(lsmeans)
and library(lsmeans)
to require(emmeans)
and library(emmeans)
lsmeans::
to emmeans::
ref.grid(
to ref_grid(
lsm.options(
and get.lsm.option(
to emm_options(
and get_emm_option(
(arguments thereof are also converted)..lsmc
to .emmc
(contrast-method names)lsmeans(
and relatives to emmeans(
and relatives, if opted forpmmeans(
and relatives to emmeans(
and relatives, if opted forIf you have any objects from the lsmeans package laying around, it is all too likely that the lsmeans package will be loaded, and perhaps even get added to the search path. This can create annoying messages, if not conflicts. When this happens, type
emmeans:::convert_workspace()
on the console. This will convert any ref.grid
or lsmobj
objects laying around to the new emmGrid
class, and unload all vestiges of lsmeans.
Once you are comfortable using emmeans in place of lsmeans, you may effect a permanent solution (the “nuclear option?”) by uninstalling the lsmeans package. Doing so will not prevent you from converting old workspaces or scripts. Watch your package updates carefully, though, as it may get re-installed if it is still imported by another package.
if you are the developer of a package that supports lsmeans, and you want to transition to supporting emmeans, I make the following suggestions:
recover.data.xyz()
and lsm.basis.xyz()
, where xyz
stands in for the class of your object. Rename these functions recover_data.xyz()
and emm_basis.xyz()
.lsmeans::
functions in the above methods should be changed to the corresponding emmeans::
functions.recover.data.xyz()
and lsm.basis.xyz()
that just call their counterparts.DESCRIPTION
file, add emmeans
to Imports
, and make sure that lsmeans
is not in Imports
.NAMESPACE
file,
importFrom(emmeans, recover_data, emm_basis)
S3method(recover_data, xyz)
S3method(emm_basis, xyz)
export(recover.data.xyz, lsm.basis.xyz)
. That is, export them as functions, and not as S3 methodsrecover_data.xyz
and emm_basis.xyz
.Many of the deprecated functions, like ref.grid()
, are renamed to avoid possible confusion in S3 method dispatch: how do we know that summary.ref.grid()
wasn’t a summary.ref()
method for class grid
, rather than a summary()
method for class ref.grid
?↩
By the way, the pmmeans()
, pmmip()
, etc. wrappers already provided in lsmeans are also still available.↩