correlation-network 1.0.0__tar.gz

correlation_network-1.0.0/.gitignore

@@ -0,0 +1,214 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# MCP configuration (generated from template)
+.mcp.json
+
+# Environments
+.env
+.envrc
+.venv
+.venv-*/
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Claude Code
+.claude/

correlation_network-1.0.0/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-10-24
+
+Initial release.
+
+### Added
+
+#### Core API
+
+- `CorrelationNetwork` with a scikit-learn-style `fit` / `transform` /
+  `fit_transform` pipeline
+- `from_matrix()` class method for pre-computed association matrices, from
+  pandas or Polars
+- Strategy pattern for association measures via the `AssociationStrategy`
+  protocol; any object implementing `compute(df) -> pd.DataFrame` can be passed
+  through the `strategy` parameter
+- Polars DataFrame and LazyFrame input, converted internally (via the `polars`
+  extra)
+- `correlation_network.__version__` and inline type information (PEP 561,
+  `py.typed`)
+
+#### Association measures
+
+- Correlation strategies: Pearson, Spearman, Kendall
+- Categorical strategies: Cramer's V (bias-corrected, no continuity
+  correction on 2x2 tables), Correlation Ratio (eta)
+- Universal strategies: Mutual Information (normalized, with equal-width or
+  `binning="quantile"` bins), PhiK (via the `phik` extra)
+- `AutoAssociationStrategy`, dispatching by column type: Spearman for
+  numeric pairs, Cramer's V for categorical pairs, eta for mixed pairs; bool
+  and pandas `string` columns count as categorical
+- Pairs are evaluated on their pairwise-complete rows, so missing values in one
+  column do not distort an unrelated pair
+- Inclusive thresholding: an association equal to `threshold` creates an edge
+
+#### Analysis and rendering
+
+- `CentralityAnalyzer` with degree, strength, betweenness, eigenvector and
+  closeness, individually or as a combined `summary()` table
+- Path-based metrics convert association strength to distance
+  (`distance = 1 - |weight|`), so shortest paths follow strongly associated
+  pairs; `strength()` and `eigenvector()` use absolute weights
+- `NetworkVisualizer` with 5 layouts (kamada_kawai, spring, circular, shell,
+  spectral), a continuous edge colormap centred on 0 with colorbar, a
+  two-colour positive/negative fallback, community colouring via greedy
+  modularity, centrality-scaled node sizes, per-edge alpha, and a `save()`
+  helper accepting `str` or `os.PathLike` paths
+
+#### Validation
+
+- Datetime and high-cardinality column exclusion during preprocessing; columns
+  a strategy cannot use are excluded too, all recorded in `excluded_columns_`
+  and reported through warnings that point at the caller's code
+- `CorrelationNetworkError`, the base class of every library error
+- `NotFittedError` with a `check_is_fitted` guard
+- `InsufficientColumnsError` when a method receives no columns of the type it
+  needs, carrying the `method`, the `required` types, and the columns `found`
+- `NoCompleteObservationsError` when a column pair shares no rows where both
+  values are present, carrying the offending `columns`
+- `ValueError` for an unknown `layout` or `centrality_metric`
+
+#### Project
+
+- Unit and integration test suites
+- GitHub Actions CI: lint, format, strict mypy, a test matrix over Python
+  3.10–3.13 gated at 80% coverage, and a run against the lowest supported
+  dependency versions
+- Tag-triggered release workflow publishing to TestPyPI and PyPI through
+  Trusted Publishing
+- `CONTRIBUTING.md` with development setup, checks, conventions and the
+  release procedure
+
+[1.0.0]: https://github.com/skateddu/correlation-network/releases/tag/v1.0.0

correlation_network-1.0.0/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.

correlation_network-1.0.0/PKG-INFO

@@ -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*.