R: Set or retrieve options for objects and summaries in...

update {lsmeans} | R Documentation

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

    ## S3 method for class 'ref.grid'
    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.
`x` | Character string holding an option name for `lsm.options`.
`default` | Return value if `x` is not found.

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

`nesting`

  (named `list`) specifies the nesting structure. The names are those of nested factors, and the elements are character vectors of the factors they are nested in. See the `nesting` argument and Details section of `ref.grid`. The current nesting structure is displayed by `link{str}`.

`tran`, `tran2`

  (`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. `tran2` is just like `tran` except it is a second transformation (i.e., a response transformation in a generalized linear model).

`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 `lmer.df`, `disable.pbkrtest`, and `pbkrtest.limit` options affect how degrees of freedom are computed for `lmerMod` objects (lme4 package).

### 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")) – invisibly, unless called with no arguments.

### Note

If a call to `lsmeans`, `contrast`, or `ref.grid` contains a non-`NULL` `options` list, those options are passed in a call to `update` on the constructed object before it is returned. This allows you, for example, to override the defaults used by `summary`. In addition, user defaults may be set using an `link{options}` setting for `"lsmeans"`. It should be a list with one or more named elements `lsmeans`, `contrast`, or `ref.grid`, used for setting the defaults for objects constructed by functions of these same names. Note that options can get “inherited”. See the examples.

Unlike the `update` method for model classes (`lm`, `glm`, etc.), this does not re-fit or re-estimate anything; but it does affect how `object` is treated by other methods for its class.

### Author(s)

Russell V. Lenth

### See Also

`summary`, `make.tran`

### Examples

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

[Package lsmeans version 2.27-62 Index]