Metadata-Version: 2.4
Name: pcorr
Version: 0.6.0
Summary: Pairwise Pearson correlations with p-values and multiple-comparison correction
Author: Mark
License-Expression: MIT
Project-URL: Repository, https://github.com/Cyber200potato/pcorr
Project-URL: Issues, https://github.com/Cyber200potato/pcorr/issues
Keywords: correlation,pearson,p-value,statistics,multiple-comparisons
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: pandas>=1.2
Requires-Dist: scipy>=1.6
Provides-Extra: full
Requires-Dist: statsmodels>=0.13; extra == "full"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: statsmodels>=0.13; extra == "test"
Dynamic: license-file

# pcorr

Compute all pairwise Pearson/Spearman correlations between numeric columns in a `pandas.DataFrame` — like `pandas.DataFrame.corr()`, but with **p-values for each pair** and **multiple-comparison correction** in one call.

## Installation

```bash
pip install pcorr
pip install "pcorr[full]"
```

## Usage

```python
import pandas as pd
from pcorr import corr_pairwise, corr_table, show_table

df = pd.read_csv("data.csv")

# Long (tidy) format: one row per pair
table = corr_pairwise(df, method="fdr_bh", alpha=0.05)
print(table)
#   var1 var2    n      r  p_corrected  p_value  significant
# 0    x    y  200  0.967       0.0000  0.0000         True
# 1    x    z  200 -0.894       0.0000  0.0000         True
# ...

# Two square tables (r and p) rendered as lower-triangle output
tables = corr_table(df, method="bonferroni")
tables["r"]  # coefficients
tables["p"]  # p-values (raw when method="none", otherwise corrected)

# Convenience display (renders nicely in Jupyter, prints in console)
show_table(df, method="bonferroni")
```

## API

- `corr_pairwise(df, ...)` — tidy table: one row per column pair.
- `corr_table(df, ...)` — two square tables (coefficients and p-values) in a lower-triangle style.
- `show_table(df, ...)` — displays/prints `corr_table(...)`.
- `corr_matrices(df, ...)` — alias for `corr_table(...)` (compatibility).

## Output format

### corr_pairwise

Always returns:

- `var1`, `var2` — column names
- `n` — number of valid observations in the pair (after pairwise NaN deletion)
- `r` — correlation coefficient
- `significant` — `p < alpha` for the p-value used for significance

P-value columns depend on `method`:

- `method="none"` returns `p_value` (raw p-value)
- any correction (e.g. `bonferroni`, `fdr_bh`, `holm`) returns `p_corrected` and `p_value` (raw)

Raw p-values example:

```python
from pcorr import corr_pairwise
out = corr_pairwise(df, method="none")
```

### corr_table / corr_matrices

Returns a dict with two `DataFrame`s:

- `tables["r"]` — coefficients (lower triangle filled), diagonal `"1"`, upper triangle blank
- `tables["p"]` — p-values in the same layout, diagonal `"—"`
  - raw p-values when `method="none"`
  - corrected p-values for any correction method

## Parameters

| parameter  | meaning                                                         |
|-----------|------------------------------------------------------------------|
| `columns` | which columns to use (default: all numeric)                      |
| `corr`    | `"pearson"` or `"spearman"`                                      |
| `method`  | `bonferroni`, `fdr_bh`, `holm`, `sidak`, `none`, ...             |
| `alpha`   | threshold for `significant`                                      |
| `min_n`   | minimum valid observations per pair (pairwise NaN deletion)      |
| `round_to`| rounding for r/p columns (None disables rounding)                |

## Notes

- Pairwise NaN deletion: each pair has its own `n`.
- Constant columns and pairs with `n < min_n` are handled without crashing.
- `corr_pairwise` is sorted by the p-value used for ranking (corrected when applicable).

## P-value correction methods

- `method="none"` and `method="bonferroni"` work without statsmodels.
- Other methods use `statsmodels.stats.multitest.multipletests` and require statsmodels (install via the `full` extra).
