Description Usage Arguments Details Value Using cov.reduce and cov.keep Interdependent covariates Matrix covariates Recovering or overriding model information Predictors with subscripts and dataset references Prediction types and transformations Side effect Note See Also Examples
Using a fitted model object, determine a reference grid for which estimated
marginal means are defined. The resulting ref_grid
object encapsulates
all the information needed to calculate EMMs and make inferences on them.
1 2 3 4 
object 
An object produced by a supported modelfitting function, such
as 
at 
Optional named list of levels for the corresponding variables 
cov.reduce 
A function, logical value, or formula; or a named list of
these. Each covariate not specified in 
cov.keep 
Character vector: names of covariates that are not
to be reduced; these are treated as factors and used in weighting calculations.

mult.names 
Character value: the name(s) to give to the
pseudofactor(s) whose levels delineate the elements of a multivariate
response. If this is provided, it overrides the default name(s) used for

mult.levs 
A named list of levels for the dimensions of a multivariate
response. If there is more than one element, the combinations of levels are
used, in 
options 
If non 
data 
A 
df 
Numeric value. This is equivalent to specifying 
type 
Character value. If provided, this is saved as the

transform 
Character, logical, or list. If nonmissing, the reference
grid is reconstructed via 
nesting 
If the model has nested fixed effects, this may be specified
here via a character vector or named 
offset 
Numeric scalar value (if a vector, only the first element is
used). This may be used to add an offset, or override offsets based on the
model. A common usage would be to specify 
sigma 
Numeric value to use for subsequent predictions or
backtransformation bias adjustments. If not specified, we use

... 
Optional arguments passed to 
To users, the ref_grid
function itself is important because most of
its arguments are in effect arguments of emmeans
and related
functions, in that those functions pass their ...
arguments to
ref_grid
.
The reference grid consists of combinations of independent variables over
which predictions are made. Estimated marginal means are defined as these
predictions, or marginal averages thereof. The grid is determined by first
reconstructing the data used in fitting the model (see
recover_data
), or by using the data.frame
provided in
data
. The default reference grid is determined by the observed levels
of any factors, the ordered unique values of charactervalued predictors, and
the results of cov.reduce
for numeric predictors. These may be
overridden using at
. See also the section below on
recovering/overriding model information.
An object of the S4 class "emmGrid"
(see
emmGridclass
). These objects encapsulate everything needed
to do calculations and inferences for estimated marginal means, and contain
nothing that depends on the modelfitting procedure.
cov.reduce
and cov.keep
The cov.keep
argument was not available in emmeans versions
1.4.1 and earlier. Any covariates named in this list are treated as if they
are factors: all the unique levels are kept in the reference grid. The user
may also specify an integer value, in which case any covariate having no more
than that number of unique values is implicitly included in cov.keep
.
The default for cove.keep
is set and retrieved via the
emm_options
framework, and the system default is "2"
,
meaning that covariates having only two unique values are automatically
treated as twolevel factors. See also the Note below on backward compatibility.
There is a subtle distinction between including a covariate in cov.keep
and specifying its values manually in at
: Covariates included in
cov.keep
are treated as factors for purposes of weighting, while
specifying levels in at
will not include the covariate in weighting.
See the mtcars.lm
example below for an illustration.
cov.reduce
may be a function,
logical value, formula, or a named list of these.
If a single function, it is applied to each covariate.
If logical and TRUE
, mean
is used. If logical and
FALSE
, it is equivalent to including all covariates in
cov.keep
. Use of cov.reduce = FALSE is inadvisable because it
can result in a huge reference grid; it is far better to use
cov.keep
.
If a formula (which must be twosided), then a model is fitted to that
formula using lm
; then in the reference grid, its response
variable is set to the results of predict
for that model,
with the reference grid as newdata
. (This is done after the
reference grid is determined.) A formula is appropriate here when you think
experimental conditions affect the covariate as well as the response.
If cov.reduce
is a named list, then the above criteria are used to
determine what to do with covariates named in the list. (However, formula
elements do not need to be named, as those names are determined from the
formulas' lefthand sides.) Any unresolved covariates are reduced using
"mean"
.
Any cov.reduce
of cov.keep
specification for a covariate
also named in at
is ignored.
Care must be taken when covariate values
depend on one another. For example, when a polynomial model was fitted
using predictors x
, x2
(equal to x^2
), and x3
(equal to x^3
), the reference grid will by default set x2
and
x3
to their means, which is inconsistent. The user should instead
use the at
argument to set these to the square and cube of
mean(x)
. Better yet, fit the model using a formula involving
poly(x, 3)
or I(x^2)
and I(x^3)
; then there is only
x
appearing as a covariate; it will be set to its mean, and the
model matrix will have the correct corresponding quadratic and cubic terms.
Support for covariates that appear in the dataset
as matrices is very limited. If the matrix has but one column, it is
treated like an ordinary covariate. Otherwise, with more than one column,
each column is reduced to a single reference value – the result of
applying cov.reduce
to each column (averaged together if that
produces more than one value); you may not specify values in at
; and
they are not treated as variables in the reference grid, except for
purposes of obtaining predictions.
Ability to support a
particular class of object
depends on the existence of
recover_data
and emm_basis
methods – see
extendingemmeans for details. The call
methods("recover_data")
will help identify these.
Data. In certain models, (e.g., results of
glmer.nb
), it is not possible to identify the original
dataset. In such cases, we can work around this by setting data
equal to the dataset used in fitting the model, or a suitable subset. Only
the complete cases in data
are used, so it may be necessary to
exclude some unused variables. Using data
can also help save
computing, especially when the dataset is large. In any case, data
must represent all factor levels used in fitting the model. It
cannot be used as an alternative to at
. (Note: If there is a
pattern of NAs
that caused one or more factor levels to be excluded
when fitting the model, then data
should also exclude those levels.)
Covariance matrix. By default, the variancecovariance matrix for
the fixed effects is obtained from object
, usually via its
vcov
method. However, the user may override this via a
vcov.
argument, specifying a matrix or a function. If a matrix, it
must be square and of the same dimension and parameter order of the fixed
effects. If a function, must return a suitable matrix when it is called
with object
as its only argument.
Nested factors. Having a nesting structure affects marginal
averaging in emmeans
in that it is done separately for each level
(or combination thereof) of the grouping factors. ref_grid
tries to
discern which factors are nested in other factors, but it is not always
obvious, and if it misses some, the user must specify this structure via
nesting
; or later using update.emmGrid
. The
nesting
argument may be a character vector, a named list
,
or NULL
.
If a list
, each name should be the name of a single factor in the
grid, and its entry a character vector of the name(s) of its grouping
factor(s). nested
may also be a character value of the form
"factor1 %in% (factor2*factor3)"
(the parentheses are optional).
If there is more than one such specification, they may be appended
separated by commas, or as separate elements of a character vector. For
example, these specifications are equivalent: nesting = list(state =
"country", city = c("state", "country")
, nesting = "state %in%
country, city %in% (state*country)"
, and nesting = c("state %in%
country", "city %in% state*country")
.
When the fitted
model contains subscripts or explicit references to data sets, the
reference grid may optionally be postprocessed to simplify the variable
names, depending on the simplify.names
option (see
emm_options
), which by default is TRUE
. For example,
if the model formula is data1$resp ~ data1$trt + data2[[3]] +
data2[["cov"]]
, the simplified predictor names (for use, e.g., in the
specs
for emmeans
) will be trt
,
data2[[3]]
, and cov
. Numerical subscripts are not simplified;
nor are variables having simplified names that coincide, such as if
data2$trt
were also in the model.
Please note that this simplification is performed after the
reference grid is constructed. Thus, nonsimplified names must be used in
the at
argument (e.g., at = list(`data2["cov"]` = 2:4)
.
If you don't want names simplified, use emm_options(simplify.names =
FALSE)
.
Transformations can exist because of a link function in a generalized linear model,
or as a response transformation, or even both. In many cases, they are autodetected,
for example a model formula of the form sqrt(y) ~ ...
. Even transformations
containing multiplicative or additive constants, such as 2*sqrt(y + pi) ~ ...
,
are autodetected. A response transformation of y + 1 ~ ...
is not
autodetected, but I(y + 1) ~ ...
is interpreted as identity(y + 1) ~ ...
.
A warning is issued if it gets too complicated.
Complex transformations like the BoxCox transformation are not autodetected; but see
the help page for make.tran
for information on some advanced methods.
There is a subtle difference
between specifying type = "response" and transform =
"response". While the summary statistics for the grid itself are the same,
subsequent use in emmeans
will yield different results if
there is a response transformation or link function. With type =
"response", EMMs are computed by averaging together predictions on the
linearpredictor scale and then backtransforming to the response
scale; while with transform = "response", the predictions are
already on the response scale so that the EMMs will be the arithmetic means
of those responsescale predictions. To add further to the possibilities,
geometric means of the responsescale predictions are obtainable via
transform = "log", type = "response". See also the help page for
regrid
.
The most recent result of ref_grid
, whether
called directly or indirectly via emmeans
,
emtrends
, or some other function that calls one of these, is
saved in the user's environment as .Last.ref_grid
. This facilitates
checking what reference grid was used, or reusing the same reference grid
for further calculations. This automatic saving is enabled by default, but
may be disabled via emm_options(save.ref_grid = FALSE), and
reenabled by specifying TRUE
.
The system default for cov.keep
causes models
containing indicator variables to be handled differently than in
emmeans version 1.4.1 or earlier. To replicate older
analyses, change the default via
emm_options(cov.keep = character(0)).
Some earlier versions of emmeans offer a covnest
argument.
This is now obsolete; if covnest
is specified, it is harmlessly
ignored. Cases where it was needed are now handled appropriately via the
code associated with cov.keep
.
Reference grids are of class emmGrid
,
and several methods exist for them – for example
summary.emmGrid
. Reference grids are fundamental to
emmeans
. Supported models are detailed in
vignette("models", "emmeans")
.
See update.emmGrid
for details of arguments that can be in
options
(or in ...
).
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39  fiber.lm < lm(strength ~ machine*diameter, data = fiber)
ref_grid(fiber.lm)
summary(.Last.ref_grid)
ref_grid(fiber.lm, at = list(diameter = c(15, 25)))
## Not run:
# We could substitute the sandwich estimator vcovHAC(fiber.lm)
# as follows:
summary(ref_grid(fiber.lm, vcov. = sandwich::vcovHAC))
## End(Not run)
# If we thought that the machines affect the diameters
# (admittedly not plausible in this example), then we should use:
ref_grid(fiber.lm, cov.reduce = diameter ~ machine)
### Model with indicator variables as predictors:
mtcars.lm < lm(mpg ~ disp + wt + vs * am, data = mtcars)
(rg.default < ref_grid(mtcars.lm))
(rg.nokeep < ref_grid(mtcars.lm, cov.keep = character(0)))
(rg.at < ref_grid(mtcars.lm, at = list(vs = 0:1, am = 0:1)))
# Two of these have the same grid but different weights:
rg.default@grid
rg.at@grid
# Multivariate example
MOats.lm = lm(yield ~ Block + Variety, data = MOats)
ref_grid(MOats.lm, mult.names = "nitro")
# Silly illustration of how to use 'mult.levs' to make comb's of two factors
ref_grid(MOats.lm, mult.levs = list(T=LETTERS[1:2], U=letters[1:2]))
# Using 'params'
require("splines")
my.knots = c(2.5, 3, 3.5)
mod = lm(Sepal.Length ~ Species * ns(Sepal.Width, knots = my.knots), data = iris)
## my.knots is not a predictor, so need to name it in 'params'
ref_grid(mod, params = "my.knots")

Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.