Pingouin is an open-source statistical package written in Python 3 and based mostly on Pandas and NumPy. Some of its main features are listed below. For a full list of available functions, please refer to the API documentation.
- ANOVAs: N-ways, repeated measures, mixed, ancova
- Pairwise post-hocs tests (parametric and non-parametric) and pairwise correlations
- Robust, partial, distance and repeated measures correlations
- Linear/logistic regression and mediation analysis
- Bayes Factors
- Multivariate tests
- Reliability and consistency
- Effect sizes and power analysis
- Parametric/bootstrapped confidence intervals around an effect size or a correlation coefficient
- Circular statistics
- Chi-squared tests
- Plotting: Bland-Altman plot, Q-Q plot, paired plot, robust correlation...
Pingouin is designed for users who want simple yet exhaustive statistical functions.
For example, the ttest_ind function of SciPy returns only the T-value and the p-value. By contrast,
the ttest function of Pingouin returns the T-value, the p-value, the degrees of freedom, the effect size (Cohen's d), the 95% confidence intervals of the difference in means, the statistical power and the Bayes Factor (BF10) of the test.
Documentation
Chat
If you have questions, please ask them in GitHub Discussions.
Installation
Dependencies
The main dependencies of Pingouin are:
- NumPy >= 1.22.4
- SciPy >= 1.8.0
- Pandas >= 2.1.1
- Pandas-flavor
- Statsmodels >= 0.14.1
- Matplotlib
- Seaborn
- Scikit-learn >= 1.2.2
- Tabulate
Some functions additionally require:
Pingouin is a Python 3 package and is currently tested for Python 3.10+.
User installation
Pingouin can be easily installed using uv
pip
or conda
New releases are frequent so always make sure that you have the latest version:
Development
To build and install from source, clone this repository and install in editable mode with uv
cd pingouin
uv pip install --group=test --editable .
# test the package
pytest --verbose
Quick start
Click on the link below and navigate to the notebooks/ folder to run a collection of interactive Jupyter notebooks showing the main functionalities of Pingouin. No need to install Pingouin beforehand, the notebooks run in a Binder environment.
10 minutes to Pingouin
1. T-test
import pingouin as pg
np.random.seed(123)
mean, cov, n = [4, 5], [(1, .6), (.6, 1)], 30
x, y = np.random.multivariate_normal(mean, cov, n).T
# T-test
pg.ttest(x, y)
| T | dof | alternative | p_val | CI95 | cohen_d | BF10 | power |
|---|---|---|---|---|---|---|---|
| -3.401 | 58 | two-sided | 0.001 | [-1.68 -0.43] | 0.878 | 26.155 | 0.917 |
2. Pearson's correlation
| n | r | CI95 | p_val | BF10 | power |
|---|---|---|---|---|---|
| 30 | 0.595 | [0.3 0.79] | 0.001 | 69.723 | 0.950 |
3. Robust correlation
x[5] = 18
# Use the robust biweight midcorrelation
pg.corr(x, y, method="bicor")
| n | r | CI95 | p_val | power |
|---|---|---|---|---|
| 30 | 0.576 | [0.27 0.78] | 0.001 | 0.933 |
4. Test the normality of the data
The pingouin.normality function works with lists, arrays, or pandas DataFrame in wide or long-format.
print(pg.multivariate_normality(np.column_stack((x, y)))) # Multivariate normality
| W | pval | normal |
|---|---|---|
| 0.615 | 0.000 | False |
5. One-way ANOVA using a pandas DataFrame
df = pg.read_dataset('mixed_anova')
# Run the ANOVA
aov = pg.anova(data=df, dv='Scores', between='Group', detailed=True)
print(aov)
| Source | SS | DF | MS | F | p_unc | np2 |
|---|---|---|---|---|---|---|
| Group | 5.460 | 1 | 5.460 | 5.244 | 0.023 | 0.029 |
| Within | 185.343 | 178 | 1.041 | nan | nan | nan |
6. Repeated measures ANOVA
| Source | SS | DF | MS | F | p_unc | ng2 | eps |
|---|---|---|---|---|---|---|---|
| Time | 7.628 | 2 | 3.814 | 3.913 | 0.023 | 0.04 | 0.999 |
| Error | 115.027 | 118 | 0.975 | nan | nan | nan | nan |
7. Post-hoc tests corrected for multiple-comparisons
posthoc = pg.pairwise_tests(data=df, dv='Scores', within='Time', subject='Subject',
parametric=True, padjust='fdr_bh', effsize='hedges')
# Pretty printing of table
pg.print_table(posthoc, floatfmt='.3f')
| Contrast | A | B | Paired | Parametric | T | dof | alternative | p_unc | p_corr | p_adjust | BF10 | hedges |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Time | August | January | True | True | -1.740 | 59.000 | two-sided | 0.087 | 0.131 | fdr_bh | 0.582 | -0.328 |
| Time | August | June | True | True | -2.743 | 59.000 | two-sided | 0.008 | 0.024 | fdr_bh | 4.232 | -0.483 |
| Time | January | June | True | True | -1.024 | 59.000 | two-sided | 0.310 | 0.310 | fdr_bh | 0.232 | -0.170 |
8. Two-way mixed ANOVA
aov = pg.mixed_anova(data=df, dv='Scores', between='Group', within='Time',
subject='Subject', correction=False, effsize="np2")
pg.print_table(aov)
| Source | SS | DF1 | DF2 | MS | F | p_unc | np2 | eps |
|---|---|---|---|---|---|---|---|---|
| Group | 5.460 | 1 | 58 | 5.460 | 5.052 | 0.028 | 0.080 | nan |
| Time | 7.628 | 2 | 116 | 3.814 | 4.027 | 0.020 | 0.065 | 0.999 |
| Interaction | 5.167 | 2 | 116 | 2.584 | 2.728 | 0.070 | 0.045 | nan |
9. Pairwise correlations between columns of a dataframe
np.random.seed(123)
z = np.random.normal(5, 1, 30)
data = pd.DataFrame({'X': x, 'Y': y, 'Z': z})
pg.pairwise_corr(data, columns=['X', 'Y', 'Z'], method='pearson')
| X | Y | method | alternative | n | r | CI95 | p_unc | BF10 | power |
|---|---|---|---|---|---|---|---|---|---|
| X | Y | pearson | two-sided | 30 | 0.366 | [0.01 0.64] | 0.047 | 1.500 | 0.525 |
| X | Z | pearson | two-sided | 30 | 0.251 | [-0.12 0.56] | 0.181 | 0.534 | 0.272 |
| Y | Z | pearson | two-sided | 30 | 0.020 | [-0.34 0.38] | 0.916 | 0.228 | 0.051 |
10. Pairwise T-test between columns of a dataframe
| X | Y | Z | |
|---|---|---|---|
| X | 0.226 | 0.165 | |
| Y | -1.238 | 0.658 | |
| Z | -1.424 | -0.447 |
11. Multiple linear regression
| names | coef | se | T | pval | r2 | adj_r2 | CI2.5 | CI97.5 |
|---|---|---|---|---|---|---|---|---|
| Intercept | 4.650 | 0.841 | 5.530 | 0.000 | 0.139 | 0.076 | 2.925 | 6.376 |
| X | 0.143 | 0.068 | 2.089 | 0.046 | 0.139 | 0.076 | 0.003 | 0.283 |
| Z | -0.069 | 0.167 | -0.416 | 0.681 | 0.139 | 0.076 | -0.412 | 0.273 |
12. Mediation analysis
| path | coef | se | pval | CI2.5 | CI97.5 | sig |
|---|---|---|---|---|---|---|
| Z ~ X | 0.103 | 0.075 | 0.181 | -0.051 | 0.256 | No |
| Y ~ Z | 0.018 | 0.171 | 0.916 | -0.332 | 0.369 | No |
| Total | 0.136 | 0.065 | 0.047 | 0.002 | 0.269 | Yes |
| Direct | 0.143 | 0.068 | 0.046 | 0.003 | 0.283 | Yes |
| Indirect | -0.007 | 0.025 | 0.898 | -0.069 | 0.029 | No |
13. Contingency analysis
expected, observed, stats = pg.chi2_independence(data, x='sex', y='target')
stats
| test | lambda | chi2 | dof | p | cramer | power |
|---|---|---|---|---|---|---|
| pearson | 1.000 | 22.717 | 1.000 | 0.000 | 0.274 | 0.997 |
| cressie-read | 0.667 | 22.931 | 1.000 | 0.000 | 0.275 | 0.998 |
| log-likelihood | 0.000 | 23.557 | 1.000 | 0.000 | 0.279 | 0.998 |
| freeman-tukey | -0.500 | 24.220 | 1.000 | 0.000 | 0.283 | 0.998 |
| mod-log-likelihood | -1.000 | 25.071 | 1.000 | 0.000 | 0.288 | 0.999 |
| neyman | -2.000 | 27.458 | 1.000 | 0.000 | 0.301 | 0.999 |
Integration with Pandas
Several functions of Pingouin can be used directly as pandas DataFrame methods. Try for yourself with the code below:
# Example 1 | ANOVA
df = pg.read_dataset('mixed_anova')
df.anova(dv='Scores', between='Group', detailed=True)
# Example 2 | Pairwise correlations
data = pg.read_dataset('mediation')
data.pairwise_corr(columns=['X', 'M', 'Y'], covar=['Mbin'])
# Example 3 | Partial correlation matrix
data.pcorr()
The functions that are currently supported as pandas method are:
- pingouin.anova
- pingouin.ancova
- pingouin.rm_anova
- pingouin.mixed_anova
- pingouin.welch_anova
- pingouin.pairwise_tests
- pingouin.pairwise_tukey
- pingouin.pairwise_corr
- pingouin.partial_corr
- pingouin.pcorr
- pingouin.rcorr
- pingouin.ptests
- pingouin.mediation_analysis
Development
Pingouin was created and is maintained by Raphael Vallat, a postdoctoral researcher at UC Berkeley, mostly during his spare time. Contributions are more than welcome so feel free to contact me, open an issue or submit a pull request!
To see the code or report a bug, please visit the GitHub repository.
This program is provided with NO WARRANTY OF ANY KIND. Pingouin is still under heavy development and there are likely hidden bugs. Always double check the results with another statistical software.
Contributors
- Nicolas Legrand
- Richard Hochenberger
- Arthur Paulino
- Eelke Spaak
- Johannes Elfner
- Stefan Appelhoff
How to cite Pingouin?
If you want to cite Pingouin, please use the publication in JOSS:
- Vallat, R. (2018). Pingouin: statistics in Python. Journal of Open Source Software, 3(31), 1026, https://doi.org/10.21105/joss.01026
Acknowledgement
Several functions of Pingouin were inspired from R or Matlab toolboxes, including: