Bayes factors for informative hypotheses

Description

bain is an acronym for "Bayesian informative hypotheses evaluation". It uses the Bayes factor to evaluate hypotheses specified using equality and inequality constraints among (linear combinations of) parameters in a wide range of statistical models. A tutorial by Hoijtink, Mulder, van Lissa, and Gu (2018), was published in Psychological Methods. The preprint of that tutorial is available on PsyArxiv (doi:10.31234/osf.io/v3shc) or on the bain website at https://informative-hypotheses.sites.uu.nl/software/bain/ Users are advised to read the tutorial AND the vignette that is provided with this package before using bain.

Usage

bain(x, hypothesis, fraction = 1, ...)

Arguments

Value

The main output resulting from analyses with bain are Bayes factors and posterior model probabilities associated with the hypotheses that are evaluated. See the tutorial and the vignette for further elaborations.

Author(s)

The main authors of the bain package are Xin Gu, Caspar van Lissa, Herbert Hoijtink and Joris Mulder with smaller contributions by Marlyne Bosman, Camiel van Zundert, and Fayette Klaassen. Contact information can be found on the bain website at https://informative-hypotheses.sites.uu.nl/software/bain/

References

For a tutorial on this method, see:

Hoijtink, H., Mulder, J., van Lissa, C., & Gu, X. (2019). A tutorial on testing hypotheses using the Bayes factor. Psychological methods, 24(5), 539. doi:10.1037/met0000201

For applications in structural equation modeling, see:

Van Lissa, C. J., Gu, X., Mulder, J., Rosseel, Y., Van Zundert, C., & Hoijtink, H. (2021). Teacher’s corner: Evaluating informative hypotheses using the Bayes factor in structural equation models. Structural Equation Modeling: A Multidisciplinary Journal, 28(2), 292-301. doi:10.1080/10705511.2020.1745644.

For the statistical underpinnings, see:

Gu, Mulder, and Hoijtink (2018). Approximated adjusted fractional Bayes factors: A general method for testing informative hypotheses. British Journal of Mathematical and Statistical Psychology, 71(2), 229-261. doi:10.1111/bmsp.12110.

Hoijtink, H., Gu, X., & Mulder, J. (2019). Bayesian evaluation of informative hypotheses for multiple populations. British Journal of Mathematical and Statistical Psychology, 72(2), 219-243. doi:10.1111/bmsp.12145.

Hoijtink, H., Gu, X., Mulder, J., & Rosseel, Y. (2019). Computing Bayes factors from data with missing values. Psychological Methods, 24(2), 253. doi:10.31234/osf.io/q6h5w

Examples

# Evaluation of informative hypotheses for an ANOVA
# make a factor of variable site
sesamesim$site <- as.factor(sesamesim$site)
# execute an analysis of variance using lm() which, due to the -1, returns
# estimates of the means of postnumb per group
anov <- lm(postnumb~site-1,sesamesim)
# take a look at the estimated means and their names
coef(anov)
# set a seed value
set.seed(100)
# use the names to formulate and test hypotheses with bain
results <- bain(anov, "site1=site2=site3=site4=site5; site2>site5>site1>
site3>site4")
#
# SEE THE TUTORIAL AND VIGNETTE FOR MANY ADDITIONAL EXAMPLES

Sensitivity analysis for bain

Description

Conducts a sensitivity analysis for bain.

Usage

bain_sensitivity(x, hypothesis, fractions = 1, ...)

Arguments

Details

The Bayes factor for equality constraints is sensitive to a scaling factor applied to the prior distribution. The argument fraction adjusts this scaling factor. The function bain_sensitivity is a wrapper for bain, which accepts a vector for the fractions argument, and returns a list of bain results objects. A table with a sensitivity analysis for specific statistics can be obtained using the summary() function, which accepts the argument summary(which_stat = ...). The available statistics are elements of the $fit table (Fit_eq, Com_eq, Fit_in, Com_in, Fit, Com, BF, PMPa, and PMPb), and elements of the BFmatrix, which can be accessed by matrix notation, e.g.: summary(bain_sens, which_stat = "BFmatrix[1,2]").

Value

A data.frame of class "bain_sensitivity".

Examples

sesamesim$site <- as.factor(sesamesim$site)
res <- lm(sesamesim$postnumb~sesamesim$site-1)
set.seed(4583)
bain_sens <- bain_sensitivity(res, "site1=site2;
                                    site2>site5",
                                    fractions = c(1,2,3))
summary(bain_sens, which_stat = "BF.c")
summary(bain_sens, which_stat = "BFmatrix[1,2]")

Constraint to equation

Description

Formats a constraint as an equation that can be evaluated. Adds scalars to all parameters in the constraint, and adds a XXXconstant parameter to any constants. Also adds "*" and "+" operators where necessary for evaluation.

Usage

constraint_to_equation(hyp)

Arguments

Value

Character

Constraint to row

Description

Evaluate a constraint, which has been formatted as an equation, with all terms moved to the left hand side, and return a single row of a (in)equality constraint matrix.

Usage

constraint_to_row(varnames, hyp)

Arguments

Value

Numeric vector.

Create (in)equality constraint matrices

Description

Parses a character string describing a set of informative hypotheses, and returns (in)equality constraint matrices

Usage

create_matrices(varnames, hyp)

Arguments

Details

Informative hypotheses specified as a character string by "hyp" should adhere to the following simple syntax:

• Competing hypotheses are separated by ";". Thus, "a=b;a>b" means that H1: a=b, and H2: a>b.

• Each individual hypothesis consists of a (series of) (in)equality constraint(s). Every single (in)equality constraint is of the form "R1*mu1 + R2*mu2+... = r", where capital Rs refer to numeric scaling constants, must refer to the names of parameters in the model, and the lower case r refers to a constant. Standard mathematical simplification rules apply; thus, "R1*mu1 = R2*mu2" is equivalent to "R1*mu1 - R2*mu2 = 0".

• Multiple unrelated constraints within one hypothesis can be chained by "&". Thus, "a=b&c=d" means that H1: a=b AND c=d.

• Multiple related constraints within one hypothesis can be chained by repeating the (in)equality operators "=", "<", or ">". Thus, "a<b<c" means that H1: a < b AND b < c.

• Parameters can be grouped by placing them in a parenthesized, comma separated list. Thus, "(a,b)>c" means that H1: a > c AND b > c. Similarly, "(a,b)>(c,d)" means that H1: a > c AND b > c AND b > c AND b > d.

Value

A pair of named matrices for every hypothesis specified in the hyp argument; one matrix named ERr, specifying equality constraints, and one matrix named IRr, specifying inequality constraints.

Author(s)

Caspar van Lissa

Expand compound constraints

Description

Takes a compound constraint, with multiple (in)equality operators, and expands it into simple constraints.

Usage

expand_compound_constraints(hyp)

Arguments

Value

A character vector with one element for each simple constraint

Expand parentheses

Description

Takes a constraint with parentheses containing a "vector" of parameter labels, and recursively expands the parenthesized "vectors".

Usage

expand_parentheses(hyp)

Arguments

Value

A character vector with one element for each simple constraint

Flip inequality

Description

Takes a constraint and flips elements on both sides of any "<" operators so that only the ">" operator is used to define inequality constraints.

Usage

flip_inequality(hyp)

Arguments

Value

Character

Get estimates from a model object

Description

Get estimates from a model object. This convenience function allows you to see that coefficients are properly extracted, note how their names will be parsed, and inspect their values.

Usage

get_estimates(x, ...)

Arguments

Value

An object of class 'model_estimates'

Examples

## Not run: 
# Example 1
m_tt <- t.test(iris$Sepal.Length[1:20], iris$Sepal.Length[21:40])
get_estimates(m_tt)
# Example 2
m_lm <- lm(Sepal.Length ~., iris)
get_estimates(m_lm)

## End(Not run)

The Effect of Prior Interaction on Trust

Description

These data were published in Kuiper and colleagues (2013), who set out to aggregate evidence for the effect of prior interactions between partners on trust in (economic) exchange relations across four heterogeneous replication studies. Batenburg et al. (2003) analyzed survey data using linear regression with covariates; Buskens and Raub (2002) analyzed experimental data using linear regression; Buskens and Weesie (2000) used an experimental design with a binary outcome, analyzed using probit regression; and Buskens, Raub, and Van der Veer (2010) used a longitudinal experimental design, analyzing the data with a three-level logistic regression. These studies each provide a regression coefficient (beta) assessing the effect of past experience on trust, and its estimated sampling variance (squared standard error). The sample sizes (n) were derived from the original publications.

Usage

data(kuiper2013)

Format

A data frame with 4 rows and 4 variables.

Details

References

Kuiper, R. M., Buskens, V., Raub, W., & Hoijtink, H. (2013). Combining Statistical Evidence From Several Studies: A Method Using Bayesian Updating and an Example From Research on Trust Problems in Social and Economic Exchange. Sociological Methods & Research, 42(1), 60–81. <doi:10.1177/0049124112464867>

Batenburg, R. S., W. Raub, and C. Snijders. 2003. Contacts and Contracts: Temporal Embeddedness and the Contractual Behavior of Firms. Research in the Sociology of Organizations 20:135-88.

Buskens, V. and W. Raub. 2002. Embedded Trust: Control and Learning. Advances in Group Processes 19:167-202.

Buskens, V., W. Raub, and J. van der Veer. 2010. Trust in Triads: An Experimental Study. Social Networks 32:301-12.

Buskens, V. and J. Weesie. 2000. An Experiment on the Effects of Embeddedness in Trust Situations: Buying a Used Car. Rationality and Society 12:227-53.

Label estimates from a model object

Description

Label estimates from a model object, before passing it on to the bain function.

Usage

label_estimates(x, labels, ...)

Arguments

Value

A model object of the same class as x.

See Also

get_estimates bain

Order terms

Description

Moves all terms on the right hand side of a constraint, which has been formatted as an equation, to the left hand side.

Usage

order_terms(hyp)

Arguments

Value

Character

Product Bayes Factor

Description

The product Bayes factor (PBF) aggregates evidence for an informative hypothesis across conceptual replication studies without imposing assumptions about heterogeneity.

Usage

pbf(...)

## Default S3 method:
pbf(x, ...)

## S3 method for class 'numeric'
pbf(yi, vi, ni, hypothesis = "y = 0", ...)

Arguments

Details

Currently, the argument 'x' accepts either: * A list of 'bain' objects, resulting from a call to 'bain'. * A list of model objects for which a 'bain' method exists; in this case, 'pbf' will call 'bain' on these model objects before aggregating the Bayes factors.

Value

A 'data.frame' of class 'pbf'.

References

Van Lissa, C. J., Kuiper, R. M., & Clapper, E. (2023, April 25). Aggregating evidence from conceptual replication studies using the product Bayes factor. doi:10.31234/osf.io/nvqpw

Examples

pbf(yi = c(-.33, .32, .39, .31),
    vi = c(.085, .034, .016, .071),
    ni = c(7, 10, 13, 20))

Standard Errors and CIs for Standardized Regression Coefficients

Description

Computes Normal Theory and ADF Standard Errors and CIs for Standardized Regression Coefficients

Usage

seBeta(
  X = NULL,
  y = NULL,
  cov.x = NULL,
  cov.xy = NULL,
  var.y = NULL,
  Nobs = NULL,
  alpha = 0.05,
  estimator = "ADF"
)

Arguments

Value

Author(s)

Jeff Jones and Niels Waller

References

Jones, J. A, and Waller, N. G. (2015). The Normal-Theory and Asymptotic Distribution-Free (ADF) covariance matrix of standardized regression coefficients: Theoretical extensions and finite sample behavior. Psychometrika, 80, 365-378.

Examples

set.seed(123)

R <- matrix(.5, 3, 3)
diag(R) <- 1
X <- sesamesim[, c("peabody", "prenumb", "postnumb")]
y <- sesamesim$age
results <- seBeta(X, y, Nobs = nrow(sesamesim), alpha = .05, estimator = 'ADF')
print(results, digits = 3)

library(MASS)

set.seed(123)

R <- matrix(.5, 3, 3)
diag(R) <- 1
X <- mvrnorm(n = 200, mu = rep(0, 3), Sigma = R, empirical = TRUE)
Beta <- c(.2, .3, .4)
y <- X %*% Beta + .64 * scale(rnorm(200))
results <- seBeta(X, y, Nobs = 200, alpha = .05, estimator = 'ADF')
print(results, digits = 3)

Simulated Sesame Street Data

Description

This is a simulated counterpart of part of the Sesame Street data presented by Stevens (1996, Appendix A) concerning the effect of the first year of the Sesame street series on the knowledge of 240 children in the age range 34 to 69 months. We will use the following variables: sex; site of child's origin; setting in which Sesame Street is watched; age; whether or not the child is encouraged to watch; Peabody metal age score; score on numbers test before, after and in a follow up measurement; and scores on knowledge of body parts, letters, forms, numbers, relations, and classifications, both before and after watching Sesame Street for a year.

Usage

data(sesamesim)

Format

A data frame with 240 rows and 21 variables.

Details

References

Stevens, J. (1996). Applied Multivariate Statistics for the Social Sciences. Mahwah NJ: Lawrence Erlbaum.

Simulated data about morality and politics in Denmark

Description

This is a simulated counterpart of data presented by Van Leeuwen and colleagues (2022) concerning associations between moral dispositions (measured using the Morality As Cooperation questionnaire, MAC; see Curry et al., 2019) and political orientation.

Usage

data(synthetic_dk)

Format

A data frame with 552 rows and 31 variables.

Details

References

Van Leeuwen, F., Van Lissa, C. J., Papakonstantinou, T., Petersen, M., & Curry, O. S. (2022, May 25). Morality as Cooperation, Politics as Conflict. <doi:10.31234/osf.io/wm6rk>

Curry, O. S., Chesters, M. J., & Van Lissa, C. J. (2019). Mapping morality with a compass: Testing the theory of 'morality-as-cooperation' with a new questionnaire. Journal of Research in Personality, 78, 106-124.

Simulated data about morality and politics in The Netherlands

Description

This is a simulated counterpart of data presented by Van Leeuwen and colleagues (2022) concerning associations between moral dispositions (measured using the Morality As Cooperation questionnaire, MAC; see Curry et al., 2019) and political orientation.

Usage

data(synthetic_nl)

Format

A data frame with 401 rows and 38 variables.

Details

References

Van Leeuwen, F., Van Lissa, C. J., Papakonstantinou, T., Petersen, M., & Curry, O. S. (2022, May 25). Morality as Cooperation, Politics as Conflict. <doi:10.31234/osf.io/wm6rk>

Curry, O. S., Chesters, M. J., & Van Lissa, C. J. (2019). Mapping morality with a compass: Testing the theory of ‘morality-as-cooperation’with a new questionnaire. Journal of Research in Personality, 78, 106-124.

Simulated data about morality and politics in the USA

Description

This is a simulated counterpart of data presented by Van Leeuwen and colleagues (2022) concerning associations between moral dispositions (measured using the Morality As Cooperation questionnaire, MAC; see Curry et al., 2019) and political orientation.

Usage

data(synthetic_us)

Format

A data frame with 518 rows and 33 variables.

Details

References

Van Leeuwen, F., Van Lissa, C. J., Papakonstantinou, T., Petersen, M., & Curry, O. S. (2022, May 25). Morality as Cooperation, Politics as Conflict. <doi:10.31234/osf.io/wm6rk>

Curry, O. S., Chesters, M. J., & Van Lissa, C. J. (2019). Mapping morality with a compass: Testing the theory of ‘morality-as-cooperation’with a new questionnaire. Journal of Research in Personality, 78, 106-124.

Student's t-test

Description

This function is a wrapper for the function t.test, which returns group-specific sample sizes and variances, in addition to the usual output of t.test.

Usage

t_test(x, ...)

Arguments

Details

This wrapper allows users to enjoy the functionality of bain with the familiar interface of the stats-function t.test.

For more documentation, see t.test.

Value

A list with class "t_test" containing the following components:

See Also

t.test

Examples

tmp <- t_test(extra ~ group, data = sleep)
tmp$n
tmp$v
tmp2 <- t_test(extra ~ group, data = sleep)
tmp2$n
tmp2$v
tmp <- t_test(Pair(sleep$extra[sleep$group == 1], sleep$extra[sleep$group == 2]) ~ 1)
tmp$n
tmp$v
t_test(sesamesim$postnumb)
tmp <- t_test(sesamesim$prenumb)
tmp$n
tmp$v
tmp2 <- t_test(sesamesim$prenumb)
tmp2$n
tmp2$v
tmp <- t_test(sesamesim$prenumb, sesamesim$postnumb)
tmp$n
tmp$v
tmp2 <- t_test(sesamesim$prenumb, sesamesim$postnumb)
tmp2$n
tmp2$v
tmp <- t_test(sesamesim$prenumb, sesamesim$postnumb, paired = TRUE)
tmp$n
tmp$v
tmp2 <- t_test(sesamesim$prenumb, sesamesim$postnumb, paired = TRUE)
tmp2$n
tmp2$v