Transitioning to emmeans from lsmeans

Russ Lenth

2018-10-26

Contents

This vignette is here to help past users of the lsmeans package.

  1. Overview
  2. User impact
  3. Converting old scripts
  4. Converting old workspaces
  5. Notes for package developers

Index of all vignette topics

Overview

emmeans is a continuation of the lsmeans package. The name is changed for two reasons:

  1. The term “least-squares means” is misleading in terms of describing the analyses it provides. The term “estimated marginal means” (EMMs) is well-accepted, and it better describes the basic idea that we use marginal means of predictions over a reference grid. When we do that with, say, an ordinal model, the concept “estimated marginal mean” makes sense while “least-squares mean” does not, because no least-squares methods are used to fit the model or obtain the EMMs.
  2. A number of changes are made to the internal architecture of the package. The lsmeans package had two classes, 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.

Back to Contents

User impact

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:

Back to Contents

Converting scripts

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.)

The conversion routines will convert the following to their emmeans counterparts:

Back to Contents

Converting workspaces

If 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.

Back to Contents

Index of all vignette topics