Pingouin

https://pingouin-stats.org/build/html/
Admin
Pingouin is an open-source statistical package for Python 3, offering a comprehensive suite of...
Tokens:916,661
Snippets:2,142
Trust Score:7.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Pingouin Data Loading and Setup Example

Source: https://pingouin-stats.org/build/html/_modules/pingouin/pairwise

Demonstrates how to load a dataset using `pg.read_dataset` and set Pandas display options for better DataFrame visualization, which is a common setup step for using Pingouin functions.

```python
import pandas as pd
import pingouin as pg

# Set Pandas display options for better DataFrame visualization
pd.set_option('display.expand_frame_repr', False)
pd.set_option('display.max_columns', 20)

# Load a dataset from Pingouin's built-in datasets
df = pg.read_dataset('mixed_anova.csv')
```

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

### Installing Documentation Dependencies

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

Installs the necessary packages to build the documentation locally, including Sphinx and related tools.

```shell
pip install -e .[docs]
```

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

### Documentation and Examples

Source: https://pingouin-stats.org/build/html/changelog

Enhancements to documentation, including major re-organization of API categories, addition of equations and references, and use of Jupyter Notebooks for examples with Binder integration.

```python
# Major re-organization in API category
# Added equations and references for effect sizes and Bayesian functions.
# Examples are now Jupyter Notebooks.
# Binder integration
# Added several tutorials
# Improved doc of several functions
```

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

### Read Example Dataset with pingouin.read_dataset

Source: https://pingouin-stats.org/build/html/generated/pingouin.power_anova

Reads an example dataset from the Pingouin library. This function provides access to built-in datasets for demonstration and testing.

```APIDOC
pingouin.read_dataset(name)
```

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

### Install Pingouin

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

Command to install the Pingouin package using pip. This is the primary method for adding Pingouin to your Python environment.

```bash
pip install pingouin
```

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

### Check mpmath Installation

Source: https://pingouin-stats.org/build/html/_modules/pingouin/utils

Verifies if the 'mpmath' library is installed. If 'raise_error' is True and the library is not found, it raises an OSError with installation instructions.

```python
def _is_mpmath_installed(raise_error=False):
    """Check if mpmath is installed."""
    try:
        import mpmath  # noqa

        is_installed = True
    except OSError:  # pragma: no cover
        is_installed = False
    # Raise error (if needed) :
    if raise_error and not is_installed:  # pragma: no cover
        raise OSError("mpmath needs to be installed. Please use `pip " "install mpmath`.")
    return is_installed
```

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

### Read Example Dataset

Source: https://pingouin-stats.org/build/html/generated/pingouin.read_dataset

Loads a specified example dataset into a pandas DataFrame. The dataset name should be a string without an extension and must exist within pingouin.datasets. This function is useful for quickly accessing and working with built-in example data for analysis.

```python
import pingouin as pg
df = pg.read_dataset('penguins')
print(df)
```

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

### List Available Pingouin Example Datasets

Source: https://pingouin-stats.org/build/html/_modules/pingouin/datasets

Lists all available example datasets within the pingouin.datasets module. It returns a pandas DataFrame containing the name, description, and reference for each dataset. This function is useful for discovering available datasets.

```python
def list_dataset():
    """List available example datasets.

    Returns
    -------
    datasets : :py:class:`pandas.DataFrame`
        A dataframe with the name, description and reference of all the
        datasets included in Pingouin.

    Examples
    --------

    >>> 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']
    """
    return dts.set_index("dataset")
```

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

### Read Pingouin Example Dataset

Source: https://pingouin-stats.org/build/html/_modules/pingouin/datasets

Reads a specified example dataset from the pingouin.datasets module. It validates the dataset name and returns a pandas DataFrame. Dependencies include pandas and os.path.

```python
def read_dataset(dname):
    """Read example datasets.

    Parameters
    ----------
    dname : string
        Name of dataset to read (without extension).
        Must be a valid dataset present in pingouin.datasets

    Returns
    -------
    data : :py:class:`pandas.DataFrame`
        Requested dataset.

    Examples
    --------
    Load the `Penguin <https://github.com/allisonhorst/palmerpenguins>`_
    dataset:

    >>> import pingouin as pg
    >>> df = pg.read_dataset('penguins')
    >>> df # doctest: +SKIP
        species  island  bill_length_mm  ...  flipper_length_mm  body_mass_g     sex
    0    Adelie  Biscoe            37.8  ...              174.0       3400.0  female
    1    Adelie  Biscoe            37.7  ...              180.0       3600.0    male
    2    Adelie  Biscoe            35.9  ...              189.0       3800.0  female
    3    Adelie  Biscoe            38.2  ...              185.0       3950.0    male
    4    Adelie  Biscoe            38.8  ...              180.0       3800.0    male
    ..      ...     ...             ...  ...                ...          ...     ...
    339  Gentoo  Biscoe             NaN  ...                NaN          NaN     NaN
    340  Gentoo  Biscoe            46.8  ...              215.0       4850.0  female
    341  Gentoo  Biscoe            50.4  ...              222.0       5750.0    male
    342  Gentoo  Biscoe            45.2  ...              212.0       5200.0  female
    343  Gentoo  Biscoe            49.9  ...              213.0       5400.0    male
    """
    # Check extension
    d, ext = op.splitext(dname)
    if ext.lower() == ".csv":
        dname = d
    # Check that dataset exist
    if dname not in dts["dataset"].to_numpy():
        raise ValueError(
            "Dataset does not exist. Valid datasets names are", dts["dataset"].to_numpy()
        )
    # Load dataset
    return pd.read_csv(op.join(ddir, dname + ".csv"), sep=",")
```

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

### McNemar's Test Example

Source: https://pingouin-stats.org/build/html/generated/pingouin.chi2_mcnemar

Example usage of the pingouin.chi2_mcnemar function with a sample dataset to demonstrate calculating McNemar's test statistics.

```python
import pingouin as pg
data = pg.read_dataset('chi2_mcnemar')
observed, stats = pg.chi2_mcnemar(data, 'treatment_X', 'treatment_Y')
```

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

### One-Sample TOST Example

Source: https://pingouin-stats.org/build/html/generated/pingouin.tost

Shows how to conduct a one-sample TOST with a specified bound using pingouin.

```python
import pingouin as pg
a = [4, 7, 8, 6, 3, 2]
pg.tost(a, y=0, bound=4)
```

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

### List Available Datasets with pingouin.list_dataset

Source: https://pingouin-stats.org/build/html/generated/pingouin.power_anova

Lists the available example datasets in the Pingouin library. This function helps users discover the available datasets.

```APIDOC
pingouin.list_dataset()
```

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

### One-way ANOVA Example

Source: https://pingouin-stats.org/build/html/generated/pingouin.anova

Example demonstrating how to perform a one-way ANOVA using the pingouin.anova function with a sample dataset.

```python
import pingouin as pg
df = pg.read_dataset('anova')
aov = pg.anova(dv='Pain threshold', between='Hair color', data=df,
               detailed=True)
aov.round(3)
```

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

### Paired TOST Example

Source: https://pingouin-stats.org/build/html/generated/pingouin.tost

Illustrates performing a paired TOST with a specified region of similarity using pingouin.

```python
import pingouin as pg
a = [4, 7, 8, 6, 3, 2]
b = [6, 8, 7, 10, 11, 9]
pg.tost(a, b, bound=0.5, paired=True)
```

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

### Accessing Regression Residuals

Source: https://pingouin-stats.org/build/html/generated/pingouin.linear_regression

Shows how to access and display the residuals from a linear regression model. It provides an example of printing the first few residuals and then using pandas to get a statistical summary of all residuals.

```python
>>> # For clarity, only display the first 9 values
>>> np.round(lm.residuals_, 2)[:9]
array([-1.62, -0.55,  0.31,  0.06, -0.11,  0.93,  0.13, -0.81, -0.49])
```

```python
>>> import pandas as pd
>>> pd.Series(lm.residuals_).describe().round(2)
count    244.00
mean      -0.00
std        1.01
min       -2.93
25%       -0.55
50%       -0.09
75%        0.51
max        4.04
dtype: float64
```

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

### Building Documentation Locally (from docs directory)

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

Builds the HTML documentation from the 'docs' directory. This allows for local preview of documentation changes.

```shell
make html
```

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

### Check statsmodels Installation

Source: https://pingouin-stats.org/build/html/_modules/pingouin/utils

Verifies if the 'statsmodels' library is installed. If 'raise_error' is True and the library is not found, it raises an OSError with installation instructions.

```python
def _is_statsmodels_installed(raise_error=False):
    """Check if statsmodels is installed."""
    try:
        import statsmodels  # noqa

        is_installed = True
    except OSError:  # pragma: no cover
        is_installed = False
    # Raise error (if needed) :
    if raise_error and not is_installed:  # pragma: no cover
        raise OSError("statsmodels needs to be installed. Please use `pip " "install statsmodels`.")
    return is_installed
```

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

### Building Documentation Locally (from root directory)

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

Builds the HTML documentation by executing the 'make html' command from the root Pingouin directory, specifying the docs directory.

```shell
make -C docs html
```

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

### Check scikit-learn Installation

Source: https://pingouin-stats.org/build/html/_modules/pingouin/utils

Verifies if the 'sklearn' (scikit-learn) library is installed. If 'raise_error' is True and the library is not found, it raises an OSError with installation instructions.

```python
def _is_sklearn_installed(raise_error=False):
    """Check if sklearn is installed."""
    try:
        import sklearn  # noqa

        is_installed = True
    except OSError:  # pragma: no cover
        is_installed = False
    # Raise error (if needed) :
    if raise_error and not is_installed:  # pragma: no cover
        raise OSError("sklearn needs to be installed. Please use `pip " "install scikit-learn`.")
    return is_installed
```

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

### Pingouin Datasets Module Initialization

Source: https://pingouin-stats.org/build/html/_modules/pingouin/datasets

Initializes the pingouin.datasets module by reading a CSV file containing dataset information and defining functions for dataset access.

```python
import pandas as pd
import os.path as op
from pingouin.utils import print_table

ddir = op.dirname(op.realpath(__file__))
dts = pd.read_csv(op.join(ddir, "datasets.csv"), sep=",")

__all__ = ["read_dataset", "list_dataset"]
```

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

### Bland-Altman Plot Example

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

Example of how to generate a Bland-Altman plot using pingouin with sample data.

```python
import pingouin as pg
import matplotlib.pyplot as plt

df = pg.read_dataset("blandaltman")
ax = pg.plot_blandaltman(df['A'], df['B'])
plt.tight_layout()
```

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

### Pingouin Logistic Regression Examples

Source: https://pingouin-stats.org/build/html/_modules/pingouin/regression

Demonstrates how to perform simple and multiple binary logistic regressions using Pingouin, including data preparation, handling missing values, and interpreting coefficients.

```python
import numpy as np
import pandas as pd
import pingouin as pg
df = pg.read_dataset('penguins')
# Let's first convert the target variable from string to boolean:
df['male'] = (df['sex'] == 'male').astype(int)  # male: 1, female: 0
# Since there are missing values in our outcome variable, we need to
# set `remove_na=True` otherwise regression will fail.
lom = pg.logistic_regression(df['body_mass_g'], df['male'],
                             remove_na=True)
lom.round(2)
```

```python
df['body_mass_kg'] = df['body_mass_g'] / 1000
lom = pg.logistic_regression(df['body_mass_kg'], df['male'],
                             remove_na=True)
lom.round(2)
```

```python
df = pd.get_dummies(df, columns=['species'], dtype=float, drop_first=True)
X = df[['body_mass_kg', 'species_Chinstrap', 'species_Gentoo']]
y = df['male']
lom = pg.logistic_regression(X, y, remove_na=True)
lom.round(2)
```

```python
pg.logistic_regression(X.to_numpy(), y.to_numpy(), coef_only=True,
                       remove_na=True)
```

```python
lom = pg.logistic_regression(X, y, solver='sag', max_iter=10000,
                           random_state=42, remove_na=True)
print(lom['coef'].to_numpy())
```

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

### Example Usage of pingouin.rm_corr

Source: https://pingouin-stats.org/build/html/generated/pingouin.rm_corr

Demonstrates how to use the pingouin.rm_corr function with a sample dataset. It shows the necessary imports and the function call with specified columns for analysis.

```python
import pingouin as pg
df = pg.read_dataset('rm_corr')
pg.rm_corr(data=df, x='pH', y='PacO2', subject='Subject')
```

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

### pingouin.compute_bootci API Documentation

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

This section details the parameters, return values, and usage of the pingouin.compute_bootci function. It covers univariate and bivariate statistics, different bootstrapping methods, and options for paired data and output formatting.

```APIDOC
pingouin.compute_bootci(_x_ , _y =None_, _func =None_, _method ='cper'_, _paired =False_, _confidence =0.95_, _n_boot =2000_, _decimals =2_, _seed =None_, _return_dist =False_)
    Bootstrapped confidence intervals of univariate and bivariate functions.

    Parameters: 
    
    x (1D-array or list): First sample. Required for both bivariate and univariate functions.
    y (1D-array, list, or None): Second sample. Required only for bivariate functions.
    func (str or custom function): Function to compute the bootstrapped statistic. Accepted string values are:
      * 'pearson': Pearson correlation (bivariate, paired x and y)
      * 'spearman': Spearman correlation (bivariate, paired x and y)
      * 'cohen': Cohen d effect size (bivariate, paired or unpaired x and y)
      * 'hedges': Hedges g effect size (bivariate, paired or unpaired x and y)
      * 'mean': Mean (univariate = only x)
      * 'std': Standard deviation (univariate)
      * 'var': Variance (univariate)
    method (str): Method to compute the confidence intervals. Accepted values are:
      * 'cper': Bias-corrected percentile method (default)
      * 'norm': Normal approximation with bootstrapped bias and standard error
      * 'per': Simple percentile
    paired (boolean): Indicates whether x and y are paired or not. If True, x and y must have the same number of elements.
    confidence (float): Confidence level (e.g., 0.95 for 95% CI).
    n_boot (int): Number of bootstrap iterations.
    decimals (int): Number of rounded decimals for the output.
    seed (int or None): Random seed for generating bootstrap samples.
    return_dist (boolean): If True, return the confidence intervals and the bootstrapped distribution.

    Returns: 
    
    ci (array): Bootstrapped confidence intervals.

    Notes:
    Results have been tested against the Matlab function `bootci`. SciPy's `scipy.stats.bootstrap()` is also available and may be faster for certain use cases.
    The percentile bootstrap method (`per`) uses percentiles of the bootstrap distribution.
    The bias-corrected percentile method (`cper`) corrects for bias in the bootstrap distribution.
    The normal approximation method (`norm`) uses standard normal distribution with bootstrapped bias and standard error.

    References:
      * DiCiccio, T. J., & Efron, B. (1996). Bootstrap confidence intervals. Statistical science, 189-212.
      * Davison, A. C., & Hinkley, D. V. (1997). Bootstrap methods and their application (Vol. 1). Cambridge university press.
      * Jung, Lee, Gupta, & Cho (2019). Comparison of bootstrap confidence interval methods for GSCA using a Monte Carlo simulation. Frontiers in psychology, 10, 2215.
```

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

### Non-parametric Test Example (Kruskal-Wallis)

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

Shows how to apply a non-parametric test, specifically the Kruskal-Wallis test, using Pingouin for independent groups when assumptions for ANOVA are not met. It uses the same dataset as the ANOVA example.

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

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

### Sphinx and PyData Sphinx Theme Versions

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

Information about the versions of Sphinx and the PyData Sphinx Theme used to build the documentation.

```text
Sphinx 7.4.7
PyData Sphinx Theme 0.15.4
```

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

### Sphinx and PyData Sphinx Theme Usage

Source: https://pingouin-stats.org/build/html/_modules/pingouin/multivariate

Information regarding the tools used to build the project's HTML documentation. This includes Sphinx for general documentation generation and the PyData Sphinx Theme for a consistent and professional look.

```rst
Created using [Sphinx](https://www.sphinx-doc.org/) 7.4.7.

Built with the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html) 0.15.4.
```

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

### Python: Horizontal Paired Plot Example

Source: https://pingouin-stats.org/build/html/generated/pingouin.plot_paired

Illustrates how to create a horizontal paired plot by setting the 'orient' parameter to 'h'. This example uses a dataset with three unique within-levels and plots 'Scores' against 'Time' for each 'Subject'.

```python
import pingouin as pg
import matplotlib.pyplot as plt
df = pg.read_dataset('mixed_anova').query("Group == 'Meditation'")
pg.plot_paired(data=df, dv='Scores', within='Time',
               subject='Subject', orient='h')
```

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

### Inspect Documentation Build on GitHub

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

Steps to inspect documentation build artifacts generated by GitHub Actions for a Pull Request. This involves navigating the GitHub UI to find and download the 'docs-artifact' zip file.

```text
1. Click on the “Show all checks” dropdown menu.
2. Click on the check that starts with `Python tests / build (ubuntu-latest, 3.8)`.
3. In the opening window, click the “Artifacts” dropdown menu.
4. Download the `docs-artifact` zip file.
5. Unpack the zip file and open `index.html`.
```

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

### Compute required sample size for a T-test

Source: https://pingouin-stats.org/build/html/generated/pingouin.power_ttest

Example showing how to calculate the necessary sample size (n) for a T-test when the effect size (d), desired power, and significance level (alpha) are known. This example uses an 'greater' alternative hypothesis.

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

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

### Correlation Analysis Examples

Source: https://pingouin-stats.org/build/html/_modules/pingouin/correlation

Demonstrates how to compute Pearson correlation coefficients and interpret the results, including confidence intervals and p-values. It shows examples using raw numpy arrays and pandas DataFrames, and highlights the handling of perfect correlations and data cleaning.

```python
import pingouin as pg
import numpy as np

x = np.array([1, 2, 3, 4, 5])
y = np.array([2, 4, 5, 4, 5])

# Calculate Pearson correlation
corr_results = pg.corr(x, y).round(3)
print(corr_results)

# Example with perfect negative correlation
corr_neg_results = pg.corr(x, -x).round(3)
print(corr_neg_results)

# Example using pandas DataFrame
import pandas as pd
data = pd.DataFrame({'x': x, 'y': y})
corr_df_results = pg.corr(data['x'], data['y']).round(3)
print(corr_df_results)
```

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

### Power ANOVA Function Examples

Source: https://pingouin-stats.org/build/html/_modules/pingouin/power

Demonstrates the usage of the `power_anova` function in Pingouin for various statistical power analysis scenarios. It includes examples for computing achieved power, required number of groups, required sample size, achieved effect size, and achieved significance level (alpha).

```python
>>> from pingouin import power_anova
>>> print('power: %.4f' % power_anova(eta_squared=0.1, k=3, n=20))
power: 0.6082

>>> print('k: %.4f' % power_anova(eta_squared=0.1, n=20, power=0.80))
k: 6.0944

>>> print('n: %.4f' % power_anova(eta_squared=0.1, k=3, power=0.80))
n: 29.9256

>>> print('eta-squared: %.4f' % power_anova(n=20, k=4, power=0.80, alpha=0.05))
eta-squared: 0.1255

>>> print('alpha: %.4f' % power_anova(eta_squared=0.1, n=20, k=4, power=0.80, alpha=None))
alpha: 0.1085
```

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

### Mauchly test for sphericity using a wide-format dataframe in Pingouin

Source: https://pingouin-stats.org/build/html/generated/pingouin.sphericity

Demonstrates how to perform Mauchly's test for sphericity using a wide-format dataframe with the pingouin library. The example imports pandas and pingouin, creates a sample dataframe, and then applies the sphericity test. This example showcases the basic usage of the sphericity function.

```Python
import pandas as pd
import pingouin as pg
data = pd.DataFrame({'A': [2.2, 3.1, 4.3, 4.1, 7.2],
                     'B': [1.1, 2.5, 4.1, 5.2, 6.4]})
```

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

### List Available Datasets

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

Retrieves a list of all available example datasets within the Pingouin library. The function returns a pandas DataFrame containing the name, description, and reference for each dataset. This is useful for exploring the datasets provided by the library.

```python
import pingouin as pg

all_datasets = pg.list_dataset()
print(all_datasets.index.tolist())
```

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

### Normality Test Examples

Source: https://pingouin-stats.org/build/html/_modules/pingouin/distribution

Demonstrates how to use the pingouin.normality function with different data structures and test methods.

```python
import numpy as np
import pingouin as pg

# 1. Shapiro-Wilk test on a 1D array
np.random.seed(123)
x = np.random.normal(size=100)
print(pg.normality(x))

# 2. Omnibus test on a wide-format dataframe with missing values
data = pg.read_dataset('mediation')
data.loc[1, 'X'] = np.nan
print(pg.normality(data, method='normaltest').round(3))

# 3. Pandas Series
print(pg.normality(data['X'], method='normaltest'))

# 4. Long-format dataframe
data_long = pg.read_dataset('rm_anova2')
print(pg.normality(data_long, dv='Performance', group='Time'))

# 5. Same but using the Jarque-Bera test
print(pg.normality(data_long, dv='Performance', group='Time', method="jarque_bera"))
```

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

### Pingouin Multicomp Module Initialization

Source: https://pingouin-stats.org/build/html/_modules/pingouin/multicomp

Initializes the pingouin.multicomp module, defining author, date, and exported functions. It imports necessary libraries like numpy and pandas Series.

```python
# Author: Raphael Vallat <raphaelvallat9@gmail.com>
# Date: April 2018
import numpy as np
from pandas import Series

__all__ = ["multicomp"]
```
Tokens:
Raw