Description

Use emm_options to set or change various options that are used in the emmeans package. These options are set separately for different contexts in which emmGrid objects are created, in a named list of option lists.

Usage

Arguments

Format

An object of class list of length 20.

Details

emmeans's options are stored as a list in the system option "emmeans". Thus, emm_options(foo = bar) is the same as options(emmeans = list(..., foo = bar)) where ... represents any previously existing options. The list emm_defaults contains the default values in case the corresponding element of system option emmeans is NULL.

Currently, the following main list entries are supported:

ref_grid

A named list of defaults for objects created by ref_grid. This could affect other objects as well. For example, if emmeans is called with a fitted model object, it calls ref_grid and this option will affect the resulting emmGrid object.

emmeans

A named list of defaults for objects created by emmeans or emtrends.

contrast

A named list of defaults for objects created by contrast.emmGrid or pairs.emmGrid.

summary

A named list of defaults used by the methods summary.emmGrid, predict.emmGrid, test.emmGrid, confint.emmGrid, and emmip. The only option that can affect the latter four is "predict.method".

sep

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

parens

Character vector that determines which labels are parenthesized when they are contrasted. The first element is a regular expression, and the second and third elements are used as left and right parentheses. See details for the parens argument in contrast. The default will parenthesize labels containing the four arithmetic operators, using round parentheses.

cov.keep

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

graphics.engine

A character value matching c("ggplot", "lattice"), setting the default engine to use in emmip and plot.emmGrid. Defaults to "ggplot".

msg.interaction

A logical value controlling whether or not a message is displayed when emmeans averages over a factor involved in an interaction. It is probably not appropriate to do this, unless the interaction is weak. Defaults to TRUE.

msg.nesting

A logical value controlling whether or not to display a message when a nesting structure is auto-detected. The existence of such a structure affects computations of EMMs. Sometimes, a nesting structure is falsely detected – namely when a user has omitted some main effects but included them in interactions. This does not change the model fit, but it produces a different parameterization that is picked up when the reference grid is constructed. Defaults to TRUE.

simplify.names

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

opt.digits

A logical value controlling the precision with which summaries are printed. If TRUE (default), the number of digits displayed is just enough to reasonably distinguish estimates from the ends of their confidence intervals; but always at least 3 digits. If FALSE, the system value getOption("digits") is used.

back.bias.adj

A logical value controlling whether we try to adjust bias when back-transforming. If FALSE, we use naive back transformation. If TRUE and sigma is available, a second-order adjustment is applied to estimate the mean on the response scale.

enable.submodel

A logical value. If TRUE, enables support for selected model classes to implement the submodel option. If FALSE, this support is disabled. Setting this option to FALSE could save excess memory consumption.

Some other options have more specific purposes:

estble.tol

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

save.ref_grid

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

Options for lme4::lmerMod models

Options lmer.df, disable.pbkrtest, pbkrtest.limit, disable.lmerTest, and lmerTest.limit options affect how degrees of freedom are computed for lmerMod objects produced by the lme4 package). See that section of the "models" vignette for details.

Value

emm_options returns the current options (same as the result of getOption("emmeans")) – invisibly, unless called with no arguments.

get_emm_option returns the currently stored option for x, or its default value if not found.

Reproducible bugs

Most options set display attributes and such that are not likely to be associated with bugs in the code. However, some other options (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 may be hard to reproduce. Therefore, when sending a bug report, please create a reproducible example and make sure the bug occurs with all options set at their defaults. This is done by preceding it with emm_options(disable = TRUE).

By the way, disable works like a stack (LIFO buffer), in that disable = TRUE is equivalent to 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 options, use options(emmeans = NULL)

See Also

update.emmGrid

Examples