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.
# S3 method for emmGrid
update(object, ..., silent = FALSE)emm_options(...)
get_emm_option(x, default = emm_defaults[[x]])
emm_defaults
An emmGrid object
Options to be set. These must match a list of known options (see Details)
Logical value. If FALSE (the default), a message is
displayed if any options are not matched. If TRUE, no messages are
shown.
Character value - the name of an option to be queried
Value to return if x is not found
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.
An object of class list of length 13.
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.multMultiple 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.
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.
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_gridA 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.
emmeansA named list of defaults for objects created by
emmeans or emtrends.
contrastA named list of defaults for objects created by
contrast.emmGrid or pairs.emmGrid.
summaryA 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.engineA character value matching
c("ggplot", "lattice"), setting the default engine to use in
emmip and plot.emmGrid. Defaults to "ggplot".
msg.interactionA 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.nestingA 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.tolTolerance for determining estimability in
rank-deficient cases. If absent, the value in emm_defaults$estble.tol)
is used.
save.ref_gridLogical value of TRUE if you wish the
latest reference grid created to be saved in .Last.ref_grid
lme4::lmerMod modelsOptions 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.
# 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")
# }
Run the code above in your browser using DataLab