Stable version: CRAN page - Package NEWS (including version changes)

Development version: Development page - Development package NEWS- Introductory material
- Performing analyses
- One-sample (and two-sample paired), and manipulating Bayes factor objects
- Two independent samples
- Meta-analytic t tests (0.9.8+)
- ANOVA, fixed-effects
- ANOVA, mixed models (including repeated measures)
- Regression
- General linear models: mixing continuous and categorical covariates
- Linear correlations
- Tests of single proportions (0.9.9+)
- Contingency Tables (0.9.9+)

- Additional tips and tricks (0.9.4+)
- References

The `BayesFactor`

package enables the computation of Bayes
factors in standard designs, such as one- and two- sample designs, ANOVA
designs, and regression. The Bayes factors are based on work spread
across several papers. This document is designed to show users how to
compute Bayes factors using the package by example. It is not designed
to present the models used in the comparisons in detail; for that, see
the `BayesFactor`

help and especially the references listed
in this manual. Complete references are given at the end of this document.

If you need help or think you’ve found a bug, please use the links at
the top of this document to contact the developers. When asking a
question or reporting a bug, please send example code and data, the
exact errors you’re seeing (a cut-and-paste from the R console will
work) and instructions for reproducing it. Also, report the output of
`BFInfo()`

and `sessionInfo()`

, and let us know
what operating system you’re running.

The `BayesFactor`

package must be installed and loaded
before it can be used. Installing the package can be done in several
ways and will not be covered here. Once it is installed, use the
`library`

function to load it:

This command will make the `BayesFactor`

package ready to
use.

The table below lists some of the functions in the
`BayesFactor`

package that will be demonstrated in this
manual. For more complete help on the use of these functions, see the
corresponding `help()`

page in R.

Function | Description |
---|---|

`ttestBF` |
Bayes factors for one- and two- sample designs |

`anovaBF` |
Bayes factors comparing many ANOVA models |

`regressionBF` |
Bayes factors comparing many linear regression models |

`generalTestBF` |
Bayes factors for all restrictions on a full model (0.9.4+) |

`lmBF` |
Bayes factors for specific linear models (ANOVA or regression) |

`correlationBF` |
Bayes factors for linear correlations |

`proportionBF` |
Bayes factors for tests of single proportions |

`contingencyTableBF` |
Bayes factors for contingency tables |

`posterior` |
Sample from the posterior distribution of the numerator of a Bayes factor object |

`recompute` |
Recompute a Bayes factor or MCMC chain, possibly increasing the precision of the estimate |

`compare` |
Compare two models; typically used to compare two models in
`BayesFactor` MCMC objects |

The t test section below has examples showing how to manipulate Bayes
factor objects, but all these functions will work with Bayes factors
generated from any function in the `BayesFactor`

package.

Function | Description |
---|---|

`/` |
Divide two Bayes factor objects to create new model comparisons, or
invert with `1/` |

`t` |
“Flip” (transpose) a Bayes factor object |

`c` |
Concatenate two Bayes factor objects together, assuming they have the same denominator |

`[` |
Use indexing to select a subset of the Bayes factors |

`plot` |
plot a Bayes factor object |

`sort` |
Sort a Bayes factor object |

`is.na` |
Determine whether a Bayes factor object contains missing values |

`head` ,`tail` |
Return the `n` highest or lowest Bayes factor in an
object |

`max` , `min` |
Return the highest or lowest Bayes factor in an object |

`which.max` ,`which.min` |
Return the index of the highest or lowest Bayes factor |

`as.vector` |
Convert to a simple vector (denominator will be lost!) |

`as.data.frame` |
Convert to data.frame (denominator will be lost!) |

The `ttestBF`

function is used to obtain Bayes factors
corresponding to tests of a single sample’s mean, or tests that two
independent samples have the same mean.

We use the `sleep`

data set in R to demonstrate a
one-sample t test. This is a paired design; for details about the data
set, see `?sleep`

. One way of analyzing these data is to
compute difference scores by subtracting a participant’s score in one
condition from their score in the other:

```
data(sleep)
## Compute difference scores
diffScores = sleep$extra[1:10] - sleep$extra[11:20]
## Traditional two-tailed t test
t.test(diffScores)
```

```
##
## One Sample t-test
##
## data: diffScores
## t = -4, df = 9, p-value = 0.003
## alternative hypothesis: true mean is not equal to 0
## 95 percent confidence interval:
## -2.46 -0.70
## sample estimates:
## mean of x
## -1.58
```

We can do a Bayesian version of this analysis using the
`ttestBF`

function, which performs the “JZS” t test described
by Rouder, Speckman, Sun, Morey, and Iverson
(2009). In this model, the true standardized difference \(\delta=(\mu-\mu_0)/\sigma_\epsilon\) is
assumed to be 0 under the null hypothesis, and \(\text{Cauchy}(\text{scale}=r)\) under the
alternative. The default \(r\) scale in
`BayesFactor`

for t tests is \(\sqrt{2}/2\). See `?ttestBF`

for
more details.

```
bf = ttestBF(x = diffScores)
## Equivalently:
## bf = ttestBF(x = sleep$extra[1:10],y=sleep$extra[11:20], paired=TRUE)
bf
```

```
## Bayes factor analysis
## --------------
## [1] Alt., r=0.707 : 17.3 ±0%
##
## Against denominator:
## Null, mu = 0
## ---
## Bayes factor type: BFoneSample, JZS
```

The `bf`

object contains the Bayes factor, and shows the
numerator and denominator models for the Bayes factor comparison. In our
case, the Bayes factor for the comparison of the alternative versus the
null is 17.259. After the Bayes factor is a proportional error estimate
on the Bayes factor.

There are a number of operations we can perform on our Bayes factor, such as taking the reciprocal:

```
## Bayes factor analysis
## --------------
## [1] Null, mu=0 : 0.0579 ±0%
##
## Against denominator:
## Alternative, r = 0.707106781186548, mu =/= 0
## ---
## Bayes factor type: BFoneSample, JZS
```

or sampling from the posterior of the numerator model:

```
##
## Iterations = 1:1000
## Thinning interval = 1
## Number of chains = 1
## Sample size per chain = 1000
##
## 1. Empirical mean and standard deviation for each variable,
## plus standard error of the mean:
##
## Mean SD Naive SE Time-series SE
## mu -1.42 0.436 0.0138 0.0154
## sig2 2.02 1.157 0.0366 0.0395
## delta -1.11 0.427 0.0135 0.0162
## g 6.26 58.623 1.8538 1.8538
##
## 2. Quantiles for each variable:
##
## 2.5% 25% 50% 75% 97.5%
## mu -2.289 -1.705 -1.43 -1.141 -0.597
## sig2 0.744 1.270 1.69 2.446 5.223
## delta -1.973 -1.383 -1.08 -0.813 -0.347
## g 0.176 0.592 1.13 2.928 33.734
```

The `posterior`

function returns a object of type
`BFmcmc`

, which inherits the methods of the `mcmc`

class from the `coda`

package. We can thus use `summary`

, `plot`

,
and other useful methods on the result of `posterior`

. If we
were unhappy with the number of iterations we sampled for
`chains`

, we can `recompute`

with more iterations,
and then `plot`

the results:

Directional hypotheses can also be tested with `ttestBF`

(Morey & Rouder, 2011). The argument
`nullInterval`

can be passed as a vector of length 2, and
defines an interval to compare to the point null. If null interval is
defined, *two* Bayes factors are returned: the Bayes factor of
the null interval against the alternative, and the Bayes factor of the
*complement* of the interval to the point null.

Suppose, for instance, we wanted to test the one-sided hypotheses
that \(\delta<0\) versus the point
null. We set `nullInterval`

to `c(-Inf,0)`

:

```
## Bayes factor analysis
## --------------
## [1] Alt., r=0.707 -Inf<d<0 : 34.4 ±0%
## [2] Alt., r=0.707 !(-Inf<d<0) : 0.101 ±0%
##
## Against denominator:
## Null, mu = 0
## ---
## Bayes factor type: BFoneSample, JZS
```

We may not be interested in tests against the point null. If we are
interested in the Bayes factor test that \(\delta<0\) versus \(\delta>0\) we can compute it using the
result above. Since the object contains two Bayes factors, both with the
same denominator, and \[
\left.\frac{A}{C}\middle/\frac{B}{C}\right. = \frac{A}{B},
\] we can divide the two Bayes factors in `bfInferval`

to obtain the desired test:

```
## Bayes factor analysis
## --------------
## [1] Alt., r=0.707 -Inf<d<0 : 341 ±0%
##
## Against denominator:
## Alternative, r = 0.707106781186548, mu =/= 0 !(-Inf<d<0)
## ---
## Bayes factor type: BFoneSample, JZS
```

The Bayes factor is about 340.

When we have multiple Bayes factors that all have the same
denominator, we can concatenate them into one object using the
`c`

function. Since `bf`

and
`bfInterval`

both share the point null denominator, we can do
this:

```
## Bayes factor analysis
## --------------
## [1] Alt., r=0.707 : 17.3 ±0%
## [2] Alt., r=0.707 -Inf<d<0 : 34.4 ±0%
## [3] Alt., r=0.707 !(-Inf<d<0) : 0.101 ±0%
##
## Against denominator:
## Null, mu = 0
## ---
## Bayes factor type: BFoneSample, JZS
```

The object `allbf`

now contains three Bayes factors, all
of which share the same denominator. If you try to concatenate Bayes
factors that do *not* share the same denominator,
`BayesFactor`

will return an error.

When you have a Bayes factor object with several numerators, there are several interesting ways to manipulate them. For instance, we can plot the Bayes factor object to obtain a graphical representation of the Bayes factors:

We can also divide a Bayes factor object by itself — or by a subset of itself — to obtain pairwise comparisons:

```
## denominator
## numerator Alt., r=0.707 Alt., r=0.707 -Inf<d<0
## Alt., r=0.707 1.00000 0.50146
## Alt., r=0.707 -Inf<d<0 1.99416 1.00000
## Alt., r=0.707 !(-Inf<d<0) 0.00584 0.00293
## denominator
## numerator Alt., r=0.707 !(-Inf<d<0)
## Alt., r=0.707 171
## Alt., r=0.707 -Inf<d<0 341
## Alt., r=0.707 !(-Inf<d<0) 1
```

The resulting object is of type `BFBayesFactorList`

, and
is a list of Bayes factor comparisons all of the same numerators
compared to different denominators. The resulting matrix can be
subsetted to return individual Bayes factor objects, or new
`BFBayesFactorList`

s:

```
## Bayes factor analysis
## --------------
## [1] Alt., r=0.707 : 0.501 ±0%
## [2] Alt., r=0.707 -Inf<d<0 : 1 ±0%
## [3] Alt., r=0.707 !(-Inf<d<0) : 0.00293 ±0%
##
## Against denominator:
## Alternative, r = 0.707106781186548, mu =/= 0 -Inf<d<0
## ---
## Bayes factor type: BFoneSample, JZS
```

```
## denominator
## numerator Alt., r=0.707 Alt., r=0.707 -Inf<d<0 Alt., r=0.707 !(-Inf<d<0)
## Alt., r=0.707 1 0.501 171
```

and they can also be transposed:

```
## denominator
## numerator Alt., r=0.707 Alt., r=0.707 -Inf<d<0
## Alt., r=0.707 1.00000 0.50146
## Alt., r=0.707 -Inf<d<0 1.99416 1.00000
## Alt., r=0.707 !(-Inf<d<0) 0.00584 0.00293
```

```
## denominator
## numerator Alt., r=0.707 Alt., r=0.707 -Inf<d<0
## Alt., r=0.707 1.00 0.501
## Alt., r=0.707 -Inf<d<0 1.99 1.000
## denominator
## numerator Alt., r=0.707 !(-Inf<d<0)
## Alt., r=0.707 171
## Alt., r=0.707 -Inf<d<0 341
```

If these values are desired in matrix form, the
`as.matrix`

function can be used to obtain a matrix.