pingouin.bayesfactor_pearson#

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

Bayes Factor of a Pearson correlation.

Parameters:

rfloat: Pearson correlation coefficient.
nint: Sample size.
alternativestring: Defines the alternative hypothesis, or tail of the correlation. Must be one of “two-sided” (default), “greater” or “less”. Both “greater” and “less” return a one-sided p-value. “greater” tests against the alternative hypothesis that the correlation is positive (greater than zero), “less” tests against the hypothesis that the correlation is negative.
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:

bffloat: 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

To compute the Bayes Factor directly from the raw data, 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 [1]:

\[\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 [2]:

\[\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: %.3f" % bf)
Bayes Factor: 10.634

Compare to Wetzels method:

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

One-sided test

>>> bf10pos = bayesfactor_pearson(r, n, alternative='greater')
>>> bf10neg = bayesfactor_pearson(r, n, alternative='less')
>>> print("BF-pos: %.3f, BF-neg: %.3f" % (bf10pos, bf10neg))
BF-pos: 21.185, BF-neg: 0.082