.. -- mode: rst --
|
.. image:: https://badge.fury.io/py/pingouin.svg :target: https://badge.fury.io/py/pingouin
.. image:: https://img.shields.io/conda/vn/conda-forge/pingouin.svg :target: https://anaconda.org/conda-forge/pingouin
.. image:: https://img.shields.io/github/license/raphaelvallat/pingouin.svg :target: https://github.com/raphaelvallat/pingouin/blob/master/LICENSE
.. image:: https://github.com/raphaelvallat/pingouin/actions/workflows/python_tests.yml/badge.svg :target: https://github.com/raphaelvallat/pingouin/actions
.. image:: https://codecov.io/gh/raphaelvallat/pingouin/branch/master/graph/badge.svg :target: https://codecov.io/gh/raphaelvallat/pingouin
.. image:: https://pepy.tech/badge/pingouin/month :target: https://pepy.tech/badge/pingouin/month
.. image:: http://joss.theoj.org/papers/d2254e6d8e8478da192148e4cfbe4244/status.svg :target: http://joss.theoj.org/papers/d2254e6d8e8478da192148e4cfbe4244
.. image:: https://pingouin-stats.org/build/html/_images/logo_pingouin.png :align: center
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 <https://pingouin-stats.org/build/html/api.html#>
_.
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 :code:ttest_ind
function of SciPy returns only the T-value and the p-value. By contrast,
the :code: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.
Link to documentation <https://pingouin-stats.org/index.html>
_If you have questions, please ask them in GitHub Discussions <https://github.com/raphaelvallat/pingouin/discussions>
_.
The main dependencies of Pingouin are :
NumPy <https://numpy.org/>
_SciPy <https://www.scipy.org/>
_Pandas <https://pandas.pydata.org/>
_Pandas-flavor <https://github.com/Zsailer/pandas_flavor>
_Statsmodels <https://www.statsmodels.org/>
_Matplotlib <https://matplotlib.org/>
_Seaborn <https://seaborn.pydata.org/>
_In addition, some functions require :
Scikit-learn <https://scikit-learn.org/>
_Mpmath <http://mpmath.org/>
_Pingouin is a Python 3 package and is currently tested for Python 3.8-3.11.
Pingouin can be easily installed using pip
.. code-block:: shell
pip install pingouin
or conda
.. code-block:: shell
conda install -c conda-forge pingouin
New releases are frequent so always make sure that you have the latest version:
.. code-block:: shell
pip install --upgrade pingouin
To build and install from source, clone this repository or download the source archive and decompress the files
.. code-block:: shell
cd pingouin python -m build # optional, build a wheel and sdist pip install . # install the package pip install --editable . # or editable install pytest # test the package
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.
.. image:: https://mybinder.org/badge.svg :target: https://mybinder.org/v2/gh/raphaelvallat/pingouin/develop
.. code-block:: python
import numpy as np 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
pg.ttest(x, y)
.. table:: Output :widths: auto
====== ===== ============= ======= ============= ========= ====== ======= 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 ====== ===== ============= ======= ============= ========= ====== =======
.. code-block:: python
pg.corr(x, y)
.. table:: Output :widths: auto
=== ===== =========== ======= ====== ======= n r CI95% p-val BF10 power === ===== =========== ======= ====== ======= 30 0.595 [0.3 0.79] 0.001 69.723 0.950 === ===== =========== ======= ====== =======
.. code-block:: python
x[5] = 18
pg.corr(x, y, method="bicor")
.. table:: Output :widths: auto
=== ===== =========== ======= ======= n r CI95% p-val power === ===== =========== ======= ======= 30 0.576 [0.27 0.78] 0.001 0.933 === ===== =========== ======= =======
The pingouin.normality
function works with lists, arrays, or pandas DataFrame in wide or long-format.
.. code-block:: python
print(pg.normality(x)) # Univariate normality print(pg.multivariate_normality(np.column_stack((x, y)))) # Multivariate normality
.. table:: Output :widths: auto
===== ====== ======== W pval normal ===== ====== ======== 0.615 0.000 False ===== ====== ========
.. parsed-literal::
(False, 0.00018)
.. code-block:: python
df = pg.read_dataset('mixed_anova')
aov = pg.anova(data=df, dv='Scores', between='Group', detailed=True) print(aov)
.. table:: Output :widths: auto
======== ======= ==== ===== ======= ======= ======= 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 ======== ======= ==== ===== ======= ======= =======
.. code-block:: python
pg.rm_anova(data=df, dv='Scores', within='Time', subject='Subject', detailed=True)
.. table:: Output :widths: auto
======== ======= ==== ===== ======= ======= ======= ======= 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 ======== ======= ==== ===== ======= ======= ======= =======
.. code-block:: python
posthoc = pg.pairwise_tests(data=df, dv='Scores', within='Time', subject='Subject', parametric=True, padjust='fdr_bh', effsize='hedges')
pg.print_table(posthoc, floatfmt='.3f')
.. table:: Output :widths: auto
========== ======= ======= ======== ============ ====== ====== ============= ======= ======== ========== ====== ======== 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 ========== ======= ======= ======== ============ ====== ====== ============= ======= ======== ========== ====== ========
.. code-block:: python
aov = pg.mixed_anova(data=df, dv='Scores', between='Group', within='Time', subject='Subject', correction=False, effsize="np2") pg.print_table(aov)
.. table:: Output :widths: auto
=========== ===== ===== ===== ===== ===== ======= ===== ======= 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 =========== ===== ===== ===== ===== ===== ======= ===== =======
.. code-block:: python
import pandas as pd 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')
.. table:: Output :widths: auto
=== === ======== ============= === ===== ============= ======= ====== ======= 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 === === ======== ============= === ===== ============= ======= ====== =======
.. code-block:: python
data.ptests(paired=True, stars=False)
.. table:: Pairwise T-tests, with T-values on the lower triangle and p-values on the upper triangle :widths: auto
==== ====== ====== ===== .. X Y Z ==== ====== ====== ===== X - 0.226 0.165 Y -1.238 - 0.658 Z -1.424 -0.447 - ==== ====== ====== =====
.. code-block:: python
pg.linear_regression(data[['X', 'Z']], data['Y'])
.. table:: Linear regression summary :widths: auto
========= ====== ===== ====== ====== ===== ======== ========== =========== names coef se T pval r2 adj_r2 CI[2.5%] CI[97.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 ========= ====== ===== ====== ====== ===== ======== ========== ===========
.. code-block:: python
pg.mediation_analysis(data=data, x='X', m='Z', y='Y', seed=42, n_boot=1000)
.. table:: Mediation summary :widths: auto
======== ====== ===== ====== ========== =========== ===== path coef se pval CI[2.5%] CI[97.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 ======== ====== ===== ====== ========== =========== =====
.. code-block:: python
data = pg.read_dataset('chi2_independence')
expected, observed, stats = pg.chi2_independence(data, x='sex', y='target')
stats
.. table:: Chi-squared tests summary :widths: auto
================== ======== ====== ===== ===== ======== ======= 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 ================== ======== ====== ===== ===== ======== =======
Several functions of Pingouin can be used directly as pandas DataFrame methods. Try for yourself with the code below:
.. code-block:: python
import pingouin as pg
df = pg.read_dataset('mixed_anova') df.anova(dv='Scores', between='Group', detailed=True)
data = pg.read_dataset('mediation') data.pairwise_corr(columns=['X', 'M', 'Y'], covar=['Mbin'])
data.pcorr()
The functions that are currently supported as pandas method are:
pingouin.anova <https://pingouin-stats.org/generated/pingouin.anova.html#pingouin.anova>
_pingouin.ancova <https://pingouin-stats.org/generated/pingouin.ancova.html#pingouin.ancova>
_pingouin.rm_anova <https://pingouin-stats.org/generated/pingouin.rm_anova.html#pingouin.rm_anova>
_pingouin.mixed_anova <https://pingouin-stats.org/generated/pingouin.mixed_anova.html#pingouin.mixed_anova>
_pingouin.welch_anova <https://pingouin-stats.org/generated/pingouin.welch_anova.html#pingouin.welch_anova>
_pingouin.pairwise_tests <https://pingouin-stats.org/generated/pingouin.pairwise_tests.html#pingouin.pairwise_tests>
_pingouin.pairwise_tukey <https://pingouin-stats.org/generated/pingouin.pairwise_tukey.html#pingouin.pairwise_tukey>
_pingouin.pairwise_corr <https://pingouin-stats.org/generated/pingouin.pairwise_corr.html#pingouin.pairwise_corr>
_pingouin.partial_corr <https://pingouin-stats.org/generated/pingouin.partial_corr.html#pingouin.partial_corr>
_pingouin.pcorr <https://pingouin-stats.org/generated/pingouin.pcorr.html#pingouin.pcorr>
_pingouin.rcorr <https://pingouin-stats.org/generated/pingouin.rcorr.html#pingouin.rcorr>
_pingouin.ptests <https://pingouin-stats.org/generated/pingouin.ptests.html#pingouin.ptests>
_pingouin.mediation_analysis <https://pingouin-stats.org/generated/pingouin.mediation_analysis.html#pingouin.mediation_analysis>
_Pingouin was created and is maintained by Raphael Vallat <https://raphaelvallat.github.io>
_, 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 <https://github.com/raphaelvallat/pingouin>
_.
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
Richard Höchenberger <http://hoechenberger.net/>
_Arthur Paulino <https://github.com/arthurpaulino>
_Eelke Spaak <https://eelkespaak.nl/>
_Johannes Elfner <https://www.linkedin.com/in/johannes-elfner/>
_Stefan Appelhoff <https://stefanappelhoff.com>
_If you want to cite Pingouin, please use the publication in JOSS:
https://doi.org/10.21105/joss.01026 <https://doi.org/10.21105/joss.01026>
_Several functions of Pingouin were inspired from R or Matlab toolboxes, including:
effsize package (R) <https://cran.r-project.org/web/packages/effsize/effsize.pdf>
_ezANOVA package (R) <https://cran.r-project.org/web/packages/ez/ez.pdf>
_pwr package (R) <https://cran.r-project.org/web/packages/pwr/pwr.pdf>
_circular statistics (Matlab) <https://www.mathworks.com/matlabcentral/fileexchange/10676-circular-statistics-toolbox-directional-statistics>
_robust correlations (Matlab) <https://sourceforge.net/projects/robustcorrtool/>
_repeated-measure correlation (R) <https://cran.r-project.org/web/packages/rmcorr/index.html>
_real-statistics.com <https://www.real-statistics.com/>
_