This documents the methods used to create a ref.grid
object from a fitted model.
recover.data(object, ...)
# S3 method for call
recover.data(object, trms, na.action,
data = NULL, params = NULL, ...)lsm.basis(object, trms, xlev, grid, ...)
An object returned from a model-fitting function.
The terms
component of object
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 model formula.
A data.frame
containing predictor values at which predictions are needed.
Integer vector of indices of observations to ignore; or NULL
if none
Data frame. Usually, this is NULL
. However, if non-null, this is used in place of the reconstructed dataset. It must have all of the predictors used in the model, and any factor levels must match those used in fitting the model.
Character vector giving the names of any variables in the
model formula that are not predictors. An example would be a
variable knots
specifying the knots to use in a spline model.
Additional arguments passed to other methods.
recover.data
should return a data.frame
containing all the variables in the original data that appear as predictors in the model. Several attributes need to be included as well; see the code for lsmeans:::recover.data.lm
.
lsm.basis
should return a list
with the following elements:
The matrix of linear functions over grid
, having the same number of rows as grid
and the number of columns equal to the length of bhat
.
The vector of regression coefficients for fixed effects. This should include any NA
s that result from rank deficiencies.
A matrix whose columns form a basis for non-estimable functions of beta, or a 1x1 matrix of NA
if there is no rank deficiency.
The estimated covariance matrix of bhat
.
A function of (k, dfargs)
that returns the degrees of freedom associated with sum(k * bhat)
.
A list
containing additional arguments needed for dffun
.
%%%\code{.all.vars} is an enhancement of \code{\link{all.vars}}, whereby the operators specified in \code{retain} are left intact. Thus, \code{All.vars(foo$y ~ bar[[2]])} returns \code{"foo$y", "bar[[2]]"}, whereas \code{all.vars} returns \code{"foo", "y", "bar"}
Some models may need something other than standard linear estimates and standard errors. If so, custom functions may be pointed to via the items misc$estHook
, misc$vcovHook
and misc$postGridHook
. If just the name of the hook function is provided as a character string, then it is retrieved using get
.
The estHook
function should have arguments (object, do.se, tol, ...) where object
is the ref.grid
or lsmobj
object, do.se
is a logical flag for whether to return the standard error, and tol
is the tolerance for assessing estimability. It should return a matrix with 3 columns: the estimates, standard errors (NA
when do.se==FALSE
), and degrees of freedom (NA
for asymptotic). The number of rows should be the same as object@linfct. The vcovHook
function should have arguments (object, tol, ...) as described. It should return the covariance matrix for the estimates. Finally, postGridHook
, if present, is called at the very end of ref.grid
; it takes one argument, the constructed object
, and should return a suitably modifiedref.grid
object.
A few additional functions used in the lsmeans codebase are exported as they may be useful to package developers. See details near the end of the vignette "extending"
.
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. Also, certain recover.data
and lsm.basis
methods are exported from lsmeans, so if your object is based on another model-fitting object, it may be that all that is needed is to call one of these exported methods and perhaps make modifications to the results. Contact the developer if you need others of these exported.
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, using the nonest.basis
function in the estimability package.
The models already supported are detailed in models
. Some packages may provide additional lsmeans support for its object classes.
# NOT RUN {
require(lsmeans)
# Fit a 2-factor model with two empty cells
warpsing.lm <- lm(breaks ~ wool*tension,
data = warpbreaks, subset = -(16:40))
lsmeans:::recover.data.lm(warpsing.lm, data = NULL)
grid = with(warpbreaks,
expand.grid(wool = levels(wool), tension = levels(tension)))
lsmeans:::lsm.basis.lm(warpsing.lm, delete.response(terms(warpsing.lm)),
warpsing.lm$xlevels, grid)
# }
# NOT RUN {
# }
# NOT RUN {
<!-- % end dontrun -->
# }
# NOT RUN {
# }
Run the code above in your browser using DataLab