correlation-network 1.0.0__py3-none-any.whl

correlation_network-1.0.0.dist-info/METADATA

@@ -0,0 +1,385 @@
+Metadata-Version: 2.5
+Name: correlation-network
+Version: 1.0.0
+Summary: Build and analyze association networks from pandas DataFrames: correlations, Cramer's V, mutual information and PhiK, with centrality analysis and visualization
+Project-URL: Homepage, https://github.com/skateddu/correlation-network
+Project-URL: Repository, https://github.com/skateddu/correlation-network
+Project-URL: Issues, https://github.com/skateddu/correlation-network/issues
+Project-URL: Changelog, https://github.com/skateddu/correlation-network/blob/main/CHANGELOG.md
+Author-email: Andrea Cadeddu <cadeddu7@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: association,centrality,correlation,cramers-v,graph,mutual-information,network,networkx,pandas
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: networkx>=3.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.11
+Provides-Extra: phik
+Requires-Dist: phik>=0.12.2; extra == 'phik'
+Provides-Extra: polars
+Requires-Dist: polars>=0.20; extra == 'polars'
+Requires-Dist: pyarrow>=14.0; extra == 'polars'
+Description-Content-Type: text/markdown
+
+# Correlation Network
+
+[![PyPI](https://img.shields.io/pypi/v/correlation-network)](https://pypi.org/project/correlation-network/)
+[![Python](https://img.shields.io/pypi/pyversions/correlation-network?logo=python&logoColor=white)](https://pypi.org/project/correlation-network/)
+[![CI](https://github.com/skateddu/correlation-network/actions/workflows/ci.yml/badge.svg)](https://github.com/skateddu/correlation-network/actions/workflows/ci.yml)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-d4aa00)
+![Type: Typed](https://img.shields.io/badge/typing-typed-blue)
+
+Python library that builds association networks from pandas DataFrames. Computes pairwise association measures (correlations, Cramer's V, mutual information, etc.), applies threshold filtering, and produces NetworkX graphs with centrality analysis and visualization.
+
+## Features
+
+- **Association methods**: Pearson, Spearman, Kendall, Cramer's V, Correlation Ratio, Mutual Information, PhiK
+- **Auto-detection**: selects the right measure based on column types (numeric, categorical, mixed)
+- **API**: scikit-learn-style `fit()` / `transform()` / `fit_transform()` pipeline
+- **Centrality**: degree, strength, betweenness, eigenvector, closeness — individual or summary table
+- **Visualization**: continuous colormap, community detection coloring, centrality-scaled nodes, per-edge alpha
+- **Extensible**: any object implementing the `AssociationStrategy` protocol can be plugged in
+
+## Dependencies
+
+| Package | Description | Link |
+|---------|-------------|------|
+| [NetworkX](https://networkx.org/) | Graph data structures, algorithms, and layout | [Docs](https://networkx.org/documentation/stable/) |
+| [pandas](https://pandas.pydata.org/) | DataFrame input and association matrix storage | [Docs](https://pandas.pydata.org/docs/) |
+| [NumPy](https://numpy.org/) | Array operations for matrix computation | [Docs](https://numpy.org/doc/stable/) |
+| [SciPy](https://scipy.org/) | Chi-squared test (Cramer's V), entropy (Mutual Information) | [Docs](https://docs.scipy.org/doc/scipy/) |
+| [Matplotlib](https://matplotlib.org/) | Graph rendering, colormaps, and figure export | [Docs](https://matplotlib.org/stable/contents.html) |
+
+Optional extras:
+
+| Extra | Description | Link |
+|-------|-------------|------|
+| `phik` | PhiK correlation (works on any column type pair) | [Docs](https://phik.readthedocs.io/) |
+| `polars` | Accept Polars DataFrames as input (auto-converted to pandas) | [Docs](https://docs.pola.rs/) |
+
+## Installation
+
+Requires Python >= 3.10.
+
+```bash
+pip install correlation-network
+```
+
+With optional extras:
+
+```bash
+pip install "correlation-network[phik]"         # PhiK correlation support
+pip install "correlation-network[polars]"       # Polars DataFrame support
+pip install "correlation-network[phik,polars]"
+```
+
+With [uv](https://docs.astral.sh/uv/): `uv add correlation-network` (extras:
+`uv add "correlation-network[phik]"`).
+
+## Quick Start
+
+### Python API
+
+```python
+import pandas as pd
+from correlation_network import CorrelationNetwork, CentralityAnalyzer, NetworkVisualizer
+
+# Build the network (default: method="pearson", threshold=0.5)
+net = CorrelationNetwork(method="spearman", threshold=0.3)
+graph = net.fit_transform(df)
+
+# Analyze centrality
+analyzer = CentralityAnalyzer(graph)
+rankings = analyzer.summary()
+print(rankings)
+
+# Visualize
+viz = NetworkVisualizer(graph)
+fig = viz.plot(
+    centrality_metric="degree",
+    community_colors=True,
+    title="Association Network",
+)
+```
+
+### Save directly
+
+```python
+viz.save("network.png", dpi=150, community_colors=True, title="My Network")
+```
+
+### From a pre-computed matrix
+
+```python
+# Use a correlation matrix you already have
+net = CorrelationNetwork.from_matrix(my_matrix, threshold=0.5)
+graph = net.transform()
+```
+
+### With Polars DataFrames
+
+```python
+import polars as pl
+
+df_polars = pl.read_csv("data.csv")
+graph = CorrelationNetwork(method="pearson", threshold=0.5).fit_transform(df_polars)
+```
+
+## Constructor Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `method` | `"pearson"` | Association method (see table below) |
+| `threshold` | `0.5` | Minimum `\|weight\|` to keep an edge (inclusive) |
+| `strategy` | `None` | Custom `AssociationStrategy` instance (overrides `method`) |
+| `cardinality_threshold` | `0.95` | Exclude index-like columns with `nunique/nrows >= threshold` (see below) |
+
+## Preprocessing
+
+Before computing associations, `fit()` automatically excludes:
+
+- **Datetime columns** (not suitable for correlation)
+- **High-cardinality columns** where `nunique / nrows >= cardinality_threshold` (e.g. IDs, UUIDs).
+  Integer columns are excluded only when their values also form a consecutive
+  sequence (row numbers, auto-increment keys, even if shuffled): on small frames
+  genuine integer measurements such as age or income are near-unique too
+
+After computing the matrix, columns the strategy cannot use (e.g. strings with
+`method="pearson"`) are reported with a warning instead of silently disappearing
+from the graph.
+
+All these columns are stored in `net.excluded_columns_` after fitting:
+
+```python
+net = CorrelationNetwork(method="auto", threshold=0.3)
+net.fit(df)
+print(net.excluded_columns_)  # ['timestamp', 'row_id']
+```
+
+## Association Methods
+
+| Method | Strategy Class | Column Types | Output Range |
+|--------|---------------|-------------|--------------|
+| `pearson` | `PearsonStrategy` | numeric — numeric | [-1, 1] |
+| `spearman` | `SpearmanStrategy` | numeric — numeric | [-1, 1] |
+| `kendall` | `KendallStrategy` | numeric — numeric | [-1, 1] |
+| `cramers_v` | `CramersVStrategy` | categorical — categorical | [0, 1] |
+| `correlation_ratio` | `CorrelationRatioStrategy` | categorical — numeric | [0, 1] |
+| `mutual_information` | `MutualInformationStrategy` | any | [0, 1] |
+| `phik` | `PhiKStrategy` | any | [0, 1] |
+| `auto` | `AutoAssociationStrategy` | auto-detects types | [0, 1] |
+
+Each method requires columns of the type it operates on. Passing a DataFrame
+that cannot satisfy it raises `InsufficientColumnsError` (attributes `method`,
+`required`, `found`) rather than silently returning an empty matrix.
+
+### Missing values
+
+Every method evaluates a column pair on the rows where **both** values are
+present (pairwise-complete observations), the same convention `pandas.corr()`
+uses. Rows missing elsewhere in the DataFrame do not affect an unrelated pair.
+
+If a pair shares no complete rows at all, its association is undefined and
+`NoCompleteObservationsError` (attribute `columns`) is raised rather than a
+misleading zero.
+
+> **Mutual information and bin count.** `MutualInformationStrategy` discretizes
+> numeric columns into `n_bins` (default 10) before computing MI. With few
+> samples per bin the estimate is biased upward: on 200 rows, two *independent*
+> columns score ≈0.10 at `n_bins=10` but ≈0.50 at `n_bins=50`. Raise `n_bins`
+> only when you have the rows to support it, and set `threshold` accordingly.
+>
+> Bins are equal-width by default, so a single extreme outlier can squeeze
+> almost every row into one bin and hide a real relationship. Pass
+> `binning="quantile"` for equal-frequency bins on skewed or outlier-prone data:
+>
+> ```python
+> from correlation_network import MutualInformationStrategy
+>
+> net = CorrelationNetwork(strategy=MutualInformationStrategy(binning="quantile"))
+> ```
+
+### Error handling
+
+All library errors derive from `CorrelationNetworkError`, so a single `except`
+catches any of them. Each one also keeps its built-in base (`ValueError`, and
+`AttributeError` for `NotFittedError`), so existing handlers keep working.
+
+### Auto mode
+
+When `method="auto"`, the library detects column dtypes and dispatches:
+
+| Pair type | Default strategy |
+|-----------|-----------------|
+| numeric — numeric | Spearman |
+| categorical — categorical | Cramer's V |
+| mixed | Correlation Ratio |
+
+Bool and string columns count as categorical.
+
+```python
+net = CorrelationNetwork(method="auto", threshold=0.3)
+graph = net.fit_transform(df)
+```
+
+> **Auto mode discards the sign.** Numeric correlations are reduced to their
+> absolute value so all three measures share a [0, 1] scale (Cramer's V and eta
+> are non-negative by definition). A Spearman of `-0.98` becomes `0.98`, and the
+> positive/negative edge colouring in `NetworkVisualizer` has no effect on such a
+> graph. Use an explicit correlation method when the direction matters.
+
+### Custom strategies
+
+Any object implementing the `AssociationStrategy` protocol (`compute(df) -> pd.DataFrame`) can be used:
+
+```python
+net = CorrelationNetwork(strategy=my_custom_strategy, threshold=0.3)
+```
+
+## Centrality Analysis
+
+| Method | Description |
+|--------|-------------|
+| `degree()` | Normalized degree: connected neighbors as fraction of (n-1) |
+| `strength()` | Sum of absolute edge weights |
+| `betweenness()` | Frequency on shortest paths (weights converted to distances) |
+| `eigenvector()` | Influence based on connections to high-scoring nodes (absolute weights) |
+| `closeness()` | Inverse average distance to all other nodes (weights converted to distances) |
+| `summary()` | DataFrame with all metrics combined |
+
+```python
+analyzer = CentralityAnalyzer(graph)
+
+analyzer.degree()   # pd.Series, sorted descending
+analyzer.summary()  # pd.DataFrame with all 5 metrics
+```
+
+### Association strength vs. graph distance
+
+`betweenness()` and `closeness()` are path-based, and NetworkX reads the edge
+attribute it is given as a **cost**. Association values run the other way — a
+weight near 1 means two nodes are *close*, not far apart. Both metrics therefore
+convert weights with `distance = 1 - |weight|` before running Dijkstra, so
+shortest paths follow strongly associated pairs.
+
+`strength()` is a magnitude sum rather than a path metric, so it keeps using the
+raw absolute weights. `eigenvector()` also runs on absolute weights: signed
+weights can yield negative scores, which have no meaning as centrality.
+
+The default `kamada_kawai` layout applies the same `1 - |weight|` conversion,
+since it reads weights as target distances: strongly associated nodes are drawn
+close together.
+
+## Visualization
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `layout` | `kamada_kawai` | Layout algorithm (`spring`, `circular`, `shell`, `spectral`) |
+| `centrality_metric` | `None` | Scale node size by centrality (`degree`, `strength`, etc.) |
+| `figsize` | `(10, 8)` | Figure size in inches |
+| `dpi` | `100` | Figure resolution |
+| `node_color` | `tab:blue` | Node color (ignored when `community_colors=True`) |
+| `community_colors` | `False` | Color nodes by greedy modularity community |
+| `edge_cmap` | `RdYlGn` | Diverging colormap for edges, centred at 0 (`None` for two-color mode) |
+| `positive_edge_color` | `darkgreen` | Positive edge color (two-color mode only) |
+| `negative_edge_color` | `tab:red` | Negative edge color (two-color mode only) |
+| `font_size` | `10` | Font size for node labels |
+| `edge_label_font_size` | `8` | Font size for edge weight labels |
+| `show_edge_labels` | `True` | Display edge weight labels |
+| `title` | `None` | Plot title |
+
+```python
+viz = NetworkVisualizer(graph)
+
+fig = viz.plot(
+    layout="kamada_kawai",
+    centrality_metric="degree",
+    community_colors=True,
+    edge_cmap="RdYlGn",
+    title="My Network",
+)
+
+viz.save("network.png", dpi=150, community_colors=True)
+```
+
+## Development
+
+Setup, test commands and contribution guidelines are in [CONTRIBUTING.md](https://github.com/skateddu/correlation-network/blob/main/CONTRIBUTING.md).
+
+### Architecture
+
+The library follows a pipeline pattern: DataFrame in, graph out.
+
+```mermaid
+graph LR
+    A[DataFrame] -->|fit| B[Association Matrix]
+    B -->|transform| C[nx.Graph]
+    C --> D[CentralityAnalyzer]
+    C --> E[NetworkVisualizer]
+```
+
+| Concept | Implementation | Module |
+|---------|---------------|--------|
+| Pluggable metrics | `AssociationStrategy` Protocol | `association/_base.py` |
+| Metric dispatch | `_STRATEGY_REGISTRY` dict | `network.py` |
+| Fit/transform pipeline | scikit-learn-style API | `network.py` |
+| Graph centrality | NetworkX algorithms wrapper | `centrality.py` |
+| Negative weight handling | `abs_weight_graph()` helper | `_graph_utils.py` |
+| Association → distance | `distance_graph()` helper | `_graph_utils.py` |
+| Fitted state guard | `check_is_fitted()` function | `_validation.py` |
+| Rendering | Matplotlib + NetworkX drawing | `visualization.py` |
+
+### Project Structure
+
+```
+correlation-network/
+├── src/correlation_network/
+│   ├── __init__.py           # Public API exports
+│   ├── network.py            # CorrelationNetwork (main entry point)
+│   ├── centrality.py         # CentralityAnalyzer (5 metrics + summary)
+│   ├── visualization.py      # NetworkVisualizer (5 layouts, colormap, community colors)
+│   ├── exceptions.py         # CorrelationNetworkError base + NotFittedError, InsufficientColumnsError, NoCompleteObservationsError
+│   ├── py.typed              # PEP 561 marker: ships inline type information
+│   ├── _types.py             # Literal type aliases (AssociationMethod, BinningMethod, CentralityMetric, LayoutAlgorithm, CorrelationMethod)
+│   ├── _validation.py        # Fitted guard, missing-data checks, option validation
+│   ├── _graph_utils.py       # Shared graph utilities (abs_weight_graph, distance_graph)
+│   └── association/
+│       ├── __init__.py       # Re-exports all strategies
+│       ├── _base.py          # AssociationStrategy (Protocol)
+│       ├── _dtypes.py        # Numeric vs categorical column detection
+│       ├── _correlation.py   # Pearson, Spearman, Kendall
+│       ├── _categorical.py   # Cramer's V, Correlation Ratio (eta)
+│       ├── _universal.py     # PhiK, Mutual Information
+│       └── _auto.py          # Auto-detection + dispatch
+├── tests/
+│   ├── conftest.py           # Shared fixtures (numeric, categorical, mixed DataFrames)
+│   ├── unit/                 # One test file per module
+│   └── integration/          # End-to-end pipeline tests
+├── .github/workflows/ci.yml  # Lint, format, mypy, test matrix (3.10–3.13), lowest dependency versions
+├── pyproject.toml            # Metadata, dependencies, ruff, mypy and pytest config
+├── uv.lock                   # Locked dependency versions
+├── CHANGELOG.md              # Keep a Changelog format
+├── CONTRIBUTING.md           # Development setup and workflow
+└── LICENSE                   # MIT
+```
+
+## References
+
+- Newman, M. E. J. (2010). *Networks: An Introduction*. Oxford University Press.
+- Cramér, H. (1946). *Mathematical Methods of Statistics*. Princeton University Press.
+- Bergsma, W. (2018). [A new correlation coefficient](https://arxiv.org/abs/1712.05289). *arXiv:1712.05289* — PhiK foundation.
+- Reshef, D. et al. (2011). [Detecting Novel Associations in Large Data Sets](https://doi.org/10.1126/science.1205438). *Science*.

correlation_network-1.0.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+correlation_network/__init__.py,sha256=A4iuT41a3Weq9U2p4OQFBUqTqTyOrbyZw2Rh-K4IOfg,1528
+correlation_network/_graph_utils.py,sha256=cvvBMJi5SuNdvTIHokaQvyX1Z_upY2_982zX747KYco,1965
+correlation_network/_types.py,sha256=3Tbyv5F6hu-uJV3GJWRBf-4XKQemrqgY9X9E8RlzC8Y,572
+correlation_network/_validation.py,sha256=hUKez1UtD9xU5ogvOPzHtWiTGBTuzMp9XAIjuuNWjUM,3462
+correlation_network/centrality.py,sha256=byNPoS22mh1XoRcboG0cR1rxE2Yze0VYwBgGp-UntHY,4036
+correlation_network/exceptions.py,sha256=QhYhR_Ra-PUuGK6eLPsIb6IfRroVQ6WXIXPBOQEQ3C8,2117
+correlation_network/network.py,sha256=hKyZjmaanzwErEuNVTSs7-lr1MK-PkanPhKJrv_Kprw,14835
+correlation_network/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+correlation_network/visualization.py,sha256=CANiCTOgEsla0utzD_fQt1fEem0ODSmDlgpoclEmBPE,13565
+correlation_network/association/__init__.py,sha256=psNUEM3zzkrTlT2UkwSoTX1SflH_2uia-nbVJGA8q6o,810
+correlation_network/association/_auto.py,sha256=q4cOnuJy_Q-BnaLgNKkvm-5BsJ_mqggXPy5icB6lwr8,4239
+correlation_network/association/_base.py,sha256=hfRpn-oLAfDdjHAF0a8a6uMuXxLUldXV2MHzDSSLaio,642
+correlation_network/association/_categorical.py,sha256=rrTuzYaUqoE217IqX6kENKlnD2AWQy0E6_2ZbcDDIEk,6379
+correlation_network/association/_correlation.py,sha256=KAVbmLk94bR1eG2W3lCGVvcXHYjMs7aUyGhLrK5mhDQ,2032
+correlation_network/association/_dtypes.py,sha256=z9MMYdEY50WiV_Xp-D9c1qdk3aQcNxwSzk7epXzGYE4,1219
+correlation_network/association/_universal.py,sha256=wDh9ENdbcluHxzo3W_Fe3Nrg5yOcv3vWpw7VLnzjgO8,5379
+correlation_network-1.0.0.dist-info/METADATA,sha256=4ha0V4qV9i3E7oxu53Z2JSsOE77f6us8JNgsBYDGurs,16881
+correlation_network-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+correlation_network-1.0.0.dist-info/licenses/LICENSE,sha256=dT_fixOtJZW_T2IpUZSTF4YLnY8DpDhgoHHOsRRDTxU,1071
+correlation_network-1.0.0.dist-info/RECORD,,

correlation_network-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

correlation_network-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrea Cadeddu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.