Pingouin

https://pingouin-stats.org
Admin
Pingouin is an open-source statistical package in Python based on Pandas and NumPy, designed to...
Tokens:231,375
Snippets:1,323
Trust Score:7.3
Update:1 day ago
Show doc for...
Tokens:
Raw
### Setup example dataset for ptests

Source: https://pingouin-stats.org/generated/pingouin.ptests.html

Loads an example dataset, renames columns, and introduces missing values to prepare for pairwise T-tests.

```python
>>> import numpy as np
>>> import pandas as pd
>>> import pingouin as pg
>>> # Load an example dataset of personality dimensions
>>> df = pg.read_dataset("pairwise_corr").iloc[:30, 1:]
>>> df.columns = ["N", "E", "O", "A", "C"]
>>> # Add some missing values
>>> df.iloc[[2, 5, 20], 2] = np.nan
>>> df.iloc[[1, 4, 10], 3] = np.nan
>>> df.head().round(2)
      N     E     O     A     C
0  2.48  4.21  3.94  3.96  3.46
1  2.60  3.19  3.96   NaN  3.23
2  2.81  2.90   NaN  2.75  3.50
3  2.90  3.56  3.52  3.17  2.79
4  3.02  3.33  4.02   NaN  2.85
```

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

### Install documentation dependencies with uv

Source: https://pingouin-stats.org/contributing.html

Install the package with the docs dependency group to build documentation locally.

```bash
$ uv pip install --group=docs --editable .
```

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

### Install Pingouin with uv

Source: https://pingouin-stats.org/faq.html

Alternative installation command using the uv package manager.

```bash
uv pip install --upgrade pingouin
```

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

### Install Pingouin with pip

Source: https://pingouin-stats.org/index.html

Install Pingouin using pip, the standard Python package installer.

```bash
pip install pingouin
```

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

### Install Pingouin with uv

Source: https://pingouin-stats.org/index.html

Install Pingouin using the uv package manager. Requires uv to be installed.

```bash
uv pip install pingouin
```

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

### Clone repository and install development dependencies with uv

Source: https://pingouin-stats.org/contributing.html

Use these commands to set up a local development environment for Pingouin. First clone the repository, then install the package in editable mode with all development dependencies (testing, linting, pre-commit) using uv.

```shell
$ git clone https://github.com/raphaelvallat/pingouin.git
$ cd pingouin
$ uv pip install --group=dev --editable .
```

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

### Install pre-commit hooks

Source: https://pingouin-stats.org/contributing.html

Run this command to set up pre-commit hooks in the Pingouin repository. After installation, Ruff will automatically run on all staged files before each commit.

```shell
$ pre-commit install
```

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

### list_dataset

Source: https://pingouin-stats.org/api.html

List available example datasets. This function returns a list of all built-in example datasets available in Pingouin.

```APIDOC
## list_dataset

### Description
List available example datasets.

### Signature
`list_dataset()`
```

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

### Install Pingouin with pip

Source: https://pingouin-stats.org/faq.html

Use this command in a command prompt (or Terminal or Anaconda Prompt) to install or upgrade Pingouin.

```bash
pip install --upgrade pingouin
```

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

### read_dataset

Source: https://pingouin-stats.org/api.html

Read example datasets. This function loads a built-in example dataset by name, useful for testing and demonstration.

```APIDOC
## read_dataset

### Description
Read example datasets.

### Signature
`read_dataset(dname)`

### Parameters
- **dname** - Name of the dataset to read.
```

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

### Install Pingouin with conda

Source: https://pingouin-stats.org/index.html

Install Pingouin using conda from the conda-forge channel.

```bash
conda install -c conda-forge pingouin
```

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

### Install Pingouin with optional dependencies

Source: https://pingouin-stats.org/faq.html

Installs Pingouin along with optional dependencies (statsmodels and mpmath) required by some functions like ancova, rm_corr, anova, and one-sided bayesfactor_pearson.

```bash
pip install --upgrade "pingouin[extras]"
```

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

### List available Pingouin datasets with pg.list_dataset()

Source: https://pingouin-stats.org/generated/pingouin.list_dataset.html

Call pg.list_dataset() to retrieve a pandas DataFrame of all example datasets included in Pingouin. The example then prints the index, which lists dataset names such as 'ancova', 'anova', and 'tips'.

```python
>>> import pingouin as pg
>>> all_datasets = pg.list_dataset()
>>> all_datasets.index.tolist()
['ancova',
 'anova',
 'anova2',
 'anova2_unbalanced',
 'anova3',
 'anova3_unbalanced',
 'blandaltman',
 'chi2_independence',
 'chi2_mcnemar',
 'circular',
 'cochran',
 'cronbach_alpha',
 'cronbach_wide_missing',
 'icc',
 'mediation',
 'mixed_anova',
 'mixed_anova_unbalanced',
 'multivariate',
 'pairwise_corr',
 'pairwise_tests',
 'pairwise_tests_missing',
 'partial_corr',
 'penguins',
 'rm_anova',
 'rm_anova_wide',
 'rm_anova2',
 'rm_corr',
 'rm_missing',
 'tips']
```

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

### Load dataset and add missing values for rcorr example

Source: https://pingouin-stats.org/generated/pingouin.rcorr.html

Imports numpy, pandas, and pingouin, loads the 'pairwise_corr' example dataset, adds missing values to specific cells, and displays the first five rows.

```python
>>> import numpy as np
>>> import pandas as pd
>>> import pingouin as pg
>>> # Load an example dataset of personality dimensions
>>> df = pg.read_dataset("pairwise_corr").iloc[:, 1:]
>>> # Add some missing values
>>> df.iloc[[2, 5, 20], 2] = np.nan
>>> df.iloc[[1, 4, 10], 3] = np.nan
>>> df.head().round(2)
   Neuroticism  Extraversion  Openness  Agreeableness  Conscientiousness
0         2.48          4.21      3.94           3.96               3.46
1         2.60          3.19      3.96            NaN               3.23
2         2.81          2.90       NaN           2.75               3.50
3         2.90          3.56      3.52           3.17               2.79
4         3.02          3.33      4.02            NaN               2.85
```

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

### Load long-format dataset and preview

Source: https://pingouin-stats.org/generated/pingouin.epsilon.html

Loads the 'rm_anova2' example dataset and displays the first few rows to show the long-format structure.

```python
>>> data = pg.read_dataset("rm_anova2")
>>> data.head()
   Subject Time   Metric  Performance
0        1  Pre  Product           13
1        2  Pre  Product           12
2        3  Pre  Product           17
3        4  Pre  Product           12
4        5  Pre  Product           19
```

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

### Correlation workflow: normality check and Pearson correlation

Source: https://pingouin-stats.org/guidelines.html

This example demonstrates a correlation analysis workflow: optionally test for bivariate normality with pg.multivariate_normality, visually inspect with a jointplot, and then compute a Pearson correlation with pg.corr. It uses the 'pairwise_corr' example dataset.

```python
import pingouin as pg
import seaborn as sns

# Load an example dataset with the personality scores of 500 participants
df = pg.read_dataset('pairwise_corr')

# 1.Test for bivariate normality (optional)
pg.multivariate_normality(df[['Neuroticism', 'Openness']])

# 1bis. Visual inspection with a histogram + scatter plot (optional)
sns.jointplot(data=df, x='Neuroticism', y='Openness', kind='reg')

# 2. If the data have a bivariate normal distribution and no clear outlier(s), we can use a regular Pearson correlation
pg.corr(df['Neuroticism'], df['Openness'], method='pearson')
```

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

### Example: Using pingouin.madmedianrule for outlier detection

Source: https://pingouin-stats.org/generated/pingouin.madmedianrule.html

This example imports pingouin and applies madmedianrule to a list of numbers, returning a boolean array where True indicates an outlier. The output shows the sixth element (6.61) is flagged as an outlier.

```python
>>> import pingouin as pg
>>> a = [-1.09, 1.0, 0.28, -1.51, -0.58, 6.61, -2.43, -0.43]
>>> pg.madmedianrule(a)
array([False, False, False, False, False,  True, False, False])
```

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

### Example: Create a 2x2 crosstab with pingouin.dichotomous_crosstab

Source: https://pingouin-stats.org/generated/pingouin.dichotomous_crosstab.html

This example creates a pandas DataFrame with dichotomous values ('Yes'/'No' and 0.0/1.0) and calls pg.dichotomous_crosstab to generate a 2x2 contingency table. The output shows the resulting crosstab with rows and columns labeled 0 and 1.

```python
>>> import pandas as pd
>>> import pingouin as pg
>>> df = pd.DataFrame({'A': ['Yes', 'No', 'No'], 'B': [0., 1., 0.]})
>>> pg.dichotomous_crosstab(data=df, x='A', y='B')
B  0  1
A
0  1  1
1  1  0
```

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

### Build documentation with make html

Source: https://pingouin-stats.org/contributing.html

Run make html within the pingouin/docs directory to build the documentation.

```bash
$ make html
```

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

### Build documentation with nitpicky and warnings as errors

Source: https://pingouin-stats.org/contributing.html

Use SPHINXOPTS with -W -n --keep-going to treat warnings as errors and run in nitpicky mode locally.

```bash
$ make -C docs html SPHINXOPTS="-W -n --keep-going"
```

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

### Build documentation with make -C docs html

Source: https://pingouin-stats.org/contributing.html

Call make from the root pingouin directory using the -C flag to switch to the docs directory and execute the html recipe.

```bash
$ make -C docs html
```

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

### Non-parametric test: Kruskal-Wallis

Source: https://pingouin-stats.org/guidelines.html

This example shows how to run a Kruskal-Wallis test with pg.kruskal when there are four independent groups. It uses the 'anova' example dataset.

```python
import pingouin as pg

# Load an example dataset comparing pain threshold as a function of hair color
df = pg.read_dataset('anova')

# There are 4 independent groups in our dataset, we'll therefore use the Kruskal-Wallis test:
pg.kruskal(data=df, dv='Pain threshold', between='Hair color')
```

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

### Launch IPython console

Source: https://pingouin-stats.org/faq.html

Opens an interactive Python console (IPython or Jupyter) to try Pingouin.

```bash
ipython
```

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

### Two-way repeated measures ANOVA

Source: https://pingouin-stats.org/generated/pingouin.rm_anova.html

Performs a two-way repeated measures ANOVA by specifying a list of within-subject factors. The example uses the same dataframe 'df' from the previous example.

```python
>>> aov = pg.rm_anova(
...     dv="DesireToKill",
...     within=["Disgustingness", "Frighteningness"],
...     subject="Subject",
...     data=df,
... )
```

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

### Normality test with Jarque-Bera method

Source: https://pingouin-stats.org/generated/pingouin.normality.html

Tests normality for a dependent variable grouped by a factor in a long-format dataframe using the 'jarque_bera' method. The example uses the same 'rm_anova2' dataset and parameters as the previous example, but with a different method.

```python
>>> pg.normality(data, dv="Performance", group="Time", method="jarque_bera")
             W      pval  normal
Time
Pre   0.304021  0.858979    True
Post  1.265656  0.531088    True
```

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

### Run Ruff linting and formatting

Source: https://pingouin-stats.org/contributing.html

Commands to manually check and format code using Ruff from the root folder of Pingouin. Run 'ruff check --fix' to fix linting issues and 'ruff format' to format the code.

```bash
$ ruff check --fix

$ ruff format
```

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

### Example: Using pingouin.multivariate_normality

Source: https://pingouin-stats.org/generated/pingouin.multivariate_normality.html

Demonstrates how to perform the Henze-Zirkler multivariate normality test on a dataset. The example loads the 'multivariate' dataset, selects three columns, and calls the function with alpha=0.05. The output shows the test statistic, p-value, and normality flag.

```python
>>> import pingouin as pg
>>> data = pg.read_dataset("multivariate")
>>> X = data[["Fever", "Pressure", "Aches"]]
>>> hz, pval, normal = pg.multivariate_normality(X, alpha=0.05)
>>> round(hz, 3), round(pval, 3), normal
(0.54, 0.717, True)
```

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

### Bootstrapped 95% BCa confidence interval of a Cohen d

Source: https://pingouin-stats.org/generated/pingouin.compute_bootci.html

Computes the bootstrapped 95% BCa confidence interval for Cohen's d effect size using the same x and y data from the previous example. The example prints the effect size and confidence interval.

```python
>>> stat = pg.compute_effsize(x, y, eftype="cohen")
>>> ci = pg.compute_bootci(x, y, func="cohen", seed=42, decimals=3)
>>> print(round(stat, 4), ci)
0.7009 [0.413 1.01 ]
```

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

### One-way Welch ANOVA example

Source: https://pingouin-stats.org/generated/pingouin.welch_anova.html

Example usage of pingouin.welch_anova on the pain threshold dataset. It imports the function and read_dataset, loads the 'anova' dataset, and runs the ANOVA with dv='Pain threshold' and between='Hair color'. The output shows the resulting ANOVA summary table.

```python
>>> from pingouin import welch_anova, read_dataset
>>> df = read_dataset("anova")
>>> aov = welch_anova(dv="Pain threshold", between="Hair color", data=df)
>>> aov
       Source  ddof1     ddof2         F     p_unc       np2
0  Hair color      3  8.329841  5.890115  0.018813  0.575962
```

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

### ANOVA workflow: homoscedasticity, ANOVA, and Tukey post-hoc

Source: https://pingouin-stats.org/guidelines.html

This example shows a typical between-subject ANOVA workflow: test for equality of variances with pg.homoscedasticity, run a one-way ANOVA with pg.anova, and if a main effect is found, proceed to a post-hoc Tukey test with pg.pairwise_tukey. It uses the 'anova' example dataset.

```python
import pingouin as pg

# Load an example dataset comparing pain threshold as a function of hair color
df = pg.read_dataset('anova')

# 1. This is a between subject design, so the first step is to test for equality of variances
pg.homoscedasticity(data=df, dv='Pain threshold', group='Hair color')

# 2. If the groups have equal variances, we can use a regular one-way ANOVA
pg.anova(data=df, dv='Pain threshold', between='Hair color')

# 3. If there is a main effect, we can proceed to post-hoc Tukey test
pg.pairwise_tukey(data=df, dv='Pain threshold', between='Hair color')
```

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

### Create a Bland-Altman plot with pingouin.plot_blandaltman

Source: https://pingouin-stats.org/generated/pingouin.plot_blandaltman.html

This example imports matplotlib and pingouin, loads the 'blandaltman' dataset, and creates a Bland-Altman plot comparing two measurements (columns 'A' and 'B'). The plot is then adjusted with plt.tight_layout().

```python
>>> import matplotlib.pyplot as plt
>>> import pingouin as pg
>>> df = pg.read_dataset("blandaltman")
>>> ax = pg.plot_blandaltman(df["A"], df["B"])
>>> plt.tight_layout()
```

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

### Using the F-test method

Source: https://pingouin-stats.org/generated/pingouin.friedman.html

Runs pg.friedman with method='f' to obtain the F statistic and corresponding degrees of freedom.

```python
>>> pg.friedman(df, method="f")
          Source         W     ddof1      ddof2    F     p_unc
Friedman  Within  0.083333  1.833333  20.166667  1.0  0.378959
```
Tokens:
Raw