Metadata-Version: 2.4
Name: pysmartcor
Version: 1.0.0
Summary: Correlation methods matched to variable types, with full inference
Author-email: "M. Harshvardhan" <harshvardhan@aus.edu>, Pritam Ranjan <pritamr@iimidr.ac.in>
Maintainer-email: "M. Harshvardhan" <harshvardhan@aus.edu>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://harshvardhaniimi.github.io/smartcor/
Project-URL: Documentation, https://harshvardhaniimi.github.io/smartcor/
Project-URL: Repository, https://github.com/harshvardhaniimi/smartcor
Keywords: correlation,statistics,polychoric,ordinal,categorical
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.9
Requires-Dist: pandas>=2.1
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5; extra == "viz"
Requires-Dist: seaborn>=0.12; extra == "viz"
Dynamic: license-file

# pysmartcor

`pysmartcor` detects variable types and selects a suitable correlation method for each pair. It supports continuous, count, binary, ordinal, and categorical variables and returns the estimate, inference, selected method, and rationale.

## Install

Once the package is on PyPI, a single call installs it together with all of its dependencies:

```bash
python -m pip install pysmartcor
```

To install the supplied archive instead (pip resolves the dependencies automatically in both cases):

```bash
python -m pip install pysmartcor.zip
```

Install the optional plotting dependencies when needed:

```bash
python -m pip install 'pysmartcor[viz]'
```

## Load the example data

The package includes `gss_2024_casestudy.csv`. This CSV is frozen for reproducibility. The examples below read the bundled copy and do not download data.

```python
from importlib.resources import as_file, files
import pandas as pd

csv_resource = files("pysmartcor").joinpath("data/gss_2024_casestudy.csv")
with as_file(csv_resource) as csv_path:
    gss = pd.read_csv(csv_path)
```

## Correlate one pair

```python
from pysmartcor import smart_cor

result = smart_cor(
    gss["coninc"],
    gss["age"],
    x_name="coninc",
    y_name="age",
    verbose=False,
)

print(result)
result.estimate
result.method
result.p_value
result.ci_lower, result.ci_upper
```

Set `assume_latent_normal` to control pairs that can use a latent-variable method:

```python
smart_cor(gss["degree"], gss["happy"], assume_latent_normal="auto")
smart_cor(gss["degree"], gss["happy"], assume_latent_normal=True)
smart_cor(gss["degree"], gss["happy"], assume_latent_normal=False)
```

The default, `"auto"`, tests the assumption for each affected pair. A binary-by-binary table is saturated, so automatic selection uses phi. Set the argument to `True` to request tetrachoric correlation.

## Build a matrix

```python
from pysmartcor import smart_cormat

columns = ["age", "coninc", "degree", "happy", "sex", "region"]
matrix = smart_cormat(
    gss[columns],
    assume_latent_normal=False,
    verbose=False,
)

matrix.correlations
matrix.methods
matrix.types
matrix.to_long()
```

Use `smart_cor_df()` when a script needs plain pandas DataFrames:

```python
from pysmartcor import smart_cor_df

plain = smart_cor_df(gss[columns], assume_latent_normal=False)
plain["correlations"]
plain["methods"]
```

## Compare methods

```python
from pysmartcor import compare_methods

comparison = compare_methods(
    gss["degree"],
    gss["happy"],
    assume_latent_normal=False,
    bootstrap=False,
    verbose=False,
)
comparison.results
```

## Plot a matrix

Plotting requires the optional `viz` dependencies.

```python
from pysmartcor.viz import cor_heatmap, method_heatmap

cor_heatmap(matrix)
method_heatmap(matrix)
```

## Methods

The package implements Pearson, Spearman, Kendall's tau, point-biserial, rank-biserial, phi, tetrachoric, Yule's Q, polychoric, polyserial, Cramer's V, Theil's U, Tschuprow's T, and Goodman-Kruskal's gamma.

Required dependencies are NumPy, SciPy, and pandas. Matplotlib and seaborn are optional plotting dependencies.

## Paper

The accompanying paper, *smartcor: Intelligent Correlation Method Selection for Mixed Variable Types* by M. Harshvardhan and Pritam Ranjan, is a work in progress.
The vignettes of the R package and the articles on the package website cover the same material.

## Authors

M. Harshvardhan (maintainer) and Pritam Ranjan.

## License

GPL (>= 3)
