lsmeans (version 2.19)

summary: 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 = 0, delta = 0, side = 0, ...)

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

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

## 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 'lsmobj':
plot(x, y, type, intervals = TRUE, comparisons = FALSE,
    alpha = 0.05, adjust = "tukey", int.adjust = "none", ...)
## 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 = TRUE)

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

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 D

side

Numeric or character value specifying whether the test is left-tailed (-1, "-", code{"<"}, "left", or "nonsuperiority"); right-tailed (1, "+", ">", "right"

x

The object to be printed, plotted, or converted.

y

This argument is ignored.

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, int.adjust

The alpha argument to use in constructing comparison arrows. int.adjust may be used to set the adjust argument for the confidence intervals (use adjust to set the adjust method for the comparison arrows)

transform

Logical value; if true, the inverse transformation is applied to the estimates in the grid

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

..., digits, quote, right, xlab, ylab, layout

For summaries, these are additional arguments passed to other methods including print.data.frame, update, or do

Value

• The summary method for "ref.grid" objects returns an object of class "summary.ref.grid", which extends "data.frame". 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.

Details

Defaults: The misc slot in object contains default values for by, infer, level, adjust, and type. 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 has the following effects: [object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object] For P-value adjustments only, the other Bonferroni-inequality-based adjustment methods in p.adjust are also available. If a p.adjust.methods method is specified for confidence limits, they are left unadjusted and an annotation is added that says so. 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. 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 - \theta_0)/SE$ where $Q$ is our estimate of $\theta$; 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: \theta \ge \theta_0 + \delta$ versus $H_1: \theta < \theta_0 + \delta$): $t = (Q - \theta_0 - \delta)/SE$. The $p$ value is the lower-tail probability. Right-sided (noninferiority): $H_0: \theta \le \theta_0 - \delta$ versus $H_1: \theta > \theta_0 - \delta$): $t = (Q - \theta_0 + \delta)/SE$. The $p$ value is the upper-tail probability. Two-sided (equivalence): $H_0: |\theta - \theta_0| \ge \delta$ versus $H_1: |\theta - \theta_0| < \delta$): $t = (|Q - \theta_0| - \delta)/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. Warning: in cases where degrees of freedom depends on the linear function being estimated, regrid will probably cause fatal errors when summary is called. 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.

See Also

Methods for the closely related "lsmobj" class can be found in contrast, cld, and glht. 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)

summary(warp.rg)

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

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