### 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 `_ 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 # Date: April 2018 import numpy as np from pandas import Series __all__ = ["multicomp"] ```