ggeffects (version 1.3.1)

hypothesis_test: (Pairwise) comparisons between predictions

Description

Function to test differences of adjusted predictions for statistical significance. This is usually called contrasts or (pairwise) comparisons.

Usage

hypothesis_test(model, ...)
# S3 method for default
hypothesis_test(
  model,
  terms = NULL,
  by = NULL,
  test = "pairwise",
  equivalence = NULL,
  scale = "response",
  p_adjust = NULL,
  df = NULL,
  ci_level = 0.95,
  collapse_levels = FALSE,
  verbose = TRUE,
  ci.lvl = ci_level,
  ...
)
# S3 method for ggeffects
hypothesis_test(
  model,
  by = NULL,
  test = "pairwise",
  equivalence = NULL,
  p_adjust = NULL,
  df = NULL,
  collapse_levels = FALSE,
  verbose = TRUE,
  ...
)

Value

A data frame containing predictions (e.g. for test = NULL), contrasts or pairwise comparisons of adjusted predictions or estimated marginal means.

Arguments

model

A fitted model object, or an object of class ggeffects.

...

Arguments passed down to data_grid() when creating the reference grid and to marginaleffects::predictions() resp. marginaleffects::slopes(). For instance, arguments type or transform can be used to back-transform comparisons and contrasts to different scales. vcov can be used to calculate heteroscedasticity-consistent standard errors for contrasts. See examples at the bottom of this vignette for further details.

terms

Character vector with the names of the focal terms from model, for which contrasts or comparisons should be displayed. At least one term is required, maximum length is three terms. If the first focal term is numeric, contrasts or comparisons for the slopes of this numeric predictor are computed (possibly grouped by the levels of further categorical focal predictors).

by

Character vector specifying the names of predictors to condition on. Hypothesis test is then carried out for focal terms by each level of by variables. This is useful especially for interaction terms, where we want to test the interaction within "groups". by is only relevant for categorical predictors.

test

Hypothesis to test. By default, pairwise-comparisons are conducted. See section Introduction into contrasts and pairwise comparisons.

equivalence

ROPE's lower and higher bounds. Should be "default" or a vector of length two (e.g., c(-0.1, 0.1)). If "default", bayestestR::rope_range() is used. Instead of using the equivalence argument, it is also possible to call the equivalence_test() method directly. This requires the parameters package to be loaded. When using equivalence_test(), two more columns with information about the ROPE coverage and decision on H0 are added. Furthermore, it is possible to plot() the results from equivalence_test(). See bayestestR::equivalence_test() resp. parameters::equivalence_test.lm() for details.

scale

Character string, indicating the scale on which the contrasts or comparisons are represented. Can be "response" (default), which would return contrasts on the response scale (e.g. for logistic regression, as probabilities); "link" to return contrasts on scale of the linear predictors; "probability" (or "probs") returns contrasts on the probability scale (which is required for some model classes, like MASS::polr()); or a transformation function like "exp" or "log", to return transformed (exponentiated respectively logarithmic) contrasts. Note: If the scale argument is not supported by the provided model, it is automaticaly changed to a supported scale-type (a message is printed when verbose = TRUE).

p_adjust

Character vector, if not NULL, indicates the method to adjust p-values. See stats::p.adjust() for details. Further possible adjustment methods are "tukey" or "sidak". Some caution is necessary when adjusting p-value for multiple comparisons. See also section P-value adjustment below.

df

Degrees of freedom that will be used to compute the p-values and confidence intervals. If NULL, degrees of freedom will be extracted from the model using insight::get_df() with type = "wald".

ci_level

Numeric, the level of the confidence intervals.

collapse_levels

Logical, if TRUE, term labels that refer to identical levels are no longer separated by "-", but instead collapsed into a unique term label (e.g., "level a-level a" becomes "level a"). See 'Examples'.

verbose

Toggle messages and warnings.

ci.lvl

Deprecated, please use ci_level.

Introduction into contrasts and pairwise comparisons

There are many ways to test contrasts or pairwise comparisons. A detailed introduction with many (visual) examples is shown in this vignette.

P-value adjustment for multiple comparisons

Note that p-value adjustment for methods supported by p.adjust() (see also p.adjust.methods), each row is considered as one set of comparisons, no matter which test was specified. That is, for instance, when hypothesis_test() returns eight rows of predictions (when test = NULL), and p_adjust = "bonferroni", the p-values are adjusted in the same way as if we had a test of pairwise comparisons (test = "pairwise") where eight rows of comparisons are returned. For methods "tukey" or "sidak", a rank adjustment is done based on the number of combinations of levels from the focal predictors in terms. Thus, the latter two methods may be useful for certain tests only, in particular pairwise comparisons.

See Also

There is also an equivalence_test() method in the parameters package (parameters::equivalence_test.lm()), which can be used to test contrasts or comparisons for practical equivalence. This method also has a plot() method, hence it is possible to do something like:

library(parameters)
ggpredict(model, focal_terms) |>
  equivalence_test() |>
  plot()

Examples

if (FALSE) {
if (requireNamespace("marginaleffects") && interactive()) {
  data(efc)
  efc$c172code <- as.factor(efc$c172code)
  efc$c161sex <- as.factor(efc$c161sex)
  levels(efc$c161sex) <- c("male", "female")
  m <- lm(barthtot ~ c12hour + neg_c_7 + c161sex + c172code, data = efc)

  # direct computation of comparisons
  hypothesis_test(m, "c172code")

  # passing a `ggeffects` object
  pred <- ggpredict(m, "c172code")
  hypothesis_test(pred)

  # test for slope
  hypothesis_test(m, "c12hour")

  # interaction - contrasts by groups
  m <- lm(barthtot ~ c12hour + c161sex * c172code + neg_c_7, data = efc)
  hypothesis_test(m, c("c161sex", "c172code"), test = NULL)

  # interaction - pairwise comparisons by groups
  hypothesis_test(m, c("c161sex", "c172code"))

  # interaction - collapse unique levels
  hypothesis_test(m, c("c161sex", "c172code"), collapse_levels = TRUE)

  # p-value adjustment
  hypothesis_test(m, c("c161sex", "c172code"), p_adjust = "tukey")

  # not all comparisons, only by specific group levels
  hypothesis_test(m, "c172code", by = "c161sex")

  # specific comparisons
  hypothesis_test(m, c("c161sex", "c172code"), test = "b2 = b1")

  # interaction - slope by groups
  m <- lm(barthtot ~ c12hour + neg_c_7 * c172code + c161sex, data = efc)
  hypothesis_test(m, c("neg_c_7", "c172code"))
}
}