emmeans (version 1.3.2)

emm_options: Set or change emmeans options

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

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

Arguments

...

Option names and values (see Details)

x

Character value - the name of an option to be queried

default

Value to return if x is not found

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.

Format

An object of class list of length 15.

Details

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

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.

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

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.

See Also

update.emmGrid

Examples

# NOT RUN {
emm_options(ref_grid = list(level = .90),
            contrast = list(infer = c(TRUE,FALSE)),
            estble.tol = 1e-6)
# Sets default confidence level to .90 for objects created by ref.grid
# AS WELL AS emmeans called with a model object (since it creates a 
# reference grid). In addition, when we call 'contrast', 'pairs', etc.,
# confidence intervals rather than tests are displayed by default.
# }
# NOT RUN {
# }
# NOT RUN {
emm_options(disable.pbkrtest = TRUE)
# This forces use of asymptotic methods for lmerMod objects.
# Set to FALSE or NULL to re-enable using pbkrtest.
# }
# NOT RUN {
# See tolerance being used for determining estimability
get_emm_option("estble.tol")

# }