Compare two subsets of factorial design cells

Convenience function for comparing two subsets of factorial design cells. It takes a brms model fit, two group specifications (two subsets of design cells), and the probability mass within the highest density interval of the difference in groups. It outputs the posterior mean of the 'higher' minus the 'lower' group, a credible interval of the mean difference, as well as the posterior probability and odds that the mean estimate of the 'higher' group is higher than that of the 'lower' group. A comparison of one group against the grand mean can be obtained by leaving out one of the two group specifications in the function call.

Usage

compare_groups(
  fit,
  higher = NULL,
  lower = NULL,
  hdi = 0.95,
  include_bf = FALSE
)

Arguments

fit

An object of class brmsfit.

higher

An expression specifying the 'higher' group to filter the draws for.

lower

An expression specifying the 'lower' group to filter the draws for.

hdi

A single value (0, 1) defining the probability mass within the highest density interval; defaults to 0.95.

include_bf

A Boolean flag indicating whether Bayes Factors should be approximated (required additional sampling); defaults to FALSE.

Value

An object of class 'faintCompare' containing summary statistics of the comparison.

Note

The faintr package currently does not support multivariate models and models that use families categorical, dirichlet, multinomial, and logistic_normal. Furthermore, models must not include special effect terms mo(), mi(), me(), and cs() for fixed effects. Also note that faintr currently does not support models where the intercept is a population-level parameter (class b), as is the case when using the 0 + Intercept syntax in the brm function call.

References

Bürkner, P.-C. (2017). brms: An R Package for Bayesian Multilevel Models Using Stan. Journal of Statistical Software, 80(1), 1-28. doi:10.18637/jss.v080.i01

Examples

if (FALSE) {
# fit a linear mixed effects model on data from a 2 x 2 factorial design
## regress voice pitch against gender and context
fit <- brms::brm(formula = pitch ~ gender * context + (1 | subject + sentence),
                 data = politeness)

# compare female speakers in informal contexts against male speakers in polite contexts
compare_groups(
 fit  = fit,
 higher = gender == "F" & context == "inf",
 lower  = gender == "M" & context == "pol"
)

# compare informal contexts against polite contexts, averaged over gender
compare_groups(
 fit  = fit,
 higher = context == "inf",
 lower  = context == "pol"
)

# compare female speakers against the grand mean
compare_groups(
 fit  = fit,
 higher = gender == "F",
 hdi = 0.8
)
}