emmeans (version 0.9)

summary.emmGrid: Summaries, predictions, intervals, and tests for emmGrid objects

Description

These are the primary methods for obtaining numerical or tabular results from an emmGrid object.

Usage

# S3 method for emmGrid
summary(object, infer, level, adjust, by, type, df, null,
  delta, side, ...)
# S3 method for emmGrid
predict(object, type, ...)
# S3 method for emmGrid
confint(object, parm, level = 0.95, ...)
test(object, null, ...)
# S3 method for emmGrid
test(object, null = 0, joint = FALSE, verbose = FALSE,
  rows, by, ...)

Arguments

object

An object of class "emmGrid" (see emmGrid-class)

infer

A vector of one or two 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

Numerical value between 0 and 1. 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 into separate tables. This affects the family of tests considered in adjusted P values.

type

Character: 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. "mu" (or equivalently, "unlink") is usually the same as "response", but in the case where the model has both a link function and a response transformation, only the link part is back-transformed. Other valid values are "link", "lp", and "linear.predictor"; these are equivalent, and request that results be shown for the linear predictor, with no back-transformation. The default is "link", unless the "predict.type" option is in force; see emm_options.

df

Numeric. If non-missing, a constant number of degrees of freedom to use in constructing confidence intervals and P values (NA specifies asymptotic results).

null

Numeric. Null hypothesis value(s), on the linear-predictor scale, 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 (on the linear-predictor scale). 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 "="). See the special section below for more details.

...

Not used by summary.emmGrid or predict.emmGrid. In confint.emmGrid and test.emmGrid, these arguments are passed to summary.emmGrid.

parm

(Required argument for confint methods, but not used)

joint

Logical value. If FALSE, the arguments are passed to summary.emmGrid with infer=c(FALSE, TRUE). If joint = TRUE, a joint test of the hypothesis L beta = null is performed, where L is object@linfct and beta is the vector of fixed effects estimated by object@betahat. This will be either an F test or a chi-square (Wald) test depending on whether degrees of freedom are available.

verbose

Logical value. If TRUE and joint = TRUE, a table of the effects being tested is printed.

rows

Integer values. The rows of L to be tested in the joint test. If missing, all rows of L are used. If not missing, by variables are ignored.

Value

summary.emmGrid, confint.emmGrid, and test.emmGrid return an object of class "summary_emm", which is an extension of data.frame but with a special print method that with custom formatting. For models fitted using MCMC methods, the result is typically a frequentist summary, based on the empirical mean and covariance matrix of the post.beta slot. A Bayesian summary may be obtained using as.mcmc.emmGrid and summarizing that result using tools for Bayesian estimation.

predict returns a vector of predictions for each row of object@grid.

Testing nonsuperiority, noninferiority, or equivalence

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.

Details

summary.emmGrid is the general function for summarizing emmGrid objects. confint.emmGrid is equivalent to summary.emmGrid with infer = c(TRUE, FALSE). When called with joint = FALSE, test.emmGrid is equivalent to summary.emmGrid with infer = c(FALSE, TRUE).

With joint = TRUE, test.emmGrid calculates the Wald test of the hypothesis linfct %*% bhat = null, where linfct and bhat refer to slots in object (possibly subsetted according to by or rows). An error is thrown if any row of linfct is non-estimable. It is permissible for the rows of linfct to be linearly dependent, as long as null == 0, in which case a reduced set of contrasts is tested. Linear dependence and nonzero null cause an error.

Examples

# NOT RUN {
warp.lm <- lm(breaks ~ wool * tension, data = warpbreaks)
warp.emmGrid <- emmeans(warp.lm, ~ tension | wool)
warp.emmGrid    # implicitly runs 'summary'

confint(warp.emmGrid, by = NULL, level = .90)

# --------------------------------------------------------------
pigs.lm <- lm(log(conc) ~ source + factor(percent), data = pigs)
pigs.emmGrid <- emmeans(pigs.lm, "percent", type = "response")
summary(pigs.emmGrid)    # (inherits type = "response")

# For which percents is EMM non-inferior to 35, based on a 10% threshold?
# Note the test is done on the log scale even though we have type = "response"
test(pigs.emmGrid, null = log(35), delta = log(1.10), side = ">")

test(contrast(pigs.emmGrid, "consec"))

test(contrast(pigs.emmGrid, "consec"), joint = TRUE)

# }