pingouin.power_corr#

pingouin.power_corr(r=None, n=None, power=None, alpha=0.05, alternative='two-sided')[source]#

Evaluate power, sample size, correlation coefficient or significance level of a correlation test.

Parameters:
rfloat

Correlation coefficient.

nint

Number of observations (sample size).

powerfloat

Test power (= 1 - type II error).

alphafloat

Significance level (type I error probability). The default is 0.05.

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.

Notes

Exactly ONE of the parameters r, n, power and alpha must be passed as None, and that parameter is determined from the others.

alpha has a default value of 0.05 so None must be explicitly passed if you want to compute it.

scipy.optimize.brenth() is used to solve power equations for other variables (i.e. sample size, effect size, or significance level). If the solving fails, a nan value is returned.

This function is a Python adaptation of the pwr.r.test function implemented in the pwr R package.

Examples

  1. Compute achieved power given r, n and alpha

>>> from pingouin import power_corr
>>> print('power: %.4f' % power_corr(r=0.5, n=20))
power: 0.6379

  1. Same but one-sided test

>>> print('power: %.4f' % power_corr(r=0.5, n=20, alternative="greater"))
power: 0.7510

>>> print('power: %.4f' % power_corr(r=0.5, n=20, alternative="less"))
power: 0.0000

  1. Compute required sample size given r, power and alpha

>>> print('n: %.4f' % power_corr(r=0.5, power=0.80))
n: 28.2484

  1. Compute achieved r given n, power and alpha level

>>> print('r: %.4f' % power_corr(n=20, power=0.80, alpha=0.05))
r: 0.5822

  1. Compute achieved alpha level given r, n and power

>>> print('alpha: %.4f' % power_corr(r=0.5, n=20, power=0.80, alpha=None))
alpha: 0.1377