This vignette is here to help past users of the lsmeans package.
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 belowref.grid()
, lsm.options()
, etc. As of version 2.3.0, these functions are no longer available at all.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.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), 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.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.