Description

These are the primary methods for obtaining numerical or tabular results from an emmGrid object. summary.emmGrid is the general function for summarizing emmGrid objects. It also serves as the print method for these objects; so for convenience, summary() arguments may be included in calls to functions such as emmeans and contrast that construct emmGrid objects. Note that by default, summaries for Bayesian models are diverted to hpd.summary.

Usage

Arguments

Details

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.

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 displays it with custom formatting. For models fitted using MCMC methods, the call is diverted to hpd.summary (with prob set to level, if specified); one may alternatively use general MCMC summarization tools with the results of as.mcmc.

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(.)).

Defaults

The misc slot in object may contain default values for by, calc, 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.

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

When bias.adjust is TRUE, then back-transformed estimates are adjusted by adding 0.5 h''(u)σ^2, where h is the inverse transformation and u is the linear predictor. This is based on a second-order Taylor expansion. There are better or exact adjustments for certain specific cases, and these may be incorporated in future updates.

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 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[r*qf(alpha, r, d)], where d is the error degrees of freedom and r is the rank of the set of linear functions under consideration. By default, the value of r is computed from object@linfct for each by group; however, if the user specifies an argument matching scheffe.rank, its value will be used instead. Ordinarily, if there are k means involved, then r = k - 1 for a full set of contrasts involving all k means, and r = k for the means themselves. (The Scheffe adjustment is 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.

Tests of significance, nonsuperiority, noninferiority, or equivalence

When delta = 0, test statistics are the usual tests of significance. They are of the form (estimate - null)/SE. Notationally:

Significance

H_0: θ = θ_0 versus
H_1: θ < θ_0 (left-sided), or
H_1 θ > θ_0 (right-sided), or
H_1: θ \ne θ_0 (two-sided)
The test statistic is
t = (Q - θ_0)/SE
where Q is our estimate of θ; then left, right, or two-sided p values are produced, depending on side.

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.
Note that t is the maximum of t_{nonsup} and -t_{noninf}. This is equivalent to choosing the less significant result in the two-one-sided-test (TOST) procedure.

Non-estimable cases

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.

Warning about potential misuse of P values

A growing consensus in the statistical and scientific community is that the term “statistical significance” should be completely abandoned, and that criteria such as “p < 0.05” never be used to assess the importance of an effect. These practices are just too misleading and prone to abuse. See the “basics” vignette for more discussion.

Note

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.

The as.data.frame method is intended primarily to allow for emmGrid objects to be coerced to a data frame as needed internally. However, we recommend against users routinely using as.data.frame; instead, use summary, confint, or test, which already return a special data.frame with added annotations. Those annotations display important information such as adjustment methods and confidence levels. If you need to see more digits, use print(summary(object), digits = ...); and if you always want to see more digits, use emm_options(opt.digits = FALSE).

See Also

hpd.summary

Examples