summary.emmGrid {emmeans} | R Documentation |
emmGrid
objectsThese are the primary methods for obtaining numerical or tabular results
from an emmGrid
object.
## S3 method for class 'emmGrid' summary(object, infer, level, adjust, by, type, df, null, delta, side, frequentist, ...) ## S3 method for class 'emmGrid' predict(object, type, ...) ## S3 method for class 'emmGrid' as.data.frame(x, row.names = NULL, optional = FALSE, ...) ## S3 method for class 'summary_emm' x[..., as.df = TRUE] ## S3 method for class 'emmGrid' confint(object, parm, level = 0.95, ...) test(object, null, ...) ## S3 method for class 'emmGrid' test(object, null = 0, joint = FALSE, verbose = FALSE, rows, by, status = FALSE, ...)
object |
An object of 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 |
adjust |
Character value naming the method used to adjust p values
or confidence limits; or to adjust comparison arrows in |
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. |
df |
Numeric. If non-missing, a constant number of degrees of freedom to
use in constructing confidence intervals and P values ( |
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., |
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 |
Numeric or character value specifying whether the test is
left-tailed ( |
frequentist |
Ignored except if a Bayesian model was fitted. If missing
of |
... |
(Not used by |
x |
object of the given class |
row.names |
passed to |
optional |
passed to |
as.df |
Logical value. With |
parm |
(Required argument for |
joint |
Logical value. If |
verbose |
Logical value. If |
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, |
status |
logical. If |
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.
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 displays it 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
.
The as.data.frame
method returns a plain data frame,
equivalent to as.data.frame(summary(.))
.
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
emm_options(summary = ...) will trump those stored in the object's
misc
slot.
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. 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.
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
rbind.emmGrid
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 our ownad hoc 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 same
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 tests, not confidence intervals, 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 Bonferroni 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.
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.
H_0: θ ≥ θ_0 + δ
versus H_1: θ < θ_0 + δ
t = (Q - θ_0 - δ)/SE
The p value is the lower-tail probability.
H_0: θ ≤ θ_0 - δ
versus H_1: θ > θ_0 - δ
t = (Q - θ_0 + δ)/SE
The p value is the upper-tail probability.
H_0: |θ - θ_0| ≥ δ
versus H_1: |θ - θ_0| < δ
t = (|Q - θ_0| - δ)/SE
The p value is the lower-tail probability.
When the model is rank-deficient, each row x
of object
's
linfct
slot is checked for estimability. If sum(x*bhat)
is found to be non-estimable, then the string NonEst
is displayed for the
estimate, and associated statistics are set to NA
.
The estimability 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 emm_options
by setting
estble.tol
to the desired value.
In doing testing and a transformation and/or link is in force, any
null
and/or delta
values specified must always be on the
scale of the linear predictor, regardless of the setting for 'type'. If
type = "response"
, the null value displayed in the summary table
will be back-transformed from the value supplied by the user. But the
displayed delta
will not be changed, because there (usually) is
not a natural way to back-transform it.
The default show
method for emmGrid
objects (with the
exception of newly created reference grids) is print(summary())
.
Thus, with ordinary usage of emmeans
and such, it is
unnecessary to call summary
unless there is a need to
specify other than its default options.
warp.lm <- lm(breaks ~ wool * tension, data = warpbreaks) warp.emm <- emmeans(warp.lm, ~ tension | wool) warp.emm # implicitly runs 'summary' confint(warp.emm, by = NULL, level = .90) # -------------------------------------------------------------- pigs.lm <- lm(log(conc) ~ source + factor(percent), data = pigs) pigs.emm <- emmeans(pigs.lm, "percent", type = "response") summary(pigs.emm) # (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.emm, null = log(35), delta = log(1.10), side = ">") test(contrast(pigs.emm, "consec")) test(contrast(pigs.emm, "consec"), joint = TRUE)