emmeans (version 1.0)

update.emmGrid: Set or retrieve options for objects and summaries

Description

Objects of class emmGrid contain several settings that affect primarily the defaults used by summary.emmGrid. This update method allows them to be changed more safely than by modifying this slot directly. In addition, the user may set or retrieve defaults for these settings.

Usage

# S3 method for emmGrid
update(object, ..., silent = FALSE)
emm_options(...)
get_emm_option(x, default = emm_defaults[[x]])
emm_defaults

Arguments

object

An emmGrid object

...

Options to be set. These must match a list of known options (see Details)

silent

Logical value. If FALSE (the default), a message is displayed if any options are not matched. If TRUE, no messages are shown.

x

Character value - the name of an option to be queried

default

Value to return if x is not found

Value

update.emmGrid returns an updated emmGrid object.

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

Details for <code>update.emmGrid</code>

In update, the names in … are partially matched against those that are valid, and if a match is found, it adds or replaces the current setting. The valid names are

tran, tran2

(list or character) specifies the transformation which, when inverted, determines the results displayed by summary.emmGrid, predict.emmGrid, or emmip when type="response". The value may be the name of a standard transformation from make.link or additional ones supported by name, such as "log2"; or, for a custom transformation, a list containing at least the functions linkinv (the inverse of the transformation) and mu.eta (the derivative thereof). The make.tran function returns such lists for a number of popular transformations. See the help page of make.tran for details as well as information on the additional named transformations that are supported. tran2 is just like tran except it is a second transformation (i.e., a response transformation in a generalized linear model).

tran.mult

Multiple for tran. For example, for the response transformation 2*sqrt(y) (or sqrt(y) + sqrt(y + 1), for that matter), we should have tran = "sqrt" and tran.mult = 2. If absent, a multiple of 1 is assumed.

estName

(character) is the column label used for displaying predictions or EMMs.

inv.lbl

(character)) is the column label to use for predictions or EMMs when type="response".

by.vars

(character) vector or NULL) the variables used for grouping in the summary, and also for defining subfamilies in a call to contrast.

pri.vars

(character vector) are the names of the grid variables that are not in by.vars. Thus, the combinations of their levels are used as columns in each table produced by summary.emmGrid.

alpha

(numeric) is the default significance level for tests, in summary.emmGrid as well as cld.emmGrid and plot.emmGrid when intervals = TRUE

adjust

(character)) is the default for the adjust argument in summary.emmGrid.

estType

(character) is the type of the estimate. It should match one of c("prediction", "contrast", "pairs"). This is used along with "adjust" to determine appropriate adjustments to P values and confidence intervals.

famSize

(integer) is the nmeans parameter for ptukey when adjust="tukey".

infer

(logical vector of length 2) is the default value of infer in summary.emmGrid.

level

(numeric) is the default confidence level, level, in summary.emmGrid

df

(numeric) overrides the default degrees of freedom with a specified single value.

null

(numeric) null hypothesis for summary or test (taken to be zero if missing).

side

(numeric or character) side specification for for summary or test (taken to be zero if missing).

delta

(numeric) delta specification for summary or test (taken to be zero if missing).

predict.type or type

(character) sets the default method of displaying predictions in summary.emmGrid, predict.emmGrid, and emmip. Valid values are "link" (with synonyms "lp" and "linear"), or "response".

avgd.over

(character) vector) are the names of the variables whose levels are averaged over in obtaining marginal averages of predictions, i.e., estimated marginal means. Changing this might produce a misleading printout, but setting it to character(0) will suppress the “averaged over” message in the summary.

initMesg

(character) is a string that is added to the beginning of any annotations that appear below the summary.emmGrid display.

methDesc

(character) is a string that may be used for creating names for a list of emmGrid objects.

nesting

(Character or named list) specifies the nesting structure. See “Recovering or overriding model information” in the documentation for ref_grid. The current nesting structure is displayed by str.emmGrid.

(any slot name)

If the name matches an element of slotNames(object), that slot is replaced by the supplied value, if it is of the required class (otherwise an error occurs). Note that other options above are saved in the misc slot; hence, you probably don't want to replace that slot. The user must be very careful in replacing slots because they are interrelated; for example, the levels and grid slots must involve the same variable names, and the lengths and dimensions of grid, linfct, bhat, and V must conform.

Using <code>emm_options</code>

In emm_options, we may set or change the default values for the above options. These defaults are set separately for different contexts in which emmGrid objects are created, in a named list of option lists. 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".

% \item{\code{msg.data.call}}{Logical value controlling whether or not % a warning is displayed when a model's \code{data} or \code{subset} % component contains a call. This can be hazardous; for example, if a model % call contains something like \code{subset = sample(...)}, then that same % call to \code{sample} will be run again when the reference grid is % constructed -- but it will be a different subset! This will definitely % affect the covariate settings, and may even affect the factor levels. % Defaults to \code{TRUE}.}

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.

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.

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

Examples

# NOT RUN {
# Using an already-transformed response:
mypigs <- transform(pigs, logconc = log(pigs$conc))
mypigs.lm <- lm(logconc ~ source + factor(percent), data = mypigs)

# Reference grid that knows about the transformation:
mypigs.rg <- update(ref_grid(mypigs.lm), tran = "log", 
                    predict.type = "response")
emmeans(mypigs.rg, "source")
# }
# 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")

# }