update: Set or retrieve options for objects and summaries in lsmeans

Description

Objects of class ref.grid or lsmobj contain several settings in their "misc" slot that affect primarily the defaults used by summary. This update method allows them to be changed more safely than by modifying this slot directly.

In addition, the user may set defaults for all objects using options(lsmeans = ...), or more conveniently using the lsm.options and get.lsm.option functions documented here (or its courtesy wrappers, pmm.options and get.pmm.option for those who dislike the ‘least-squares means’ terminology).

Usage

"update"(object, ..., silent = FALSE)
lsm.options(...)
get.lsm.option(x, default = defaults.lsm[[x]])
pmm.options(...)
get.pmm.option(...)

Arguments

object

An object of class ref.grid (or its extension, lsmobj)

...

Arguments specifying elements' names and their new values.

silent

If FALSE, a message is displayed for any unmatched names.

Character string holding an option name for lsm.options.

default

Return value if x is not found.

Value

update returns a copy of object with its "misc" slot modified (and perhaps other slots). lsm.options returns the current options (same as the result of getOption("lsmeans")).

Details

Using update In update, the names in ... are partially matched against those that are valid, and if a match is found, it adds or replaces the current setting. The valid names are

tran: (list or character) specifies the transformation which, when inverted, determines the results displayed by summary, predict, or lsmip when type="response". The value may be the name of a standard transformation from make.link or additional ones supported by name, such as log2; or, for a custom transformation, a list containing at least the functions linkinv (the inverse of the transformation) and mu.eta (the derivative thereof). The make.tran function returns such lists for a number of popular transformations. See the help page of make.tran for details as well as information on the additional named transformations that are supported.

tran.mult

Multiple for tran. For example, for the response transformation 2*sqrt(y) (or sqrt(y) + sqrt(y + 1), for that matter), we should have tran = "sqrt" and tran.mult = 2. If absent, a multiple of 1 is assumed.

estName

(character) is the column label used for displaying predictions or LS means.

inv.lbl

(character)) is the column label to use for predictions or LS means when type="response".

by.vars

(character) vector or NULL) the variables used for grouping in the summary, and also for defining subfamilies in a call to contrast.

pri.vars

(character vector) are the names of the grid variables that are not in by.vars. Thus, the combinations of their levels are used as columns in each table produced by summary.

alpha

(numeric) is the default significance level for tests, in summary as well as cld and plot when intervals = TRUE

adjust

(character)) is the default for the adjust argument in summary.

estType

(character) is the type of the estimate. It should match one of c("prediction","contrast","pairs"). This is used along with "adjust" to determine appropriate adjustments to P values and confidence intervals.

famSize

(integer) is the nmeans parameter for ptukey when adjust="tukey".

infer

(logical vector of length 2) is the default value of infer in summary.

level

(numeric) is the default confidence level, level, in summary

df

(numeric) overrides the default degrees of freedom with a specified single value.

null

(numeric) null hypothesis for summary or test (taken to be zero if missing).

side

(numeric or character) side specification for for summary or test (taken to be zero if missing).

delta

(numeric) delta specification for summary or test (taken to be zero if missing).

predict.type

(character) sets the default method of displaying predictions in summary, predict, and lsmip. Valid values are "link" (with synonyms "lp" and "linear"), or "response".

avgd.over

(character) vector) are the names of the variables whose levels are averaged over in obtaining marginal averages of predictions, i.e., LS means. Changing this might produce a misleading printout, but setting it to character(0) will suppress the “averaged over” message in the summary.

initMesg

(character) is a string that is added to the beginning of any annotations that appear below the summary display.

methDesc

(character) is a string that may be used for creating names for a list of lsmobj objects.

(any slot name)

If the name matches an element of slotNames(object), that slot is replaced by the supplied value, if it is of the required class (otherwise an error occurs). Note that all the other possibilities above refer to elements of misc; hence, you probably don't want to replace misc itself. The user must be very careful in replacing slots because they are interrelated; for example, the levels and grid slots must involve the same variable names, and the lengths and dimensions of grid, linfct, bhat, and V must conform.

Using lsm.options In lsm.options, we may set or change the default values for the above attributes in the lsmeans option list(see options). Currently, the following elements of this list are used if specified:

ref.grid: A named list of defaults for objects created by ref.grid. This could affect other objects as well. For example, if lsmeans is called with a fitted model object, it calls ref.grid and this option will affect the resulting lsmobj object.

lsmeans

A named list of defaults for objects created by lsmeans (or lstrends).

contrast

A named list of defaults for objects created by contrast (or pairs).

summary

A named list of defaults used by the methods summary, predict, and lsmip. The only option that can affect the latter two is "predict.method".

estble.tol

Tolerance for determining estimability in rank-deficient cases. If absent, the value in defaults.lsm$estble.tol) is used.

(others)

Other options may be accessed by support code for particular model classes (see models). For example, the disable.pbkrtest and pbkrtest.limit options affect whether approximate degrees of freedom are computed for lmerMod objects (lme4 package).

Examples

Run this code

# An altered log transformation

warp.lm1 <- lm(log(breaks + 1) ~ wool*tension, data = warpbreaks)
rg1 <- update(ref.grid(warp.lm1), 
        tran = list(linkinv = function(eta) exp(eta) - 1,
                    mu.eta = function(eta) exp(eta)),
        inv.lbl = "pred.breaks")
        
summary(rg1, type = "response")

## Not run: 
# lsm.options(ref.grid = list(level = .90),
#             contrast = list(infer = c(TRUE,FALSE)),
#             estble.tol = 1e-6)
# # Sets default confidence level to .90 for objects created by ref.grid
# # AS WELL AS lsmeans called with a model object (since it creates a 
# # reference grid). In addition, when we call 'contrast', 'pairs', etc.,
# # confidence intervals rather than tests are displayed by default.
# ## End(Not run)

## Not run: 
# lsm.options(disable.pbkrtest = TRUE)
# # This forces use of asymptotic methods for lmerMod objects.
# # Set to FALSE or NULL to re-enable using pbkrtest.
# ## End(Not run)

# See tolerance being used for determining estimability
get.lsm.option("estble.tol")