hypothesis_test: (Pairwise) comparisons between predictions

In ggeffects: Create Tidy Data Frames of Marginal Effects for 'ggplot' from Model Outputs

(Pairwise) comparisons between predictions

Description

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

Usage

hypothesis_test(model, ...)

test_predictions(model, ...)

## Default S3 method:
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 class 'ggeffects'
hypothesis_test(
  model,
  by = NULL,
  test = "pairwise",
  equivalence = NULL,
  p_adjust = NULL,
  df = NULL,
  collapse_levels = FALSE,
  verbose = TRUE,
  ...
)

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 one of: "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 (e.g. for logistic regression, as log-odds); "probability" (or "probs") returns contrasts on the probability scale, which is required for some model classes, like MASS::polr(); "oddsratios" to return contrasts on the odds ratio scale (only applies to logistic regression models); "irr" to return contrasts on the odds ratio scale (only applies to count models); or a transformation function like "exp" or "log", to return transformed (exponentiated respectively logarithmic) contrasts; note that these transformations are applied to the response scale. 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.

Value

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

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

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

# equivalence testing
hypothesis_test(m, c("c161sex", "c172code"), equivalence = c(-2.96, 2.96))

# equivalence testing, using the parameters package
pr <- ggpredict(m, c("c161sex", "c172code"))
parameters::equivalence_test(pr)

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

ggeffects documentation built on Oct. 17, 2023, 5:07 p.m.