Package 'BFpack'

BFpack: Flexible Bayes factor testing of scientific expectations

Description

The R package BFpack provides tools for exploratory and confirmatory Bayesian hypothesis testing using Bayes factors and posterior probabilities under common statistical models. The main function 'BF' needs a fitted model 'x' as input argument. Depending on the class of the fitted model, a standard hypothesis test is executed by default. For example, if 'x' is a fitted regression model of class 'lm' then posterior probabilities are computed of whether each separate coefficient is zero, negative, or positive (assuming equal prior probabilities). If one has specific hypotheses with equality and/or order constraints on the parameters under the fitted model 'x' then these can be formulated using the 'hypothesis' argument (a character string), possibly together prior probabilities for the hypotheses via the 'prior' argument (default all hypotheses are equally likely a priori), and the 'complement' argument which is a logical stating whether the complement hypotheses should be included in the case ('TRUE' by default).

Use compilation for Fortran functions

References

Mulder, J., D.R. Williams, Gu, X., A. Tomarken, F. Böing-Messing, J.A.O.C. Olsson-Collentine, Marlyne Meyerink, J. Menke, J.-P. Fox, Y. Rosseel, E.J. Wagenmakers, H. Hoijtink., and van Lissa, C. (submitted). BFpack: Flexible Bayes Factor Testing of Scientific Theories in R. https://arxiv.org/abs/1911.07728

Mulder, J., van Lissa, C., Gu, X., Olsson-Collentine, A., Boeing-Messing, F., Williams, D. R., Fox, J.-P., Menke, J., et al. (2019). BFpack: Flexible Bayes Factor Testing of Scientific Expectations. (Version 0.2.1) https://CRAN.R-project.org/package=BFpack

Examples

## Not run: 
# EXAMPLE 1. One-sample t test
ttest1 <- t_test(therapeutic, mu = 5)
print(ttest1)
# confirmatory Bayesian one sample t test
BF1 <- BF(ttest1, hypothesis = "mu = 5")
summary(BF1)
# exploratory Bayesian one sample t test
BF(ttest1)

# EXAMPLE 2. ANOVA
aov1 <- aov(price ~ anchor * motivation,data = tvprices)
BF1 <- BF(aov1, hypothesis = "anchorrounded = motivationlow;
                              anchorrounded < motivationlow")
summary(BF1)

# EXAMPLE 3. Logistic regression
fit <- glm(sent ~ ztrust + zfWHR + zAfro + glasses + attract + maturity +
   tattoos, family = binomial(), data = wilson)
BF1 <- BF(fit, hypothesis = "ztrust > zfWHR > 0;
                             ztrust > 0 & zfWHR = 0")
summary(BF1)

# EXAMPLE 4. Correlation analysis
set.seed(123)
cor1 <- cor_test(memory[1:20,1:3])
BF1 <- BF(cor1)
summary(BF1)
BF2 <- BF(cor1, hypothesis = "Wmn_with_Im > Wmn_with_Del > 0;
                              Wmn_with_Im = Wmn_with_Del = 0")
summary(BF2)

## End(Not run)

---

Actors from a small hypothetical network

Description

The related data files 'events', 'same_location', 'same_culture' contain information on the event sequence and the two event statistics respectively.

Usage

data(actors)

Format

dataframe (25 rows, 4 columns)

actors$id	integer	ID of the employee, corresponding to the sender and receiver IDs in the events dataframe
actors$location	numeric	Location of the actor, ranging from 1-4
actors$culture	character	Categorical variable, indicating the culture of the employee

---

Multiple Sources of Attentional Dysfunction in Adults With Tourette's Syndrome

Description

Data from a psychological study comparing attentional performances of Tourette's syndrome (TS) patients, ADHD patients, and controls. These data were simulated using the sufficient statistics from Silverstein, Como, Palumbo, West, and Osborn (1995).

Usage

data(attention)

Format

A data.frame with 51 rows and 2 columns.

Details

accuracy	numeric	Participant's accuracy in the attentional task
group	factor	Participant's group membership (TS patient, ADHD patient, or control)

References

Silverstein, S. M., Como, P. G., Palumbo, D. R., West, L. L., & Osborn, L. M. (1995). Multiple sources of attentional dysfunction in adults with Tourette's syndrome: Comparison with attention deficit-hyperactivity disorder. Neuropsychology, 9(2), 157-164. doi:10.1037/0894-4105.9.2.157

---

Bartlett Test of Homogeneity of Variances

Description

Performs Bartlett's test of the null that the variances in each of the groups (samples) are the same.

Usage

bartlett_test(x, g, ...)

## Default S3 method:
bartlett_test(x, g, ...)

Arguments

x	a numeric vector of data values, or a list of numeric data vectors representing the respective samples, or fitted linear model objects (inheriting from class "lm").
g	a vector or factor object giving the group for the corresponding elements of x. Ignored if x is a list.
...	further arguments to be passed to or from methods.

Details

x must be a numeric data vector, and g must be a vector or factor object of the same length as x giving the group for the corresponding elements of x.

Value

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

statistic	Bartlett's K-squared test statistic.
parameter	the degrees of freedom of the approximate chi-squared distribution of the test statistic.
p.value	the p-value of the test.
conf.int	a confidence interval for the mean appropriate to the specified alternative hypothesis.
method	the character string "Bartlett test of homogeneity of variances".
data.name	a character string giving the names of the data.
vars	the sample variances across groups (samples).
n	the number of observations per group (sample)

Bain t_test

In order to allow users to enjoy the functionality of bain with the familiar stats-function bartlett.test, we have had to make minor changes to the function bartlett.test.default. All rights to, and credit for, the function bartlett.test.default belong to the R Core Team, as indicated in the original license below. We make no claims to copyright and incur no liability with regard to the changes implemented in bartlett_test.

This the original copyright notice by the R core team: File src/library/stats/R/bartlett_test.R Part of the R package, https://www.R-project.org

Copyright (C) 1995-2015 The R Core Team

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is available at https://www.R-project.org/Licenses/

References

Bartlett, M. S. (1937). Properties of sufficiency and statistical tests. Proceedings of the Royal Society of London Series A 160, 268–282. DOI: 10.1098/rspa.1937.0109.

Examples

require(graphics)

plot(count ~ spray, data = InsectSprays)
bartlett_test(InsectSprays$count, InsectSprays$spray)

---

Bayes factors for Bayesian exploratory and confirmatory hypothesis testing

Description

The BF function can be used for hypothesis testing and model selection using the Bayes factor. By default exploratory hypothesis tests are performed of whether each model parameter equals zero, is negative, or is positive. Confirmatory hypothesis tests can be executed by specifying hypotheses with equality and/or order constraints on the parameters of interest.

Usage

BF(x, hypothesis, prior.hyp, complement, Sigma, n, ...)

Arguments

x	An R object containing the outcome of a statistical analysis. An R object containing the outcome of a statistical analysis. Currently, the following objects can be processed: t_test(), bartlett_test(), lm(), aov(), manova(), cor_test(), lmer() (only for testing random intercep variances), glm(), coxph(), survreg(), polr(), zeroinfl(), rma(), or named vector objects. In the case x is a named vector, the arguments Sigma and n are also needed. See vignettes for elaborations.
hypothesis	A character string containing the constrained (informative) hypotheses to evaluate in a confirmatory test. The default is NULL, which will result in standard exploratory testing under the model x.
prior.hyp	A vector specifying the prior probabilities of the hypotheses. The default is NULL which will specify equal prior probabilities.
complement	a logical specifying whether the complement should be added to the tested hypothesis under hypothesis.
Sigma	An approximate posterior covariance matrix (e.g,. error covariance matrix) of the parameters of interest. This argument is only required when x is a named vector.
n	The (effective) sample size that was used to acquire the estimates in the named vector x and the error covariance matrix Sigma. This argument is only required when x is a named vector.
...	Parameters passed to and from other functions.

Details

The function requires a fitted modeling object. Current analyses that are supported: t_test, bartlett_test, aov, manova, lm, mlm, glm, hetcor, lmer, coxph, survreg, zeroinfl, rma and polr.

For testing parameters from the results of t_test(), lm(), aov(), manova(), and bartlett_test(), hypothesis testing is done using adjusted fractional Bayes factors are computed (using minimal fractions). For testing measures of association (e.g., correlations) via cor_test(), Bayes factors are computed using joint uniform priors under the correlation matrices. For testing intraclass correlations (random intercept variances) via lmer(), Bayes factors are computed using uniform priors for the intraclass correlations. For all other tests, approximate adjusted fractional Bayes factors (with minimal fractions) are computed using Gaussian approximations, similar as a classical Wald test.

Value

The output is an object of class BF. The object has elements:

• BFtu_exploratory: The Bayes factors of the constrained hypotheses against the unconstrained hypothesis in the exploratory test.

• PHP_exploratory: The posterior probabilities of the constrained hypotheses in the exploratory test.

• BFtu_confirmatory: The Bayes factors of the constrained hypotheses against the unconstrained hypothesis in the confirmatory test using the hypothesis argument.

• PHP_confirmatory: The posterior probabilities of the constrained hypotheses in the confirmatory test using the hypothesis argument.

• BFmatrix_confirmatory: The evidence matrix which contains the Bayes factors between all possible pairs of hypotheses in the confirmatory test.

• BFtable_confirmatory: The Specification table (output when printing the summary of a BF for a confirmatory test) which contains the different elements of the extended Savage Dickey density ratio where

  • The first column 'complex=' quantifies the relative complexity of the equality constraints of a hypothesis (the prior density at the equality constraints in the extended Savage Dickey density ratio).

  • The second column 'complex>' quantifies the relative complexity of the order constraints of a hypothesis (the prior probability of the order constraints in the extended Savage Dickey density ratio).

  • The third column 'fit=' quantifies the relative fit of the equality constraints of a hypothesis (the posterior density at the equality constraints in the extended Savage Dickey density ratio).

  • The fourth column 'fit>' quantifies the relative fit of the order constraints of a hypothesis (the posterior probability of the order constraints in the extended Savage Dickey density ratio)

  • The fifth column 'BF=' contains the Bayes factor of the equality constraints against the unconstrained hypothesis.

  • The sixth column 'BF>' contains the Bayes factor of the order constraints against the unconstrained hypothesis.

  • The seveth column 'BF' contains the Bayes factor of the constrained hypothesis against the unconstrained hypothesis.

  • The eigth column 'BF=' contains the posterior probabilities of the constrained hypotheses.

• prior: The prior probabilities of the constrained hypotheses in a confirmatory test.

• hypotheses: The tested constrained hypotheses in a confirmatory test.

• estimates: The unconstrained estimates.

• model: The input model x.

• call: The call of the BF function.

References

Mulder, J., D.R. Williams, Gu, X., A. Tomarken, F. Böing-Messing, J.A.O.C. Olsson-Collentine, Marlyne Meyerink, J. Menke, J.-P. Fox, Y. Rosseel, E.J. Wagenmakers, H. Hoijtink., and van Lissa, C. (submitted). BFpack: Flexible Bayes Factor Testing of Scientific Theories in R.

Examples

# EXAMPLE 1. One-sample t test
ttest1 <- bain::t_test(therapeutic, mu = 5)
print(ttest1)
# confirmatory Bayesian one sample t test
BF1 <- BF(ttest1, hypothesis = "mu = 5")
summary(BF1)
# exploratory Bayesian one sample t test
BF(ttest1)

# EXAMPLE 2. ANOVA
aov1 <- aov(price ~ anchor * motivation, data = tvprices)
# check the names of the model parameters
names(aov1$coefficients)
BF1 <- BF(aov1, hypothesis = "anchorrounded = motivationlow;
                              anchorrounded < motivationlow;
                              anchorrounded > motivationlow")
summary(BF1)

# EXAMPLE 3. Logistic regression
fit <- glm(sent ~ ztrust + zfWHR + zAfro + glasses + attract + maturity +
   tattoos, family = binomial(), data = wilson)
BF1 <- BF(fit, hypothesis = "ztrust > (zfWHR, zAfro) > 0;
                             ztrust > 0 & zfWHR=zAfro= 0")
summary(BF1)

# EXAMPLE 4. Correlation analysis
set.seed(123)
cor1 <- cor_test(memory[1:20,1:3])
BF1 <- BF(cor1)
summary(BF1)
BF2 <- BF(cor1, hypothesis = "Wmn_with_Im > Wmn_with_Del > 0;
                              Wmn_with_Im = Wmn_with_Del = 0")
summary(BF2)

# EXAMPLE 5. Bayes factor testing on a named vector
# We illustrate the computation of Bayes factors using a named vector
# as input on a Poisson regression model
poisson1 <- glm(formula = breaks ~ wool + tension,
  data = datasets::warpbreaks, family = poisson)
# extract estimates, error covariance matrix, and sample size,
# from fitted object
estimates <- poisson1$coefficients
covmatrix <- vcov(poisson1)
samplesize <- nobs(poisson1)
# compute Bayes factors on equal/order constrained hypotheses on coefficients
BF1 <- BF(estimates, Sigma = covmatrix, n = samplesize, hypothesis =
"woolB > tensionM > tensionH; woolB = tensionM = tensionH")
summary(BF1)

---

Bayesian correlation analysis

Description

Estimate the unconstrained posterior for the correlations using a joint uniform prior.

Usage

cor_test(..., formula = NULL, iter = 5000)

Arguments

...	matrices (or data frames) of dimensions n (observations) by p (variables) for different groups (in case of multiple matrices or data frames).
formula	an object of class formula. This allows for including control variables in the model (e.g., ~ education).
iter	number of iterations from posterior (default is 5000).

Value

list of class cor_test:

• meanF posterior means of Fisher transform correlations

• covmF posterior covariance matrix of Fisher transformed correlations

• correstimates posterior estimates of correlation coefficients

• corrdraws list of posterior draws of correlation matrices per group

• corrnames names of all correlations

Examples

# Bayesian correlation analysis of the 6 variables in 'memory' object
# we consider a correlation analysis of the first three variable of the memory data.
fit <- cor_test(BFpack::memory[,1:3])

# Bayesian correlation of variables in memory object in BFpack while controlling
# for the Cat variable
fit <- cor_test(BFpack::memory[,c(1:4)],formula = ~ Cat)

# Bayesian correlation analysis of first three variables in memory data
# for two different groups
HC <- subset(BFpack::memory[,c(1:3,7)], Group == "HC")[,-4]
SZ <- subset(BFpack::memory[,c(1:3,7)], Group == "SZ")[,-4]
fit <- cor_test(HC,SZ)

---

fMRI data

Description

fMRI data assessing relation between individual differences in the ability to recognize faces and cars and thickness of the superficial, middle, and deep layers of the fusiform face area, as assessed by high-resolution fMRI recognition (Williams et al, 2019, under review)

Usage

data(fmri)

Format

A data.frame with 13 rows and 6 columns.

Details

Subject	numeric	Particicpant ID number
Face	numeric	Standardized score on face recognition battery
Vehicle	numeric	Standardized score on vehicle recognition battery
Superficial	numeric	Depth in mm of superficial layer of FFA
Middle	numeric	Depth in mm of middle layer of FFA
Bform	numeric	Depth in mm of deep layer of FFA

References

McGuigin, R.W., Newton, A.T., Tamber-Rosenau, B., Tomarken, A.J, & Gauthier, I. (under review). Thickness of deep layers in the fusiform face area predicts face recognition.

---

Memory data on health and schizophrenic patients

Description

Data set from study assessing differences between schizophrenic patients and healthy control participants in patterns of correlations among 6 verbal memory tasks (Ichinose et al., 2019).

Im	numeric	Percent correct on immediate recall of 3 word lists
Del	numeric	Percent correct on delayed recall of 3 word lists
Wmn	numeric	Number correct on letter-number span test of auditory working memory
Cat	numeric	Number correct on category fluency task
Fas	numeric	Number correct on letter fluency task
Rat	numeric	Number correct on remote associates task
Group	factor	Participant Group (HC = Healthy Control; SZ = Schizophrenia)

Usage

data(memory)

Format

A data.frame with 40 rows and 8 columns.

References

Ichinose, M.C., Han, G., Polyn, S., Park, S., & Tomarken, A.J. (2019). Verbal memory performance discordance in schizophrenia: A reflection of cognitive dysconnectivity. Unpublished manuscript.

---

A sequence of innovation-related e-mail messages

Description

A time-ordered sequence of 247 communication messages between 25 actors.

Usage

data(relevents)

Format

dataframe (247 rows, 3 columns)

relevents$time	numeric	Time of the e-mail message, in seconds since onset of the observation
relevents$sender	integer	ID of the sender, corresponding to the employee IDs in the actors dataframe
relevents$receiver	integer	ID of the receiver

Details

The related data files 'actors', 'same_location', 'same_culture' contain information on the actors and three event statistics respectively.

---

Same culture event statistic

Description

A matrix coding whether senders of events (in the rows) and receivers of events (in the column) have the background culture. Related to the 'events' data object, that contains a relational event sequence, and the 'actors' object, that contains information on the 25 actors involved in the relational event sequence.

Usage

data(same_culture)

Format

dataframe (25 rows, 4 columns)

same_culture	integer	Event statistic. Matrix with senders in the rows and receivers in the columns. The event statistic is 1 if sender and receiver have the same culture and 0 otherwise.

---

Same location event statistic

Description

A matrix coding whether senders of events (in the rows) and receivers of events (in the column) have the same location. Related to the 'events' data object, that contains a relational event sequence, and the 'actors' object, that contains information on the 25 actors involved in the relational event sequence.

Usage

data(same_location)

Format

dataframe (25 rows, 4 columns)

same_location	integer	Event statistic. Matrix with senders in the rows and receivers in the columns. The event statistic is 1 if sender and receiver have the same location and 0 otherwise.

---

Wason task performance and morality

Description

Data from an experimental study, using the Wason selection task (Wason 1968) to examine whether humans have cognitive adaptations for detecting violations of rules in multiple moral domains. Moral domains are operationalized in terms of the five domains of the Moral Foundations Questionnaire (Graham et al. 2011). These data were simulated using the R-package synthpop, based on the characteristics of the original data.

Usage

data(sivan)

Format

A data.frame with 887 rows and 12 columns.

Details

sex	factor	Participant sex
age	integer	Participant age
nationality	factor	Participant nationality
politics	integer	How would you define your political opinions? Likert type scale, from 1 (Liberal) to 6 (Conservative)
WasonOrder	factor	Was the Wason task presented before, or after the MFQ?
Harm	numeric	MFQ harm domain.
Fairness	numeric	MFQ fairness domain.
Loyalty	numeric	MFQ loyalty domain.
Purity	numeric	MFQ purity domain.
Tasktype	ordered	How was the Wason task framed?
GotRight	factor	Did the participant give the correct answer to the Wason task?

References

Sivan, J., Curry, O. S., & Van Lissa, C. J. (2018). Excavating the Foundations: Cognitive Adaptations for Multiple Moral Domains. Evolutionary Psychological Science, 4(4), 408–419. doi:10.1007/s40806-018-0154-8

---

Data come from an experimental study (Rosa, Rosa, Sarner, and Barrett, 1998) that were also used in Howell (2012, p.196). An experiment was conducted to investigate if Therapeutic Touch practitioners who were blindfolded can effectively identify which of their hands is below the experimenter¡¯s. Twenty-eight practitioners were involved and tested 10 times in the experiment. Researchers expected an average of 5 correct answers from each practitioner as it is the number by chance if they do not outperform others.

Description

correct	integer	How many correct answers are from each practitioner)

Usage

data(therapeutic)

Format

A data.frame with 22 rows and 1 column.

References

Howell, D. (2012). Statistical methods for psychology (8th ed.). Belmont, CA: Cengage Learning.

---

Trends in International Mathematics and Science Study (TIMSS) 2011-2015

Description

A stratified sample was drawn by country and school to obtain a balanced sample of p = 15 grade-4 students per school for each of four countries (The Netherlands (NL), Croatia (HR), Germany (DE), and Denmark (DK)) and two measurement occasions (2011, 2015). Achievement scores (first plausible value) of overall mathematics were considered. Performances of fourth and eight graders from more than 50 participating countries around the world can be found at (https://www.iea.nl/timss) The TIMSS achievement scale is centered at 500 and the standard deviation is equal to 100 scale score points. The TIMSS data set has a three-level structure, where students are nested within classrooms/schools, and the classrooms/schools are nested within countries. Only one classroom was sampled per school. Changes in the mathematics achievement can be investigated by examining the grouping of students in schools across countries. Changes in country-specific intraclass correlation coefficient from 2011 to 2015, representing heterogeneity in mathematic achievements within and between schools across years, can be tested. When detecting a decrease in average performance together with an increase of the intraclass correlation, a subset of schools performed worse. For a constant intraclass correlation across years the drop in performance applied to the entire population of schools. For different countries, changes in the intraclass correlation across years can be tested concurrently to examine also differences across countries.

Usage

data(timssICC)

Format

A data.frame with 16770 rows and 15 columns.

Details

math	numeric	math score child
groupNL11	numeric	Indicator for child from NL in 2011
groupNL15	numeric	Indicator for child from NL in 2015
groupHR11	numeric	Indicator for child from HR in 2011
groupHR15	numeric	Indicator for child from HR in 2015
groupDE11	numeric	Indicator for child from DE in 2011
groupDE15	numeric	Indicator for child from DE in 2015
groupDR11	numeric	Indicator for child from DK in 2011
groupDR15	numeric	Indicator for child from DK in 2015
gender	numeric	Female=0,Male=1
weight	numeric	Child sampling weight
yeargender	numeric	Interaction for occassion and gender
lln	numeric	total number of children in school-class
groupschool	factor	Nested indicator for school in country
schoolID	factor	Unique indicator for school

References

Mulder, J. & Fox, J.-P. (2019). Bayes factor testing of multiple intraclass correlations. Bayesian Analysis. 14, 2, p. 521-552.

---

Precision of the Anchor Influences the Amount of Adjustment

Description

Data from an experimental study where participants have to guess the price of a plasma tv. There were two experimental conditions. These data were simulated using the sufficient statistics from Janiszewski & Uy (2008).

Usage

data(tvprices)

Format

A data.frame with 59 rows and 3 columns.

Details

price	numeric	Participant z-scores of price
anchor	factor	Participant anchor
motivation	factor	motivation to change

References

Janiszewski, C., & Uy, D. (2008). Precision of the anchor influences the amount of adjustment. Psychological Science, 19(2), 121–127. doi:10.1111/j.1467-9280.2008.02057.x

---

Facial trustworthiness and criminal sentencing

Description

Data from a correlational study in which the correlation between ratings of facial trustworthiness of inmates was correlated with whether they had received the death penalty or not (wilson and Rule, 2015). These data were simulated using the R-package synthpop, based on the characteristics of the original data.

Usage

data(wilson)

Format

A data.frame with 742 rows and 13 columns.

Details

stim	integer	Stimulus Number
sent	integer	Sentence: 1 = Death, 0 = Life
race	integer	Race: 1 = White, -1 = Black
glasses	integer	Glasses: 1 = Yes, 0 = No
tattoos	integer	Tattoos: 1 = Yes, 0 = No
ztrust	numeric	Trustworthiness
trust_2nd	numeric	Trustworthiness ratings with 2nd control group; Death targets are same as in primary analysis, Life targets are different.
afro	numeric	raw Afrocentricity ratings.
zAfro	numeric	Afrocentricity ratings normalized within target race. Analyses in paper were done with this variable.
attract	numeric	Attractiveness
fWHR	numeric	facial width-to-height
afWHR	numeric	fWHR normalized within target race. Analyses in paper were done with this variable
maturity	numeric	Maturity

References

Wilson, J. P., & Rule, N. O. (2015). Facial Trustworthiness Predicts Extreme Criminal-Sentencing Outcomes. Psychological Science, 26(8), 1325–1331. doi: 10.1177/0956797615590992

---