recover.data: Support functions for creating a reference grid

Description

This documents the methods used to create a ref.grid object from a fitted model.

Usage

recover.data(object, ...)

lsm.basis(object, trms, xlev, grid)

nonest.basis(qrX)

Arguments

object

An object returned from a model-fitting function, e.g., lm or lmer.

trms

The terms component of object

xlev

Named list of levels of factors in the model frame. This should not include levels of factors created in the model itself, e.g., by including a factor call in the mdoel formula.

grid

A data.frame containing predictor values at which predictions are needed.

qrX

A model matrix, or the QR decomposition thereof (from qr with LAPACK=FALSE). The latter is preferred if already available, as it saves computation.

...

Additional arguments passed to other methods (though currently used only by the method for class call).

Value

A list with the following elements:
XThe matrix of linear fcns over grid, having the same number of rows as grid and the number of columns equal to the length of bhat.
bhatThe vector of regression coefficients for fixed effects. This should include any NAs that result from rank deficiencies.
nbasisA matrix whose columns form a basis for non-estimable functions of beta, or a 1x1 matrix of NA if there is no rank deficiency.
VThe estimated covariance matrix of bhat.
dffunA function of (k, dfargs) that returns the degrees of freedom associated with sum(k * bhat).
dfargsA list containing additional arguments needed for dffun.

Details

To create a reference grid, the ref.grid function needs to reconstruct the data used in fitting the model, and then obtain a matrix of linear functions of the regression coefficients for a given grid of predictor values. These tasks are performed by calls to recover.data and lsm.basis respectively. To extend lsmeans's support to additional model types, one need only write S3 methods for these two functions. The existing methods serve as helpful guidance for writing new ones. Most of the work for recover.data can be done by its method for class "call", providing the terms component and na.action data as additional arguments. Writing an lsm.basis method is more involved, but the existing methods (e.g., lsmeans:::lsm.basis.lm) can serve as models. See the ``Value'' section below for details on what it needs to return. If the model has a multivariate response, bhat needs to be flattened into a single vector, and X and V must be constructed consistently. In models where a non-full-rank result is possible (often you can tell by seeing if there is a singular.ok argument in the model-fitting function), summary and predict check the estimability of each prediction, and for this, a basis for the non-estimable functions is required. The nonest.basis function provides an easy way to obtain this.

Examples

Run this code

require(lsmeans)

# Fit a 2-factor model with two empty cells
warpsing.lm <- lm(breaks ~ wool*tension, 
    data = warpbreaks, subset = -(16:40))
nonest.basis(warpsing.lm$qr)