Phi_K correlation analyzer library

0.12.5 · active · verified Sun Apr 12

Phi_K is a practical correlation constant that works consistently between categorical, ordinal, and interval variables. It extends Pearson's hypothesis test of independence, capturing non-linear dependencies and reverting to Pearson's correlation for bi-variate normal distributions. The current version, 0.12.5, was released in July 2025. The library aims for a regular release cadence, with updates occurring every few months to a year, incorporating Python version support and bug fixes.

Warnings

breaking Python 3.7 and 3.8 support has been dropped. Version 0.12.4 dropped 3.7, and 0.12.5 dropped 3.8. Ensure your Python environment is 3.9 or newer.
Fix: Upgrade Python to version 3.9 or later.
breaking The `scipy.stats.mvn` function was migrated to `scipy.stats.qmvn` in version 0.12.5 due to deprecation in newer SciPy versions. Using older `phik` versions with a newer `scipy` or vice-versa might lead to compatibility issues.
Fix: Ensure `phik` and `scipy` versions are compatible. Upgrade `phik` to 0.12.5 or newer if using a recent `scipy`.
gotcha The optional C++ extension for computing the significance matrix (hypergeometric/Patefield method) might not build during a manual `pip install` on some systems. If it fails, `phik` will install without it, and attempting to use this method will raise a `NotImplementedError`.
Fix: Ensure your system has the necessary C++ compilers (e.g., GCC, Clang, MSVC) and `pybind11` development headers if you intend to use the hypergeometric method. Pre-built wheels for common OS are usually available.
gotcha The calculated Phi_K correlation value for interval (continuous) variables is dependent on the chosen binning. The default is 10 uniform bins, but custom binning can significantly alter results.
Fix: Carefully consider and test different binning strategies for interval variables relevant to your analysis. Use the `bins` parameter in methods like `phik_matrix()`.
gotcha Phi_K correlation is computationally expensive, especially for large datasets, due to the underlying integral calculations. This can lead to longer processing times.
Fix: Utilize the `njobs` parameter in `phik_matrix()` and `significance_matrix()` to enable parallel processing and speed up computations, or process data in chunks if memory is also a concern.
gotcha Phi_K values range from 0 to 1 and do not indicate the direction of a relationship (e.g., positive or negative correlation), only its strength.
Fix: Supplement Phi_K analysis with other methods or visualizations (e.g., scatter plots, contingency tables) to understand the nature and direction of dependencies between variables.

Install

pip install phik Install stable version

Imports

phik_matrix

import pandas as pd
import phik

df.phik_matrix()

report.correlation_report

from phik import report

report.correlation_report(df)

phik_from_hist2d
```
from phik.phik import phik_from_hist2d
```

Quickstart

This quickstart demonstrates how to load a sample dataset, calculate the Phi_K correlation matrix, and the corresponding significance matrix. It also shows how to generate a comprehensive correlation report (commented out as it requires a local PDF save and matplotlib).

import pandas as pd
import phik
from phik import resources, report

# Load example data
df = pd.read_csv(resources.fixture('fake_insurance_data.csv.gz'))

# Calculate the phi_k correlation matrix
phik_corr = df.phik_matrix()
print(phik_corr.head())

# Calculate the significance matrix
significance_matrix = df.significance_matrix()
print(significance_matrix.head())

# Generate and save a correlation report (requires matplotlib)
# report.correlation_report(df, pdf_file_name='phik_report.pdf')

view raw JSON →