lsmeans (version 2.19)

ref.grid: Create a reference grid from a fitted model

Description

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.

Usage

ref.grid(object, at, cov.reduce = mean, mult.name, mult.levs, 
    options = lsm.options()$ref.grid, data, type, ...)

Arguments

object

An object produced by a supported model-fitting function, such as lm. Many models are supported. See models.

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 at is reduced according to these specifications. If a single function, it is applied to each covariate. If logical and <

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., "rep.meas" for an mlm

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 expand.grid order. The (total) number of levels must matc

options

If non-NULL, a named list of arguments to pass to update, just after the object is constructed.

data

A data.frame to use to obtain information about the predictors (e.g. factor levels). If missing, then recover.data is used to attempt to reconstruct the data.

type

If provided, this is saved as the "predict.type" setting. See update

...

Optional arguments passed to lsm.basis, such as vcov. (see Details below) or options for certain models (see models).

Value

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

Details

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.

See Also

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.

Examples

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)))

# We could substitute the sandwich estimator vcovHAC(fiber.lm)
# as follows:
require(sandwich)
summary(ref.grid(fiber.lm, vcov. = vcovHAC))

# 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]))