pingouin.bayesfactor_pearson

pingouin.bayesfactor_pearson(r, n, tail='two-sided', method='ly', kappa=1.0)[source]

Bayes Factor of a Pearson correlation.

Parameters
rfloat

Pearson correlation coefficient.

nint

Sample size.

tailstr

Tail of the alternative hypothesis. Can be ‘two-sided’, ‘one-sided’, ‘greater’ or ‘less’. ‘greater’ corresponds to a positive correlation, ‘less’ to a negative correlation. If ‘one-sided’, the directionality is inferred based on the r value (= ‘greater’ if r > 0, ‘less’ if r < 0).

methodstr

Method to compute the Bayes Factor. Can be ‘ly’ (default) or ‘wetzels’. The former has an exact analytical solution, while the latter requires integral solving (and is therefore slower). ‘wetzels’ was the default in Pingouin <= 0.2.5. See notes for details.

kappafloat

Kappa factor. This is sometimes called the rscale parameter, and is only used when method is ‘ly’.

Returns
bfstr

Bayes Factor (BF10). The Bayes Factor quantifies the evidence in favour of the alternative hypothesis.

See also

corr

(Robust) correlation between two variables

pairwise_corr

Pairwise correlation between columns of a pandas DataFrame

bayesfactor_ttest

Bayes Factor of a T-test

bayesfactor_binom

Bayes Factor of a binomial test

Notes

If you would like to compute the Bayes Factor directly from the raw data instead of from the correlation coefficient, use the pingouin.corr() function.

The two-sided Wetzels Bayes Factor (also called JZS Bayes Factor) is calculated using the equation 13 and associated R code of Wetzels & Wagenmakers (2012):

\[\text{BF}_{10}(n, r) = \frac{\sqrt{n/2}}{\gamma(1/2)}* \int_{0}^{\infty}e((n-2)/2)* log(1+g)+(-(n-1)/2)log(1+(1-r^2)*g)+(-3/2)log(g)-n/2g\]

where \(n\) is the sample size, \(r\) is the Pearson correlation coefficient and \(g\) is is an auxiliary variable that is integrated out numerically. Since the Wetzels Bayes Factor requires solving an integral, it is slower than the analytical solution described below.

The two-sided Ly Bayes Factor (also called Jeffreys exact Bayes Factor) is calculated using equation 25 of Ly et al, 2016:

\[\text{BF}_{10;k}(n, r) = \frac{2^{\frac{k-2}{k}}\sqrt{\pi}} {\beta(\frac{1}{k}, \frac{1}{k})} \cdot \frac{\Gamma(\frac{2+k(n-1)}{2k})}{\Gamma(\frac{2+nk}{2k})} \cdot 2F_1(\frac{n-1}{2}, \frac{n-1}{2}, \frac{2+nk}{2k}, r^2)\]

The one-sided version is described in eq. 27 and 28 of Ly et al, 2016. Please take note that the one-sided test requires the mpmath package.

Results have been validated against JASP and the BayesFactor R package.

References

1

Ly, A., Verhagen, J. & Wagenmakers, E.-J. Harold Jeffreys’s default Bayes factor hypothesis tests: Explanation, extension, and application in psychology. J. Math. Psychol. 72, 19–32 (2016).

2

Wetzels, R. & Wagenmakers, E.-J. A default Bayesian hypothesis test for correlations and partial correlations. Psychon. Bull. Rev. 19, 1057–1064 (2012).

Examples

Bayes Factor of a Pearson correlation

>>> from pingouin import bayesfactor_pearson
>>> r, n = 0.6, 20
>>> bf = bayesfactor_pearson(r, n)
>>> print("Bayes Factor: %s" % bf)
Bayes Factor: 10.634

Compare to Wetzels method:

>>> bf = bayesfactor_pearson(r, n, method='wetzels')
>>> print("Bayes Factor: %s" % bf)
Bayes Factor: 8.221

One-sided test

>>> bf10pos = bayesfactor_pearson(r, n, tail='greater')
>>> bf10neg = bayesfactor_pearson(r, n, tail='less')
>>> print("BF-pos: %s, BF-neg: %s" % (bf10pos, bf10neg))
BF-pos: 21.185, BF-neg: 0.082

We can also only pass tail='one-sided' and Pingouin will automatically infer the directionality of the test based on the r value.

>>> print("BF: %s" % bayesfactor_pearson(r, n, tail='one-sided'))
BF: 21.185