ref.grid {lsmeans} | R Documentation |
Using a fitted model object, determine a reference grid for which least-squares means are defined. The resulting ref.grid
object encapsulates all the information needed to calculate LS means and make inferences on them.
ref.grid(object, at, cov.reduce = mean, mult.name, mult.levs, options = get.lsm.option("ref.grid"), data, type, ...) .Last.ref.grid
object |
An object produced by a supported model-fitting 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 If a single function, it is applied to each covariate. If logical and If a formula (which must be two-sided), then a model is fitted to that formula using If Any |
mult.name |
Character, the name to give to the “factor” whose levels delineate the elements of a multivariate response. If this is provided, it overrides the default name, e.g., |
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 |
type |
If provided, this is saved as the |
... |
Optional arguments passed to |
The reference grid consists of combinations of independent variables over which predictions are made. Least-squares 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 context
. The default reference grid is determined by the observed levels of any factors, the ordered unique values of character-valued predictors, and the results of cov.reduce
for numeric predictors. These may be overridden using at
.
Ability to support a particular class of object
depends on the existence of recover.data
and lsm.basis
methods – see extending-lsmeans for details. The call methods("recover.data")
will help identify these.
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.)
By default, the variance-covariance 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 efefcts. If a function, must return a suitable matrix when it is called with object
as its only argument.
The most recent result of ref.grid
, whether called directly or indirectly via lsmeans
, lstrends
, 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 lsm.options(save.ref.grid = FALSE), and re-enabled by specifying TRUE
.
An S4 object of class "ref.grid"
(see ref.grid-class
). These objects encapsulate everything needed to do calculations and inferences for least-squares means, and contain nothing that depends on the model-fitting procedure. As a side effect, the result is also saved as .Last.ref.grid
(in the global environment, unless this variable is found in another position).
Russell V. Lenth
See also summary
and other methods for the returned objects. Reference grids are fundamental to lsmeans
. Click here for more on the ref.grid
class. Supported models are detailed in models
.
require(lsmeans) fiber.lm <- lm(strength ~ machine*diameter, data = fiber) ref.grid(fiber.lm) summary(ref.grid(fiber.lm)) ref.grid(fiber.lm, at = list(diameter = c(15, 25))) ## Not run: # We could substitute the sandwich estimator vcovHAC(fiber.lm) # as follows: require(sandwich) summary(ref.grid(fiber.lm, vcov. = 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) # Multivariate example MOats.lm = lm(yield ~ Block + Variety, data = MOats) ref.grid(MOats.lm, mult.name = "nitro") # silly illustration of how to use 'mult.levs' ref.grid(MOats.lm, mult.levs = list(T=LETTERS[1:2], U=letters[1:2]))