pingouin.power_ttest#

pingouin.power_ttest(d=None, n=None, power=None, alpha=0.05, contrast='two-samples', alternative='two-sided')[source]#

Evaluate power, sample size, effect size or significance level of a one-sample T-test, a paired T-test or an independent two-samples T-test with equal sample sizes.

Parameters:

dfloat

Cohen d effect size

nint

Sample size In case of a two-sample T-test, sample sizes are assumed to be equal. Otherwise, see the power_ttest2n() function.

powerfloat

Test power (= 1 - type II error).

alphafloat

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

contraststr

Can be “one-sample”, “two-samples” or “paired”. Note that “one-sample” and “paired” have the same behavior.

alternativestring

Defines the alternative hypothesis, or tail of the test. Must be one of “two-sided” (default), “greater” or “less”.

Notes

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

For a paired T-test, the sample size n corresponds to the number of pairs. For an independent two-sample T-test with equal sample sizes, n corresponds to the sample size of each group (i.e. number of observations in one group). If the sample sizes are unequal, please use the power_ttest2n() function instead.

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

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

Statistical power is the likelihood that a study will detect an effect when there is an effect there to be detected. A high statistical power means that there is a low probability of concluding that there is no effect when there is one. Statistical power is mainly affected by the effect size and the sample size.

The first step is to use the Cohen’s d to calculate the non-centrality parameter $\delta$ and degrees of freedom $v$. In case of paired groups, this is:

$$\delta =d\ast \sqrt{n}$$

$$v=n-1$$

and in case of independent groups with equal sample sizes:

$$\delta =d\ast \sqrt{\frac{n}{2}}$$

$$v=(n-1)\ast 2$$

where $d$ is the Cohen d and $n$ the sample size.

The critical value is then found using the percent point function of the T distribution with $q=1-alpha$ and $v$ degrees of freedom.

Finally, the power of the test is given by the survival function of the non-central distribution using the previously calculated critical value, degrees of freedom and non-centrality parameter.

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.

Results have been tested against GPower and the pwr R package.

Examples

1. Compute power of a one-sample T-test given d, n and alpha

>>> from pingouin import power_ttest
>>> print('power: %.4f' % power_ttest(d=0.5, n=20, contrast='one-sample'))
power: 0.5645

2. Compute required sample size given d, power and alpha

>>> print('n: %.4f' % power_ttest(d=0.5, power=0.80, alternative='greater'))
n: 50.1508

3. Compute achieved d given n, power and alpha level

>>> print('d: %.4f' % power_ttest(n=20, power=0.80, alpha=0.05, contrast='paired'))
d: 0.6604

4. Compute achieved alpha level given d, n and power

>>> print('alpha: %.4f' % power_ttest(d=0.5, n=20, power=0.80, alpha=None))
alpha: 0.4430

5. One-sided tests

>>> from pingouin import power_ttest
>>> print('power: %.4f' % power_ttest(d=0.5, n=20, alternative='greater'))
power: 0.4634

>>> print('power: %.4f' % power_ttest(d=0.5, n=20, alternative='less'))
power: 0.0007