R: Methods for 'ref.grid' objects

summary {lsmeans} | R Documentation

## Methods for `ref.grid` objects

### Description

Use these methods to summarize, print, plot, or examine objects of class `"ref.grid"`. They also apply to the class `"lsmobj"`, which is an extension of `"ref.grid"`.

### Usage

    ## S3 method for class 'ref.grid'
    summary(object, infer, level, adjust, by, type, df,
        null, delta, side, ...)

    ## S3 method for class 'ref.grid'
    predict(object, type, ...)

    ## S3 method for class 'ref.grid'
    str(object, ...)

    ## S3 method for class 'ref.grid'
    rbind(..., deparse.level = 1, adjust = "mvt")

    ## S3 method for class 'ref.grid'
    x[i, adjust = "mvt", ...]

    ## S3 method for class 'ref.grid'
    print(x, ...)
    ## S3 method for class 'summary.ref.grid'
    print(x, ..., digits = NULL, quote = FALSE, right = TRUE)

    ## S3 method for class 'ref.grid'
    xtable(x, caption = NULL, label = NULL, align = NULL,
        digits = 4, display = NULL, auto = FALSE, ...)
    ## S3 method for class 'summary.ref.grid'
    xtable(x, caption = NULL, label = NULL, align = NULL,
        digits = 4, display = NULL, auto = FALSE, ...)
    ## S3 method for class 'xtable.lsm'
    print(x, type = getOption("xtable.type", "latex"),
        include.rownames = FALSE, sanitize.message.function = footnotesize,
        ...)

    ## S3 method for class 'lsmobj'
    plot(x, y, type, intervals = TRUE, comparisons = FALSE,
        alpha = 0.05, adjust = "tukey", int.adjust, ...)
    ## S3 method for class 'summary.ref.grid'
    plot(x, y, horizontal = TRUE,
        xlab, ylab, layout, ...)

    ## S3 method for class 'ref.grid'
    vcov(object, ...)

    regrid (object, transform = c("response", "log", "none"),
        inv.log.lbl = "response", predict.type)

    ## S3 method for class 'ref.grid'
    as.mcmc(x, names = TRUE, ...)

### Arguments

`object` | An object of class `"ref.grid"`.
`infer` | A vector of two logical values. The first determines whether confidence intervals are displayed, and the second determines whether t tests and P values are displayed. If only one value is provided, it is used for both.
`level` | Confidence level for confidence intervals, if `infer[1]` is `TRUE`.
`adjust` | Character value naming the method used to adjust p values or confidence limits; or to adjust comparison arrows in `plot`. See Details.
`by` | Character name(s) of variables to use for grouping. This affects the family of tests considered in adjusted P values. The printed display of the summary is grouped by the `by` variables.
`type` | Type of prediction desired (except in `print.xtable`). This only has an effect if there is a known transformation or link function. `"response"` specifies that the inverse transformation be applied. Other valid values are `"link"`, `"lp"`, and `"linear"`; these are equivalent, and request that results be shown for the linear predictor. The default is `"link"`, unless the `"predict.type"` option is in force; see `lsm.options`. Note that `type` is also an argument for the `print.xtable` method; it is passed to `print.xtableList` in the xtable package.
`df` | If non-missing a constant number of degrees of freedom to use in constructing confidence intervals and P values (`NA` specifies asymptotic results).
`null` | Null hypothesis value(s) against which estimates are tested. May be a single value used for all, or a numeric vector of length equal to the number of tests in each family (i.e., `by` group in the displayed table).
`delta` | Numeric value. If zero, ordinary tests of significance are performed. If positive, this specifies a threshold for testing equivalence (using the TOST or two-one-sided-test method), non-inferiority, or non-superiority, depending on `side`. See Details for how the test statistics are defined.
`side` | Numeric or character value specifying whether the test is left-tailed (`-1`, `"-"`, code"<", `"left"`, or `"nonsuperiority"`); right-tailed (`1`, `"+"`, `">"`, `"right"`, or `"noninferiority"`); or two-sided (`0`, `2`, `"!="`, `"two-sided"`, `"both"`, `"equivalence"`, or `"="`).
`deparse.level` | This argument is needed by the generic `rbind` method, but ignored by its `ref.grid` method.
`x` | The object to be subsetted, printed, plotted, or converted.
`y` | This argument is ignored.
`i` | Integer index(es) of which linear functions to extract.
`horizontal` | Determines orientation of plotted confidence intervals.
`intervals` | If `TRUE`, confidence intervals are plotted for each estimate
`comparisons` | If `TRUE`, “comparison arrows” are added to the plot, in such a way that the degree to which arrows overlap reflects as much as possible the significance of the comparison of the two estimates.
`alpha` | The `alpha` argument to use in constructing comparison arrows.
`int.adjust` | the multiplicity adjustment method for the plotted confidence intervals; if missing, it defaults to the object's internal `adjust` setting (see `update`). (Note: the `adjust` argument in `plot` sets the adjust method for the comparison arrows, not the confidence intervals.)
`transform` | Character value. If `"response"`, the inverse transformation is applied to the estimates in the grid; if `"log"`, the results are formulated as if the response had been `log`-transformed; if `"none"`, predictions thereof are on the same scale as in `object`, and any internal transformation information is preserved. For compatibility with past versions, `transform` may also be logical; `TRUE` is taken as `"response"`, and `FALSE` as `"none"`.
`inv.log.lbl` | Character value. This applies only when `transform = "log"`, and is used to label the predictions if subsequently summarized with `type = "response"`.
`predict.type` | Character value. If provided, the returned object is first `update`d with the given type, e.g., `"response"`.
`names` | Logical scalar or vector specifying whether variable names are appended to levels in the column labels for the `as.mcmc` result – e.g., column names of `treat A` and `treat B` versus just `A` and `B`. When there is more than one variable involved, the elements of `names` are used cyclically.
`..., digits, quote, right, caption, label, align, display, auto, include.rownames, sanitize.message.function, xlab, ylab, layout` | For summaries, these are additional arguments passed to other methods including `print.data.frame`, `xtableList`, `print.xtableList`, `update`, or `dotplot` as appropriate. If not specified, appropriate defaults are used. For example, the default `layout` is one column of horizontal panels or one row of vertical panels.

### Details

Defaults for summarization, etc.: The `misc` slot in `object` contains default values for `by`, `infer`, `level`, `adjust`, `type`, `null`, `side`, and `delta`. These defaults vary depending on the code that created the object. The `update` method may be used to change these defaults. In addition, any options set using lsm.options(summary=...) will trump those stored in the object's `misc` slot.

Transformations and links: With `type="response"`, the transformation assumed can be found in object@misc$tran, and its label, for the summary is in object@misc$inv.lbl. At this time, `tran` must be one of the named transformations valid for `make.link`. Any t or z tests are still performed on the scale of the linear predictor, not the inverse-transformed one. Similarly, confidence intervals are computed on the linear-predictor scale, then inverse-transformed.

Confidence-limit and P-value adjustments: The `adjust` argument specifies a multiplicity adjustment for tests or confidence intervals. This adjustment always is applied separately to each table or sub-table that you see in the printed output (see the details on `rbind` below for how to combine tables). The valid values of `adjust` are as follows:

`"tukey"`

  Uses the Studentized range distribution with the number of means in the family. (Available for two-sided cases only.)

`"scheffe"`

  Computes p values from the F distribution, according to the Scheffe critical value of sqrt[k*F(k,d)], where d is the error degrees of freedom and k is (family size minus 1) for contrasts, and (number of estimates) otherwise. (Available for two-sided cases only.)

`"sidak"`

  Makes adjustments as if the estimates were independent (a conservative adjustment in many cases).

`"bonferroni"`

  Multiplies p values, or divides significance levels by the number of estimates. This is a conservative adjustment.

`"dunnettx"`

  Uses an approximation to the Dunnett distribution for a family of estimates having pairwise correlations of 0.5 (as is true when comparing treatments with a control with equal sample sizes). The accuracy of the approximation improves with the number of simultaneous estimates, and is much faster than `"mvt"`. (Available for two-sided cases only.)

`"mvt"`

  Uses the multivariate t distribution to assess the probability or critical value for the maximum of k estimates. This method produces the same p values and intervals as the default `summary` or `confint` methods to the results of `as.glht`. In the context of pairwise comparisons or comparisons with a control, this produces “exact” Tukey or Dunnett adjustments, respectively. However, the algorithm (from the mvtnorm package) uses a Monte Carlo method, so results are not exactly repeatable unless the random-number seed is used (see `set.seed`). As the family size increases, the required computation time will become noticeable or even intolerable, making the `"tukey"`, `"dunnettx"`, or others more attractive.

`"none"`

  Makes no adjustments to the p values.

For P-value adjustments only, the Bonferroni-inequality-based adjustment methods in `p.adjust` are also available (currently, these include `"holm"`, `"hochberg"`, `"hommel"`, `"bonferroni"`, `"BH"`, `"BY"`, `"fdr"`, and `"none"`). If a `p.adjust.methods` method other than `"bonferroni"` or `"none"` is specified for confidence limits, the straight Bonferoni adjustment is used instead. Also, if an adjustment method is not appropriate (e.g., using `"tukey"` with one-sided tests, or with results that are not pairwise comparisons), a more appropriate method (usually `"sidak"`) is substituted.

In some cases, confidence and p-value adjustments are only approximate – especially when the degrees of freedom or standard errors vary greatly within the family of tests. The `"mvt"` method is always the correct one-step adjustment, but it can be very slow. One may use `as.glht` with methods in the multcomp package to obtain non-conservative multi-step adjustments to tests.

Information: The `str` method outputs a very brief summary of the object, whereas `levels` produces a `data.frame` containing the combinations of levels of predictor values that define the reference grid.

`xtable`-related methods: The `xtable` methods actually use `xtableList`, because of the ability to display messages such as those for P-value adjustments. These methods return an object of class `"xtable.lsm"` – an extension of `"xtableList"`. Unlike other `xtable` methods, the number of digits defaults to 4; and degrees of freedom and t ratios are always formatted independently of `digits`. The `print` method uses `print.xtableList`, and any `...` arguments are passed there.

`rbind` and `[` methods: `rbind` can be used to combine two or more reference grids into one. The `"["` method for `ref.grid`s may be used to obtain a subset. The primary reason for doing this would be to redefine the family of tests to which a P-value adjustment method applies. In `rbind`, the variables defined in the objects' grids are merged into one grid, and the returned object has no “by” variables and the multiplicity adjustment method set to `"mvt"` (as this is likely the only appropriate one). `rbind` throws an error if there are any mismatches among the dimensions, fixed-effect coefficients, or covariance matrices.

Non-estimable cases: When the model is rank-deficient, each row `x` of `object`'s `linfct` slot is each checked for estimability. If `sum(x*bhat)` is found to be non-estimable, then an `NA` is displayed for the estimate (as well as any associated statistics). This check is performed using the orthonormal basis `N` in the `nbasis` slot for the null space of the rows of the model matrix. Estimability fails when ||Nx||^2 / ||x||^2 exceeds `tol`, which by default is `1e-8`. You may change it via `lsm.options` by setting `estble.tol` to the desired value.

More on tests: When `delta = 0`, test statistics are of the usual form (estimate - null)/SE, or notationally, t = (Q - θ_0)/SE where Q is our estimate of θ; then left, right, or two-sided p values are produced.

When `delta` is positive, the test statistic depends on `side` as follows.

Left-sided (nonsuperiority, H_0: θ ≥ θ_0 + δ versus H_1: θ < θ_0 + δ): t = (Q - θ_0 - δ)/SE. The p value is the lower-tail probability.

Right-sided (noninferiority): H_0: θ ≤ θ_0 - δ versus H_1: θ > θ_0 - δ): t = (Q - θ_0 + δ)/SE. The p value is the upper-tail probability.

Two-sided (equivalence): H_0: |θ - θ_0| ≥ δ versus H_1: |θ - θ_0| < δ): t = (|Q - θ_0| - δ)/SE. The p value is the lower-tail probability.

Plots: The `plot` method for `"lsmobj"` or `"summary.ref.grid"` objects (but not `"ref.grid"` objects themselves) produces a plot displaying confidence intervals for the estimates. If any `by` variables are in force, the plot is divided into separate panels. These functions use the `dotplot` function, and thus require that the lattice package be installed. For `"summary.ref.grid"` objects, the `...` arguments in `plot` are passed only to `dotplot`, whereas for `"lsmobj"` objects, the object is updated using `...` before summarizing and plotting.

In plots with `comparisons = TRUE`, the resulting arrows are only approximate, and in some cases may fail to accurately reflect the pairwise comparisons of the estimates – especially when estimates having large and small standard errors are intermingled in just the wrong way.

Re-gridding: The `regrid` function reparameterizes an existing `ref.grid` so that its `linfct` slot is the identity matrix and its `bhat` slot consists of the estimates at the grid points. If `transform` is `TRUE`, the inverse transform is applied to the estimates. Outwardly, the `summary` after applying `regrid` is identical to what it was before (using type="response" if `transform` is `TRUE`). But subsequent contrasts will be conducted on the transformed scale – which is the reason this function exists. See the example below. In cases where the degrees of freedom depended on the linear function being estimated, the d.f. from the reference grid are saved, and a kind of “containment” method is substituted in the returned object whereby the calculated d.f. for a new linear function will be the minimum d.f. among those having nonzero coefficients. This is kind of an ad hoc method, and it can over-estimate the degrees of freedom in some cases.

MCMC samplers: When the object's `post.beta` slot is non-trivial, `as.mcmc` will return an `mcmc` object that can be summarized or plotted using methods in the coda package. Specifically, `post.beta` is transformed by post-multiplying by `t(linfct)`, creating a sample from the posterior distribution of LS means.

### Value

The `summary` method for `"ref.grid"` objects returns an object of class `"summary.ref.grid"`, which extends `"data.frame"`. `xtable` returns an object of class `"xtable.lsm"`, as explained in details. `plot` returns an object of class `"trellis"`. `vcov` returns the covariance matrix of the product of the object's `linfct` and `bhat` slots. `as.mcmc` returns a coda `mcmc` object.

### Author(s)

Russell V. Lenth

### See Also

Methods for the closely related `"lsmobj"` class can be found in `contrast`, `cld`, and `glht`. For more on Bonferroni-based P-value adjustments, see `p.adjust`. Also, `test` and `confint` are essentially front-ends for `summary`, so additional examples may be found there.

### Examples

    require(lsmeans)
    warp.lm <- lm(breaks ~ wool * tension, data = warpbreaks)
    warp.rg <- ref.grid(warp.lm)
    str(warp.rg)
    levels(warp.rg)

    summary(warp.rg)

    summary(warp.rg, by = "wool",
            infer = c(TRUE, FALSE), level = .90, adjust = "sidak")

    # Do all pairwise comparisons within rows or within columns,
    # all considered as one faily of tests:
    w.t <- pairs(lsmeans(warp.rg, ~ wool | tension))
    t.w <- pairs(lsmeans(warp.rg, ~ tension | wool))
    rbind(w.t, t.w)

    # Transformed response
    sqwarp.rg <- ref.grid(update(warp.lm, sqrt(breaks) ~ .))
    summary(sqwarp.rg)

    # Back-transformed results - compare with summary of 'warp.rg'
    summary(sqwarp.rg, type = "response")

    # But differences of sqrts can't be back-transformed
    summary(pairs(sqwarp.rg, by = "wool"), type = "response")

    # We can do it via regrid
    sqwarp.rg2 <- regrid(sqwarp.rg)
    summary(sqwarp.rg2)  # same as for sqwarp.rg with type = "response"
    pairs(sqwarp.rg2, by = "wool")

    # Logistic regression
    # Reshape the Titanic data
    Titan <- do.call("expand.grid", dimnames(Titanic)[-4])
    Titan$Died <- matrix(Titanic, ncol=2)
    Titan.glm <- glm(Died ~ (Class + Sex + Age)^2,
        family = binomial, data = Titan)
    Titan.lsm <- lsmeans(Titan.glm, ~ Class|Sex, at = list(Age="Adult"))
    summary(Titan.lsm, type="response")
    summary(pairs(Titan.lsm), type="response")

    # Nonsuperiority test: Is any class no more likely to die than
    # the 1st class passengers?
    summary(contrast(Titan.lsm, "trt.vs.ctrl1"), delta = 1,
        adjust = "none", side = "<")

    # Plot 90% CIs on the response scale
    plot(Titan.lsm, type = "response", level = .90,
         xlab = "Predicted probability of drowning")

[Package lsmeans version 2.25-5 Index]