.. -*- mode: rst -*-

|

.. image:: https://badge.fury.io/py/pingouin.svg
  :target: https://badge.fury.io/py/pingouin

.. image:: https://img.shields.io/github/license/raphaelvallat/pingouin.svg
  :target: https://github.com/raphaelvallat/pingouin/blob/master/LICENSE

.. image:: https://travis-ci.org/raphaelvallat/pingouin.svg?branch=master
    :target: https://travis-ci.org/raphaelvallat/pingouin

.. image:: https://ci.appveyor.com/api/projects/status/v7fhavoqj8ig1bs2?svg=true
    :target: https://ci.appveyor.com/project/raphaelvallat/pingouin

.. image:: https://codecov.io/gh/raphaelvallat/pingouin/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/raphaelvallat/pingouin

.. image:: http://joss.theoj.org/papers/d2254e6d8e8478da192148e4cfbe4244/status.svg
    :target: http://joss.theoj.org/papers/d2254e6d8e8478da192148e4cfbe4244

.. image:: https://badges.gitter.im/owner/repo.png
    :target: https://gitter.im/pingouin-stats/Lobby

----------------

.. figure::  https://github.com/raphaelvallat/pingouin/blob/master/docs/pictures/logo_pingouin.png
   :align:   center


**Pingouin** is an open-source statistical package written in Python 3 and based on Pandas and NumPy.

It provides easy-to-grasp functions for computing several statistical functions:

1. ANOVAs: one- and two-ways, repeated measures, mixed, ancova

2. Post-hocs tests and pairwise comparisons

3. Robust correlations

4. Partial correlation, repeated measures correlation and intraclass correlation

5. Bayes Factor

6. Tests for sphericity, normality and homoscedasticity

7. Effect sizes

8. Circular statistics

9. Linear/logistic regression and mediation analysis

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, p-value, degrees of freedom, effect size (Cohen's d), statistical power and Bayes Factor (BF10) of the test.


Documentation
=============

- `Link to documentation <https://raphaelvallat.github.io/pingouin/build/html/index.html>`_

Chat
====

If you have questions, please ask them in the public `Gitter chat <https://gitter.im/pingouin-stats/Lobby>`_

.. image:: https://badges.gitter.im/owner/repo.png
    :target: https://gitter.im/pingouin-stats/Lobby

Installation
============

Dependencies
------------

The main dependencies of Pingouin are :

* NumPy (>= 1.15)
* SciPy (>= 1.1.0)
* Pandas (>= 0.23)

In addition, some functions require :

* Statsmodels
* Scikit-learn

Pingouin is a Python 3 package. While most of the functions should work with Python 2.7, we strongly recommend using Python >= 3.6.

User installation
-----------------

.. code-block:: shell

  pip install pingouin

Develop mode

.. code-block:: shell

  git clone https://github.com/raphaelvallat/pingouin.git pingouin/
  cd pingouin/
  pip install -r requirements.txt
  python setup.py develop

New releases are frequent so always make sure that you have the latest version:

.. code-block:: shell

  pip install --upgrade pingouin

Quick start
============

Try before you buy! Click on the link below and navigate to the notebooks folder to load a collection of interactive Jupyter notebooks demonstrating the main functionalities of Pingouin. No need to install Pingouin beforehand as the notebooks run in a Binder environment.

.. image:: https://mybinder.org/badge.svg
    :target: https://mybinder.org/v2/gh/raphaelvallat/pingouin/develop

10 minutes to Pingouin
----------------------

1. T-test
#########

.. 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

  # T-test
  pg.ttest(x, y)

.. table:: Output
   :widths: auto

   =======  =======  =====  =========  =========  =======  ======
         T    p-val    dof  tail         cohen-d    power    BF10
   =======  =======  =====  =========  =========  =======  ======
    -3.401    0.001     58  two-sided      0.878    0.917  26.155
   =======  =======  =====  =========  =========  =======  ======

------------

2. Pearson's correlation
########################

.. code-block:: python

  pg.corr(x, y)

.. table:: Output
   :widths: auto

   ====  =====  ===========  =====  ========  =======  ======
      n      r  CI95%           r2    adj_r2    p-val    BF10
   ====  =====  ===========  =====  ========  =======  ======
     30  0.595  [0.3  0.79]  0.354     0.306    0.001  54.222
   ====  =====  ===========  =====  ========  =======  ======

------------

3. Robust correlation
#####################

.. code-block:: python

  # Introduce an outlier
  x[5] = 18
  # Use the robust Shepherd's pi correlation
  pg.corr(x, y, method="shepherd")

.. table:: Output
   :widths: auto

   ====  =====  ===========  =====  ========  =======
      n      r  CI95%           r2    adj_r2    p-val
   ====  =====  ===========  =====  ========  =======
     30  0.561  [0.25 0.77]  0.315     0.264    0.002
   ====  =====  ===========  =====  ========  =======

------------

4. Test the normality of the data
#################################

.. code-block:: python

   # Return a boolean (true if normal) and the associated p-value
   print(pg.normality(x, y))                                 # Univariate normality
   print(pg.multivariate_normality(np.column_stack((x, y)))) # Multivariate normality

.. parsed-literal::

   (array([False,  True]), array([0., 0.552]))
   (False, 0.00018)

------------

5. One-way ANOVA using a pandas DataFrame
#########################################

.. code-block:: python

  # Read an example dataset
  from pingouin.datasets import read_dataset
  df = read_dataset('mixed_anova')

  # Run the 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.02320  0.029
  Within    185.343   178  1.041  -      -        -
  ========  =======  ====  =====  =====  =======  =====

------------

6. Repeated measures ANOVA
##########################

.. 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     np2    eps
  ========  =======  ====  =====  =====  ========  =====  =====
  Time        7.628     2  3.814  3.913  0.022629  0.062  0.999
  Error     115.027   118  0.975  -      -         -      -
  ========  =======  ====  =====  =====  ========  =====  =====

------------

7. Post-hoc tests corrected for multiple-comparisons
####################################################

.. code-block:: python

  # FDR-corrected post hocs with Hedges'g effect size
  posthoc = pg.pairwise_ttests(data=df, dv='Scores', within='Time', subject='Subject',
                               padjust='fdr_bh', effsize='hedges')

  # Pretty printing of table
  pg.print_table(posthoc, floatfmt='.3f')

.. table:: Output
  :widths: auto

  ==========  =======  =======  ========  ======  =========  =======  ========  ==========  ======  ========  ========
  Contrast    A        B        Paired         T  tail         p-unc    p-corr  p-adjust      BF10    efsize  eftype
  ==========  =======  =======  ========  ======  =========  =======  ========  ==========  ======  ========  ========
  Time        August   January  True      -1.740  two-sided    0.087     0.131  fdr_bh       0.582    -0.328  hedges
  Time        August   June     True      -2.743  two-sided    0.008     0.024  fdr_bh       4.232    -0.485  hedges
  Time        January  June     True      -1.024  two-sided    0.310     0.310  fdr_bh       0.232    -0.170  hedges
  ==========  =======  =======  ========  ======  =========  =======  ========  ==========  ======  ========  ========

------------

8. Two-way mixed ANOVA
######################

.. code-block:: python

  # Compute the two-way mixed ANOVA and export to a .csv file
  aov = pg.mixed_anova(data=df, dv='Scores', between='Group', within='Time',
                       subject='Subject', correction=False,
                       export_filename='mixed_anova.csv')
  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  -
  Time         7.628      2    116  3.814  4.027    0.020  0.065  0.999
  Interaction  5.168      2    116  2.584  2.728    0.070  0.045  -
  ===========  =====  =====  =====  =====  =====  =======  =====  =====

------------

9. Pairwise correlations between columns of a dataframe
#######################################################

.. code-block:: python

  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'])

.. table:: Output
  :widths: auto

  ===  ===  ========  =========  ===  =====  =============  =====  ========  =====  =======  ======
  X    Y    method    tail         n      r  CI95%             r2    adj_r2      z    p-unc    BF10
  ===  ===  ========  =========  ===  =====  =============  =====  ========  =====  =======  ======
  X    Y    pearson   two-sided   30  0.366  [0.01 0.64]    0.134     0.070  0.384    0.047   1.006
  X    Z    pearson   two-sided   30  0.251  [-0.12  0.56]  0.063    -0.006  0.256    0.181   0.344
  Y    Z    pearson   two-sided   30  0.020  [-0.34  0.38]  0.000    -0.074  0.020    0.916   0.142
  ===  ===  ========  =========  ===  =====  =============  =====  ========  =====  =======  ======

10. Convert between effect sizes
################################

.. code-block:: python

    # Convert from Cohen's d to Hedges' g
    pg.convert_effsize(0.4, 'cohen', 'hedges', nx=10, ny=12)

.. parsed-literal::

    0.384

11. Multiple linear regression
##############################

.. code-block:: ipython3

    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
  =========  ======  =====  ======  ======  =====  ========  ==========  ===========

12. Mediation analysis
######################

.. code-block:: ipython3

  pg.mediation_analysis(data=data, x='X', m='Z', y='Y', n_boot=500)

.. table:: Mediation summary
  :widths: auto

  ========  ======  ==========  ===========  =====
  Path        Beta    CI[2.5%]    CI[97.5%]  Sig
  ========  ======  ==========  ===========  =====
  X -> M     0.103      -0.051        0.256  No
  M -> Y     0.018      -0.332        0.369  No
  X -> Y     0.136       0.002        0.269  Yes
  Direct     0.143       0.003        0.283  Yes
  Indirect  -0.007      -0.050        0.027  No
  ========  ======  ==========  ===========  =====

Development
===========

Pingouin was created and is maintained by `Raphael Vallat <https://raphaelvallat.github.io>`_. 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>`_.

Note that this program is provided with NO WARRANTY OF ANY KIND. If you can, always double check the results with another statistical software.

Acknowledgement
===============

Several functions of Pingouin were translated to Python from the original 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>`_
- `circular statistics (Matlab) <https://www.mathworks.com/matlabcentral/fileexchange/10676-circular-statistics-toolbox-directional-statistics>`_ (Berens 2009)
- `robust correlations (Matlab) <https://sourceforge.net/projects/robustcorrtool/>`_ (Pernet, Wilcox & Rousselet, 2012)
- `repeated-measure correlation (R) <https://cran.r-project.org/web/packages/rmcorr/index.html>`_ (Bakdash & Marusich, 2017)

I am also grateful to Charles Zaiontz and his website `www.real-statistics.com <https://www.real-statistics.com/>`_ which has been useful to
understand the practical implementation of several functions.
