correlation-network 1.0.0__py3-none-any.whl

correlation_network/__init__.py

@@ -0,0 +1,56 @@
+"""correlation-network: Build and analyze association networks from DataFrames."""
+
+from importlib.metadata import version
+
+from correlation_network._types import (
+    AssociationMethod,
+    BinningMethod,
+    CentralityMetric,
+    LayoutAlgorithm,
+)
+from correlation_network.association import (
+    AssociationStrategy,
+    AutoAssociationStrategy,
+    CorrelationRatioStrategy,
+    CramersVStrategy,
+    KendallStrategy,
+    MutualInformationStrategy,
+    PearsonStrategy,
+    PhiKStrategy,
+    SpearmanStrategy,
+)
+from correlation_network.centrality import CentralityAnalyzer
+from correlation_network.exceptions import (
+    CorrelationNetworkError,
+    InsufficientColumnsError,
+    NoCompleteObservationsError,
+    NotFittedError,
+)
+from correlation_network.network import CorrelationNetwork
+from correlation_network.visualization import NetworkVisualizer
+
+# Read from the installed metadata so pyproject.toml stays the single source
+__version__ = version("correlation-network")
+
+__all__ = [
+    "AssociationMethod",
+    "AssociationStrategy",
+    "AutoAssociationStrategy",
+    "BinningMethod",
+    "CentralityAnalyzer",
+    "CentralityMetric",
+    "CorrelationNetwork",
+    "CorrelationNetworkError",
+    "CorrelationRatioStrategy",
+    "CramersVStrategy",
+    "InsufficientColumnsError",
+    "KendallStrategy",
+    "LayoutAlgorithm",
+    "MutualInformationStrategy",
+    "NetworkVisualizer",
+    "NoCompleteObservationsError",
+    "NotFittedError",
+    "PearsonStrategy",
+    "PhiKStrategy",
+    "SpearmanStrategy",
+]

correlation_network/_graph_utils.py

@@ -0,0 +1,65 @@
+"""Shared graph utility functions."""
+
+import networkx as nx
+
+# Floor for converted distances. A |weight| of 1.0 would otherwise map to a
+# zero-length edge, collapsing two nodes into the same point for path-based
+# metrics and making closeness degenerate.
+_MIN_DISTANCE = 1e-6
+
+
+def distance_graph(graph: nx.Graph) -> nx.Graph:
+    """Return a copy with edge weights converted to distances.
+
+    Association strength and graph distance run in opposite directions: a
+    strong association (``|w|`` near 1) means two nodes are *close*, while
+    NetworkX shortest-path algorithms read the edge attribute as a *cost*.
+    Passing raw association values to Dijkstra therefore routes paths through
+    the weakest edges. This helper applies ``distance = 1 - |weight|`` so that
+    strong associations become short distances.
+
+    Parameters
+    ----------
+    graph : nx.Graph
+        A weighted undirected graph whose weights are association values.
+
+    Returns
+    -------
+    nx.Graph
+        Copy with edge weights replaced by distances, floored at a small
+        positive value so no edge has zero or negative length.
+    """
+    g = graph.copy()
+    nx.set_edge_attributes(
+        g,
+        values={
+            (u, v): max(_MIN_DISTANCE, 1.0 - abs(d.get("weight", 1.0)))
+            for u, v, d in g.edges(data=True)
+        },
+        name="weight",
+    )
+    return g
+
+
+def abs_weight_graph(graph: nx.Graph) -> nx.Graph:
+    """Return a copy of the graph with absolute edge weights.
+
+    Useful for algorithms (Dijkstra, layout) that require non-negative weights.
+
+    Parameters
+    ----------
+    graph : nx.Graph
+        A weighted undirected graph.
+
+    Returns
+    -------
+    nx.Graph
+        Copy with all edge weights replaced by their absolute values.
+    """
+    g = graph.copy()
+    nx.set_edge_attributes(
+        g,
+        values={(u, v): abs(d.get("weight", 1)) for u, v, d in g.edges(data=True)},
+        name="weight",
+    )
+    return g

correlation_network/_types.py

@@ -0,0 +1,34 @@
+"""Type aliases and literal types."""
+
+from typing import Literal
+
+CorrelationMethod = Literal["pearson", "spearman", "kendall"]
+
+AssociationMethod = Literal[
+    "pearson",
+    "spearman",
+    "kendall",
+    "cramers_v",
+    "correlation_ratio",
+    "phik",
+    "mutual_information",
+    "auto",
+]
+
+CentralityMetric = Literal[
+    "degree",
+    "strength",
+    "betweenness",
+    "eigenvector",
+    "closeness",
+]
+
+LayoutAlgorithm = Literal[
+    "kamada_kawai",
+    "spring",
+    "circular",
+    "shell",
+    "spectral",
+]
+
+BinningMethod = Literal["uniform", "quantile"]

correlation_network/_validation.py

@@ -0,0 +1,118 @@
+"""Input validation utilities."""
+
+from collections.abc import Collection
+
+import numpy as np
+import pandas as pd
+
+from correlation_network.exceptions import NoCompleteObservationsError, NotFittedError
+
+NOT_FITTED_MESSAGE = (
+    "The instance is not fitted yet. "
+    "Call 'fit' with appropriate arguments before using the estimator."
+)
+
+
+def check_is_fitted(
+    estimator: object,
+    attributes: set[str] | None = None,
+    message: str = NOT_FITTED_MESSAGE,
+) -> None:
+    """Check whether an estimator has been fitted.
+
+    Parameters
+    ----------
+    estimator : object
+        The estimator instance to check.
+    attributes : set[str] | None
+        Fitted attributes to look for. Defaults to ``{"adjacency_matrix_"}``.
+    message : str
+        Error message raised when the estimator is not fitted.
+
+    Raises
+    ------
+    NotFittedError
+        If none of the expected fitted attributes are found.
+    """
+    if attributes is None:
+        attributes = {"adjacency_matrix_"}
+    object_attrs = set(vars(estimator))
+    if not attributes.intersection(object_attrs):
+        raise NotFittedError(message)
+
+
+def complete_pair(x: pd.Series, y: pd.Series) -> tuple[pd.Series, pd.Series]:
+    """Restrict two series to the rows where both values are present.
+
+    Parameters
+    ----------
+    x : pd.Series
+        First column of the pair.
+    y : pd.Series
+        Second column of the pair, aligned with ``x``.
+
+    Returns
+    -------
+    tuple[pd.Series, pd.Series]
+        Both series, filtered to their pairwise-complete rows.
+
+    Raises
+    ------
+    NoCompleteObservationsError
+        If the two series share no rows where both values are present.
+    """
+    valid = x.notna() & y.notna()
+    if not valid.any():
+        raise NoCompleteObservationsError(columns=(str(x.name), str(y.name)))
+    return x[valid], y[valid]
+
+
+def check_pairwise_overlap(dataframe: pd.DataFrame) -> None:
+    """Ensure every column pair shares at least one complete row.
+
+    Matrix-level counterpart of :func:`complete_pair`, for strategies that
+    delegate the pairwise computation to pandas, which reports such pairs as
+    ``NaN`` rather than raising.
+
+    Parameters
+    ----------
+    dataframe : pd.DataFrame
+        Columns to check.
+
+    Raises
+    ------
+    NoCompleteObservationsError
+        For the first column pair with no rows where both values are present.
+    """
+    present = dataframe.notna().to_numpy()
+    if len(present) and present.all():
+        return
+    # Float matmul goes through BLAS; integer matmul does not and takes
+    # seconds on large frames. Counts stay exact far beyond realistic sizes.
+    present = present.astype(np.float64)
+    overlap = present.T @ present
+    rows, cols = np.nonzero(np.triu(overlap == 0, k=1))
+    if rows.size:
+        names = dataframe.columns
+        raise NoCompleteObservationsError(columns=(str(names[rows[0]]), str(names[cols[0]])))
+
+
+def check_option(name: str, value: object, options: Collection[str]) -> None:
+    """Ensure a string argument is one of the supported options.
+
+    Parameters
+    ----------
+    name : str
+        Argument name, used in the error message.
+    value : object
+        Value received.
+    options : Collection[str]
+        Accepted values.
+
+    Raises
+    ------
+    ValueError
+        If ``value`` is not in ``options``.
+    """
+    if value not in options:
+        raise ValueError(f"Unknown {name} {value!r}. Available options: {tuple(options)}")

correlation_network/association/__init__.py

@@ -0,0 +1,29 @@
+"""Association strategies for computing pairwise relationships."""
+
+from correlation_network.association._auto import AutoAssociationStrategy
+from correlation_network.association._base import AssociationStrategy
+from correlation_network.association._categorical import (
+    CorrelationRatioStrategy,
+    CramersVStrategy,
+)
+from correlation_network.association._correlation import (
+    KendallStrategy,
+    PearsonStrategy,
+    SpearmanStrategy,
+)
+from correlation_network.association._universal import (
+    MutualInformationStrategy,
+    PhiKStrategy,
+)
+
+__all__ = [
+    "AssociationStrategy",
+    "AutoAssociationStrategy",
+    "CorrelationRatioStrategy",
+    "CramersVStrategy",
+    "KendallStrategy",
+    "MutualInformationStrategy",
+    "PearsonStrategy",
+    "PhiKStrategy",
+    "SpearmanStrategy",
+]

correlation_network/association/_auto.py

@@ -0,0 +1,104 @@
+"""Auto-detection strategy that dispatches by column type."""
+
+import numpy as np
+import pandas as pd
+
+from correlation_network.association._base import AssociationStrategy
+from correlation_network.association._categorical import (
+    CorrelationRatioStrategy,
+    CramersVStrategy,
+)
+from correlation_network.association._correlation import SpearmanStrategy
+from correlation_network.association._dtypes import (
+    categorical_columns,
+    numeric_columns,
+)
+
+
+class AutoAssociationStrategy:
+    """Automatically selects the appropriate association measure per column pair.
+
+    Default dispatch:
+    - numeric-numeric: Spearman correlation
+    - categorical-categorical: Cramer's V
+    - categorical-numeric: Correlation ratio (eta)
+
+    Bool and string columns count as categorical.
+
+    Notes
+    -----
+    Numeric-numeric correlations are reduced to their **absolute value**, so
+    the resulting matrix is in [0, 1] and the sign of a negative correlation
+    is lost. This keeps the three measures on a comparable scale (Cramer's V
+    and eta are already non-negative), but means ``method="auto"`` never
+    produces negative edge weights — the positive/negative edge colouring in
+    :class:`~correlation_network.NetworkVisualizer` has no effect on such a
+    graph. Use an explicit correlation method to retain the sign.
+
+    Parameters
+    ----------
+    numeric_strategy : AssociationStrategy | None
+        Strategy for numeric-numeric pairs. Defaults to SpearmanStrategy.
+    categorical_strategy : AssociationStrategy | None
+        Strategy for categorical-categorical pairs. Defaults to CramersVStrategy.
+    mixed_strategy : AssociationStrategy | None
+        Strategy for categorical-numeric pairs. Defaults to CorrelationRatioStrategy.
+    """
+
+    def __init__(
+        self,
+        numeric_strategy: AssociationStrategy | None = None,
+        categorical_strategy: AssociationStrategy | None = None,
+        mixed_strategy: AssociationStrategy | None = None,
+    ) -> None:
+        self._numeric = numeric_strategy if numeric_strategy is not None else SpearmanStrategy()
+        self._categorical = (
+            categorical_strategy if categorical_strategy is not None else CramersVStrategy()
+        )
+        self._mixed = mixed_strategy if mixed_strategy is not None else CorrelationRatioStrategy()
+
+    def compute(self, dataframe: pd.DataFrame) -> pd.DataFrame:
+        """Compute a combined association matrix using type-aware dispatch.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            Input data with numeric and/or categorical columns.
+
+        Returns
+        -------
+        pd.DataFrame
+            Symmetric association matrix combining all column types.
+        """
+        num_cols = numeric_columns(dataframe)
+        cat_cols = categorical_columns(dataframe)
+        all_cols = num_cols + cat_cols
+        n = len(all_cols)
+        matrix = np.eye(n)
+        col_index = {col: i for i, col in enumerate(all_cols)}
+
+        # Numeric-numeric block: assign via numpy fancy indexing
+        if len(num_cols) > 1:
+            num_matrix = self._numeric.compute(dataframe[num_cols])
+            num_idx = np.array([col_index[c] for c in num_cols])
+            matrix[np.ix_(num_idx, num_idx)] = num_matrix.abs().values
+
+        # Categorical-categorical block: assign via numpy fancy indexing
+        if len(cat_cols) > 1:
+            cat_matrix = self._categorical.compute(dataframe[cat_cols])
+            cat_idx = np.array([col_index[c] for c in cat_cols])
+            matrix[np.ix_(cat_idx, cat_idx)] = cat_matrix.values
+
+        # Mixed block (cat-num): assign via numpy fancy indexing
+        if num_cols and cat_cols:
+            mixed_matrix = self._mixed.compute(dataframe[num_cols + cat_cols])
+            cat_idx = np.array([col_index[c] for c in cat_cols])
+            num_idx = np.array([col_index[c] for c in num_cols])
+            sub = mixed_matrix.loc[cat_cols, num_cols].values
+            matrix[np.ix_(cat_idx, num_idx)] = sub
+            matrix[np.ix_(num_idx, cat_idx)] = sub.T
+
+        # Restore diagonal after block assignments
+        np.fill_diagonal(matrix, 1.0)
+
+        return pd.DataFrame(data=matrix, index=all_cols, columns=all_cols)

correlation_network/association/_base.py

@@ -0,0 +1,25 @@
+"""Base protocol for association strategies."""
+
+from typing import Protocol, runtime_checkable
+
+import pandas as pd
+
+
+@runtime_checkable
+class AssociationStrategy(Protocol):
+    """Protocol that all association strategies must implement."""
+
+    def compute(self, dataframe: pd.DataFrame) -> pd.DataFrame:
+        """Compute a symmetric association matrix from a DataFrame.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            Input data with columns to compute associations for.
+
+        Returns
+        -------
+        pd.DataFrame
+            Symmetric matrix of association values.
+        """
+        ...

correlation_network/association/_categorical.py

@@ -0,0 +1,174 @@
+"""Association strategies for categorical and mixed-type pairs."""
+
+from itertools import combinations
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+
+from correlation_network._validation import complete_pair
+from correlation_network.association._dtypes import (
+    categorical_columns,
+    numeric_columns,
+)
+from correlation_network.exceptions import InsufficientColumnsError
+
+
+class CramersVStrategy:
+    """Cramer's V association measure for categorical-categorical pairs.
+
+    Computes the bias-corrected Cramer's V for all pairs of categorical
+    columns, returning values in [0, 1].
+    """
+
+    def compute(self, dataframe: pd.DataFrame) -> pd.DataFrame:
+        """Compute Cramer's V matrix for categorical columns.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            Input data. Only object, category, bool and string columns are
+            used.
+
+        Returns
+        -------
+        pd.DataFrame
+            Symmetric matrix of Cramer's V values in [0, 1].
+
+        Raises
+        ------
+        InsufficientColumnsError
+            If fewer than 2 categorical columns are present.
+        NoCompleteObservationsError
+            If a pair has no rows where both columns are present.
+        """
+        categorical_cols = categorical_columns(dataframe)
+        if len(categorical_cols) < 2:
+            raise InsufficientColumnsError(
+                method="cramers_v",
+                required="at least 2 categorical columns",
+                found=categorical_cols,
+            )
+        n_cols = len(categorical_cols)
+        matrix = np.eye(n_cols)
+
+        for i, j in combinations(range(n_cols), 2):
+            value = self._cramers_v(
+                x=dataframe[categorical_cols[i]],
+                y=dataframe[categorical_cols[j]],
+            )
+            matrix[i, j] = value
+            matrix[j, i] = value
+
+        return pd.DataFrame(data=matrix, index=categorical_cols, columns=categorical_cols)
+
+    @staticmethod
+    def _cramers_v(x: pd.Series, y: pd.Series) -> float:
+        """Compute bias-corrected Cramer's V between two categorical series."""
+        x, y = complete_pair(x, y)
+        contingency = pd.crosstab(index=x, columns=y)
+        # Yates' continuity correction (scipy's default on 2x2 tables) shrinks
+        # chi2 and would bias V downward on top of the explicit correction below.
+        chi2 = stats.chi2_contingency(observed=contingency, correction=False)[0]
+        n = contingency.values.sum()
+        r, k = contingency.shape
+
+        # Bias correction
+        phi2 = chi2 / n
+        phi2_corrected = max(0.0, phi2 - ((k - 1) * (r - 1)) / (n - 1))
+        r_corrected = r - ((r - 1) ** 2) / (n - 1)
+        k_corrected = k - ((k - 1) ** 2) / (n - 1)
+        denominator = min(k_corrected - 1, r_corrected - 1)
+
+        if denominator <= 0:
+            return 0.0
+        return np.sqrt(phi2_corrected / denominator)
+
+
+class CorrelationRatioStrategy:
+    """Correlation ratio (eta) for categorical-numeric pairs.
+
+    For each pair of (categorical, numeric) columns, computes the
+    correlation ratio in [0, 1].
+    """
+
+    def compute(self, dataframe: pd.DataFrame) -> pd.DataFrame:
+        """Compute correlation ratio matrix for mixed-type columns.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            Input data with both categorical and numeric columns.
+
+        Each pair is evaluated on the rows where both columns are present,
+        matching the pairwise-complete convention the other strategies use.
+
+        Returns
+        -------
+        pd.DataFrame
+            Symmetric matrix of correlation ratio values in [0, 1].
+
+        Raises
+        ------
+        InsufficientColumnsError
+            If either no categorical or no numeric column is present.
+        NoCompleteObservationsError
+            If a pair has no rows where both columns are present.
+        """
+        cat_cols = categorical_columns(dataframe)
+        num_cols = numeric_columns(dataframe)
+        if not cat_cols or not num_cols:
+            raise InsufficientColumnsError(
+                method="correlation_ratio",
+                required="at least 1 categorical and 1 numeric column",
+                found=cat_cols + num_cols,
+            )
+        all_cols = cat_cols + num_cols
+        n = len(all_cols)
+        matrix = np.zeros((n, n))
+        col_index = {col: i for i, col in enumerate(all_cols)}
+
+        # Per-column stats cannot be pre-computed: each pair is restricted to
+        # its own complete rows, so the grand mean and total sum of squares
+        # depend on which categorical column it is paired with.
+        for cat_col in cat_cols:
+            for num_col in num_cols:
+                value = self._correlation_ratio(
+                    categories=dataframe[cat_col],
+                    values=dataframe[num_col],
+                )
+                ci = col_index[cat_col]
+                ni = col_index[num_col]
+                matrix[ci, ni] = value
+                matrix[ni, ci] = value
+
+        np.fill_diagonal(matrix, 1.0)
+
+        return pd.DataFrame(data=matrix, index=all_cols, columns=all_cols)
+
+    @staticmethod
+    def _correlation_ratio(categories: pd.Series, values: pd.Series) -> float:
+        """Compute correlation ratio (eta) for a categorical-numeric pair.
+
+        Restricted to rows where both columns are present. Computing the total
+        sum of squares over every row while the between-group sum only covers
+        rows with a known category would divide two quantities measured on
+        different populations, understating the association.
+
+        Raises
+        ------
+        NoCompleteObservationsError
+            If the two columns share no rows where both values are present.
+        """
+        categories, values = complete_pair(categories, values)
+
+        grand_mean = values.mean()
+        ss_total = ((values - grand_mean) ** 2).sum()
+        # A constant column has no variance for the categories to explain.
+        # That is uninformative rather than undefined, so report no association.
+        if ss_total == 0:
+            return 0.0
+
+        group_stats = values.groupby(categories, observed=True).agg(["mean", "count"])
+        ss_between = (group_stats["count"] * (group_stats["mean"] - grand_mean) ** 2).sum()
+        return np.sqrt(ss_between / ss_total)

correlation_network/association/_correlation.py

@@ -0,0 +1,65 @@
+"""Correlation-based association strategies for numeric-numeric pairs."""
+
+import pandas as pd
+
+from correlation_network._types import CorrelationMethod
+from correlation_network._validation import check_pairwise_overlap
+from correlation_network.association._dtypes import numeric_columns
+from correlation_network.exceptions import InsufficientColumnsError
+
+
+class _CorrelationStrategy:
+    """Base class for pandas correlation methods."""
+
+    _method: CorrelationMethod
+
+    def compute(self, dataframe: pd.DataFrame) -> pd.DataFrame:
+        """Compute correlation matrix using pandas.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            Input data with numeric columns.
+
+        Returns
+        -------
+        pd.DataFrame
+            Symmetric correlation matrix with values in [-1, 1].
+
+        Raises
+        ------
+        InsufficientColumnsError
+            If fewer than 2 numeric columns are present.
+        NoCompleteObservationsError
+            If a pair has no rows where both columns are present.
+        """
+        numeric_cols = numeric_columns(dataframe)
+        if len(numeric_cols) < 2:
+            raise InsufficientColumnsError(
+                method=self._method,
+                required="at least 2 numeric columns",
+                found=numeric_cols,
+            )
+        matrix = dataframe.corr(method=self._method, numeric_only=True)
+        # numeric_only also keeps bool columns, so check the columns pandas
+        # actually used rather than numeric_cols
+        check_pairwise_overlap(dataframe[matrix.columns])
+        return matrix
+
+
+class PearsonStrategy(_CorrelationStrategy):
+    """Pearson linear correlation coefficient."""
+
+    _method: CorrelationMethod = "pearson"
+
+
+class SpearmanStrategy(_CorrelationStrategy):
+    """Spearman rank correlation coefficient."""
+
+    _method: CorrelationMethod = "spearman"
+
+
+class KendallStrategy(_CorrelationStrategy):
+    """Kendall tau rank correlation coefficient."""
+
+    _method: CorrelationMethod = "kendall"