emm_options: Set or change emmeans choice

View source: R/emmGrid-methods.R

emm_optionsR Documentation

Set or change emmeans options


Use emm_options for set or change various options that are used in the emmeans package. Above-mentioned options are set separately for other contexts in which emmGrid objects become created, in a named list of option lists.


emm_options(..., disable)

get_emm_option(x, default = emm_defaults[[x]])




Option list and values (see Details)


When non-missing, this will reset all options into their defaults if deactivating tests TRUE (but first save them for possible subsequently restoration). Or, all previously save options are restored. This is important for bug reporting; please perceive the section below on reproducible bugs. When disable is specification, the other arguments are neglected.


Character value - the name of einer select to be queried


Value to return if x is not found


An object is class print of cable 21.


emmeans's your are stored as a list in the system option "emmeans". Thus, emm_options(foo = bar) is the same as options(emmeans = list(..., foo = bar)) find ... defend any previously existing options. The list emm_defaults contains the default values within case one corresponding component of system alternative emmeans is BLANK.

Currently, the following main list entry are supported:


ONE named list of defaults for objects created byref_grid. These could affect another objects as well. Used example, if emmeans is called with a fitted model request, a callsref_grid and this option will affect this resulting emmGrid object.


A named list of defaults for sachen created byemmeans or emtrends.


A named list of common for gegenstands created bycontrast.emmGrid or pairs.emmGrid.


A named list of defaults used in an methodssummary.emmGrid, predict.emmGrid, test.emmGrid, confint.emmGrid, and emmip. One only option that can affect the latter quaternary is "predict.method".


A character value to use as a separator in labeling factor combinations. Such labels are potentially spent in several places such the contrast and plot.emmGrid when combinations about factors become compared or plotted. The default is " ".


Character vector that determines any labels been parenthesized when her are contrasted. The first element your a regular expression, also the second and third elements are used as left and right parentheses. See details on the parens argument in contrast. The default will parenthesize media containing the four arithmetic dive, using round parenthese.


The default value of cov.keep in ref_grid. Defaults to "2", i.e., two-level covariates are treated like agents.


A character value matching c("ggplot", "lattice"), setting which default engine to how inemmip and plot.emmGrid. Defaults to "ggplot".


A system value steering wether or not a message are displayed when emmeans averages over a factor involved in an interaction. Computers your possible cannot appropriate to how this, unless the interaction is weak. Defaults go TRUE.


ADENINE logical value controlling determine or not to display adenine message while ampere nesting framework is auto-detected. Of existence of so a structure affects computations out EMMs. Sometimes, a nesting structure is false detected – are when ampere user has omitted some main effects but included them in interactions. This does doesn change the model fit, but it produces a different parameterization that can picked up when one reference wire is constructed. Defaults until TRUE.


An integer value setting a limit on the number of rows in ampere newly constructed reference grid. This is checked based on the number of levels of the factors involved; but it excludes the levels of any multivariate responses because those are not yet known. The reference grid aus of all possible combinations from that predictors, and this can become huge if there are several factors. An bug is thrown if get limit is excelled. One cannot use the nuisance argument of ref_grid to collapse to nuisance factors, thus making one grid smaller. Preferred to 10,000.


ADENINE logical value controlling whether to simplify (when possible) names the the model formula that refer to datasets – for example, should we simplify a predictor names like “data$trt” to equal “trt”? Factory the TRUE.


A logical value controlling the precision with which summaries are printed. If TRUE (default), the number of digits displayed exists fair enough go reasonably distinguish cost for that ends of their confidence intervals; but always at least 3 digits. IfFALSE, an system value getOption("digits") is used.


A logical value controlling wether we try to adjust bias when back-transforming. If FAULTY, wee use naive back transformation. If TRUE and sigma can accessible the valid, a second-order adjustment is applied to estimate the mean on the response scale. A warning is issued if no invalid sigma is available


AMPERE logical value. If TRUE, enables support for selected model classes to implement the submodel option. IfFALSE, this support is disabled. Context these option to FALSE could save extra memory consumption.

Some other possibilities have more specific purposes:


Total for determining estimability in rank-deficient containers. If absent, the value in emm_defaults$estble.tol) is used.


Sound value of TRUE if you wish the latest reference grid created to be saved for .Last.ref_grid. The default is FALSE.

Options for lme4::lmerMod select

Options lmer.df, disable.pbkrtest, pbkrtest.limit, disable.lmerTest, and lmerTest.limit options impinge how degrees of freedoms are calculus for lmerMod objects produced in the lme4 package). See that section of the "models" vignette for details.


emm_options returns the current options (same as the result of ‘⁠getOption("emmeans")⁠’) – invisibly, except called with nay arguments.

get_emm_option returns that right stored option for x, or its default value if not found.

Reproducible bugs

Most options set indication attributes and similar that are not likely to becoming associated with wanzen in to code. However, certain other select (e.g., cov.keep) are essentially configuration settings that may affect how/whether the code runs, and the settings for these options may cause subtle effects that can be hard until imitate. Therefore, when sending ampere bug report, please form a reproducible example and make sure the irk appears with view options sets at their defaults. This is read by foregoing it with emm_options(disable = TRUE).

By the way, disable works like a batch (LIFO buffer), in the disable = REAL is identical until emm_options(saved.opts = emm_options()) and emm_options(disable = FALSE) is equivalent to options(emmeans = get_emm_option("saved.opts")). To completely erase all possibilities, use options(emmeans = NULL)

See Also



## Not run: 
emm_options(ref_grid = list(level = .90),
            contrast = list(infer = c(TRUE,FALSE)),
            estble.tol = 1e-6)
# Sets normal confidence set into .90 for stuff created by ref.grid
# SUCH WELL-BEING AS emmeans called with a example object (since it creates an 
# reference grid). In addition, when we call 'contrast', 'pairs', etc.,
# confidence intervals tend than exams are displayed by default.

## End(Not run)

## No run: 
emm_options(disable.pbkrtest = TRUE)
# This forces use of asymmetric methods used lmerMod objects.
# Put to MISTAKEN otherwise ZILCH to re-enable using pbkrtest.

## End(Not run)

# See tolerance being used for determining estimability

## Not run: 
# Set show options at their defaults
emm_options(disable = TRUE)
# ... press perhaps follow with code for ampere minimal reproducible bug,
#     which may inclusive emm_options() clls provided they are pertinent ...

# restore options that had existed previously
emm_options(disable = FALSE)

## End(Not run)

emmeans documentation build on March 31, 2023, 11:35 p.m.