R: Set or retrieve options for objects and summaries

update.emmGrid {emmeans} | R Documentation

## Set or retrieve options for objects and summaries

### Description

Objects of class `emmGrid` contain several settings that affect primarily the defaults used by `summary.emmGrid`. This `update` method allows them to be changed more safely than by modifying this slot directly. In addition, the user may set or retrieve defaults for these settings.

### Usage

    ## S3 method for class 'emmGrid'
    update(object, ..., silent = FALSE)

    emm_options(...)

    get_emm_option(x, default = emm_defaults[[x]])

    emm_defaults

### Arguments

`object` | An `emmGrid` object
`...` | Options to be set. These must match a list of known options (see Details)
`silent` | Logical value. If `FALSE` (the default), a message is displayed if any options are not matched. If `TRUE`, no messages are shown.
`x` | Character value - the name of an option to be queried
`default` | Value to return if `x` is not found

### Format

An object of class `list` of length 13.

### Value

`update.emmGrid` returns an updated `emmGrid` object.

`emm_options` returns the current options (same as the result of getOption("emmeans")) – invisibly, unless called with no arguments.

`get_emm_option` returns the currently stored option for `x`, or its default value if not found.

### Details for `update.emmGrid`

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`, `tran2`

  (`list` or `character`) specifies the transformation which, when inverted, determines the results displayed by `summary.emmGrid`, `predict.emmGrid`, or `emmip` 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 EMMs.

`inv.lbl`

  (`character)`) is the column label to use for predictions or EMMs 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.emmGrid`.

`alpha`

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

`adjust`

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

`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.emmGrid`.

`level`

  (numeric) is the default confidence level, `level`, in `summary.emmGrid`

`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` or `type`

  (character) sets the default method of displaying predictions in `summary.emmGrid`, `predict.emmGrid`, and `emmip`. 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., estimated marginal 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.emmGrid` display.

`methDesc`

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

`nesting`

  (Character or named `list`) specifies the nesting structure. See “Recovering or overriding model information” in the documentation for `ref_grid`. The current nesting structure is displayed by `str.emmGrid`.

(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 other options above are saved in the `misc` slot; hence, you probably don't want to replace that slot. 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 `emm_options`

In `emm_options`, we may set or change the default values for the above options. These defaults are set separately for different contexts in which `emmGrid` objects are created, in a named list of option lists. Currently, the following main list entries are supported:

`ref_grid`

  A named `list` of defaults for objects created by `ref_grid`. This could affect other objects as well. For example, if `emmeans` is called with a fitted model object, it calls `ref_grid` and this option will affect the resulting `emmGrid` object.

`emmeans`

  A named `list` of defaults for objects created by `emmeans` or `emtrends`.

`contrast`

  A named `list` of defaults for objects created by `contrast.emmGrid` or `pairs.emmGrid`.

`summary`

  A named `list` of defaults used by the methods `summary.emmGrid`, `predict.emmGrid`, `test.emmGrid`, `confint.emmGrid`, and `emmip`. The only option that can affect the latter four is `"predict.method"`.

`graphics.engine`

  A character value matching `c("ggplot", "lattice")`, setting the default engine to use in `emmip` and `plot.emmGrid`. Defaults to `"ggplot"`.

`msg.interaction`

  A logical value controlling whether or not a message is displayed when `emmeans` averages over a factor involved in an interaction. It is probably not appropriate to do this, unless the interaction is weak. Defaults to `TRUE`.

`msg.nesting`

  A logical value controlling whether or not to display a message when a nesting structure is auto-detected. The existence of such a structure affects computations of EMMs. Sometimes, a nesting structure is falsely detected – namely when a user has omitted some main effects but included them in interactions. This does not change the model fit, but it produces a different parameterization that is picked up when the reference grid is constructed. Defaults to `TRUE`.

Some other options have more specific purposes:

`estble.tol`

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

`save.ref_grid`

  Logical value of `TRUE` if you wish the latest reference grid created to be saved in `.Last.ref_grid`

Options for `lme4::lmerMod` models

  Options `lmer.df`, `disable.pbkrtest`, `pbkrtest.limit`, `disable.lmerTest`, and `lmerTest.limit` options affect how degrees of freedom are computed for `lmerMod` objects produced by the lme4 package). See that section of the "models" vignette for details.

### Examples

    # Using an already-transformed response:
    mypigs <- transform(pigs, logconc = log(pigs$conc))
    mypigs.lm <- lm(logconc ~ source + factor(percent), data = mypigs)

    # Reference grid that knows about the transformation:
    mypigs.rg <- update(ref_grid(mypigs.lm), tran = "log",
                        predict.type = "response")
    emmeans(mypigs.rg, "source")
    ## Not run:
    emm_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 emmeans 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:
    emm_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_emm_option("estble.tol")

[Package emmeans version 1.1.3 Index]