correlation-network 1.0.0__py3-none-any.whl

correlation_network/association/_dtypes.py

@@ -0,0 +1,47 @@
+"""Column type detection shared by the type-aware association strategies."""
+
+from typing import Literal
+
+import pandas as pd
+
+# bool and pandas' "string" dtype hold labels, not quantities. select_dtypes
+# leaves both out of "number", so unless they are listed here every
+# type-aware strategy drops them without notice.
+CATEGORICAL_DTYPES: tuple[Literal["object", "category", "bool", "string"], ...] = (
+    "object",
+    "category",
+    "bool",
+    "string",
+)
+
+
+def categorical_columns(dataframe: pd.DataFrame) -> list[str]:
+    """Return the columns treated as categorical.
+
+    Parameters
+    ----------
+    dataframe : pd.DataFrame
+        Input data.
+
+    Returns
+    -------
+    list[str]
+        Object, category, bool and string columns, in frame order.
+    """
+    return dataframe.select_dtypes(include=list(CATEGORICAL_DTYPES)).columns.tolist()
+
+
+def numeric_columns(dataframe: pd.DataFrame) -> list[str]:
+    """Return the columns treated as numeric (bool excluded).
+
+    Parameters
+    ----------
+    dataframe : pd.DataFrame
+        Input data.
+
+    Returns
+    -------
+    list[str]
+        Numeric columns, in frame order.
+    """
+    return dataframe.select_dtypes(include="number").columns.tolist()

correlation_network/association/_universal.py

@@ -0,0 +1,162 @@
+"""Universal association strategies that work with any column type."""
+
+from itertools import combinations
+from typing import get_args
+
+import numpy as np
+import pandas as pd
+from scipy.stats import entropy
+
+from correlation_network._types import BinningMethod
+from correlation_network._validation import (
+    check_option,
+    check_pairwise_overlap,
+    complete_pair,
+)
+from correlation_network.association._dtypes import numeric_columns
+from correlation_network.exceptions import InsufficientColumnsError
+
+
+class PhiKStrategy:
+    """PhiK correlation coefficient (requires optional phik dependency).
+
+    Works with any combination of column types. Returns values in [0, 1].
+    """
+
+    def compute(self, dataframe: pd.DataFrame) -> pd.DataFrame:
+        """Compute PhiK correlation matrix.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            Input data with any column types.
+
+        Returns
+        -------
+        pd.DataFrame
+            Symmetric matrix of PhiK values in [0, 1].
+
+        Raises
+        ------
+        ImportError
+            If the ``phik`` package is not installed.
+        NoCompleteObservationsError
+            If a pair has no rows where both columns are present.
+        """
+        try:
+            import phik  # noqa: F401
+        except ImportError:
+            raise ImportError(
+                "PhiK strategy requires the 'phik' package. "
+                "Install it with: pip install 'correlation-network[phik]'"
+            ) from None
+
+        # phik reports pairs without overlapping rows as NaN instead of raising
+        check_pairwise_overlap(dataframe)
+        # phik registers this DataFrame method at import time, which the
+        # pandas stubs cannot know about
+        return dataframe.phik_matrix()  # type: ignore[operator]
+
+
+class MutualInformationStrategy:
+    """Normalized mutual information for any column type.
+
+    Discretizes numeric columns before computing MI. Returns values in [0, 1].
+
+    Parameters
+    ----------
+    n_bins : int
+        Number of bins for numeric columns. Default ``10``.
+    binning : BinningMethod
+        ``"uniform"`` (default) splits the value range into equal-width bins;
+        ``"quantile"`` uses equal-frequency bins, which a few extreme values
+        cannot squeeze into a single bin. Duplicate quantile edges are merged,
+        so heavily repeated values may yield fewer than ``n_bins`` bins.
+
+    Raises
+    ------
+    ValueError
+        If ``binning`` is not a supported method.
+    """
+
+    def __init__(self, n_bins: int = 10, binning: BinningMethod = "uniform") -> None:
+        check_option(name="binning", value=binning, options=get_args(BinningMethod))
+        self.n_bins = n_bins
+        self.binning = binning
+
+    def compute(self, dataframe: pd.DataFrame) -> pd.DataFrame:
+        """Compute normalized mutual information matrix.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            Input data with any column types.
+
+        Returns
+        -------
+        pd.DataFrame
+            Symmetric matrix of normalized MI values in [0, 1].
+
+        Raises
+        ------
+        InsufficientColumnsError
+            If fewer than 2 columns are present.
+        NoCompleteObservationsError
+            If a pair has no rows where both columns are present.
+        """
+        if len(dataframe.columns) < 2:
+            raise InsufficientColumnsError(
+                method="mutual_information",
+                required="at least 2 columns",
+                found=dataframe.columns.tolist(),
+            )
+        discretized = self._discretize(dataframe)
+        columns = discretized.columns.tolist()
+        n = len(columns)
+        matrix = np.eye(n)
+
+        for i, j in combinations(range(n), 2):
+            value = self._normalized_mi(
+                x=discretized[columns[i]],
+                y=discretized[columns[j]],
+            )
+            matrix[i, j] = value
+            matrix[j, i] = value
+
+        return pd.DataFrame(data=matrix, index=columns, columns=columns)
+
+    def _discretize(self, dataframe: pd.DataFrame) -> pd.DataFrame:
+        """Discretize numeric columns into bins."""
+        result = dataframe.copy()
+        numeric_cols = numeric_columns(result)
+        result[numeric_cols] = result[numeric_cols].apply(self._bin)
+        return result
+
+    def _bin(self, column: pd.Series) -> pd.Series:
+        """Map one numeric column to integer bin labels."""
+        match self.binning:
+            case "quantile":
+                return pd.qcut(column, q=self.n_bins, labels=False, duplicates="drop")
+            case _:
+                return pd.cut(column, bins=self.n_bins, labels=False)
+
+    @staticmethod
+    def _normalized_mi(x: pd.Series, y: pd.Series) -> float:
+        """Compute normalized mutual information between two discrete series."""
+        x_clean, y_clean = complete_pair(x, y)
+
+        contingency = pd.crosstab(index=x_clean, columns=y_clean)
+        joint_prob = contingency.values / contingency.values.sum()
+
+        marginal_x = joint_prob.sum(axis=1)
+        marginal_y = joint_prob.sum(axis=0)
+
+        h_x = entropy(marginal_x)
+        h_y = entropy(marginal_y)
+
+        if h_x == 0 or h_y == 0:
+            return 0.0
+
+        h_xy = entropy(joint_prob.ravel())
+        mi = h_x + h_y - h_xy
+        return float(mi / np.sqrt(h_x * h_y))

correlation_network/centrality.py

@@ -0,0 +1,124 @@
+"""Centrality analysis for association networks."""
+
+import functools
+
+import networkx as nx
+import pandas as pd
+
+from correlation_network._graph_utils import abs_weight_graph, distance_graph
+
+
+class CentralityAnalyzer:
+    """Compute centrality metrics for a NetworkX graph.
+
+    Parameters
+    ----------
+    graph : nx.Graph
+        A weighted undirected graph.
+    """
+
+    def __init__(self, graph: nx.Graph) -> None:
+        self.graph = graph
+
+    @functools.cached_property
+    def _abs_graph(self) -> nx.Graph:
+        """Graph copy with absolute weights, for magnitude-based metrics."""
+        return abs_weight_graph(self.graph)
+
+    @functools.cached_property
+    def _distance_graph(self) -> nx.Graph:
+        """Graph copy with weights as distances, for path-based metrics (Dijkstra)."""
+        return distance_graph(self.graph)
+
+    def degree(self) -> pd.Series:
+        """Normalized degree centrality.
+
+        Returns
+        -------
+        pd.Series
+            Fraction of possible connections for each node, sorted descending.
+        """
+        return pd.Series(nx.degree_centrality(self.graph), name="degree").sort_values(
+            ascending=False
+        )
+
+    def strength(self) -> pd.Series:
+        """Weighted degree (sum of absolute edge weights).
+
+        Returns
+        -------
+        pd.Series
+            Weighted degree for each node, sorted descending.
+        """
+        weighted_degree = dict(self._abs_graph.degree(weight="weight"))
+        return pd.Series(weighted_degree, name="strength").sort_values(ascending=False)
+
+    def betweenness(self) -> pd.Series:
+        """Betweenness centrality.
+
+        Association values are converted to distances (``1 - |weight|``) so
+        that shortest paths run through strongly associated pairs.
+
+        Returns
+        -------
+        pd.Series
+            Betweenness centrality for each node, sorted descending.
+        """
+        return pd.Series(
+            nx.betweenness_centrality(self._distance_graph, weight="weight"),
+            name="betweenness",
+        ).sort_values(ascending=False)
+
+    def eigenvector(self) -> pd.Series:
+        """Eigenvector centrality.
+
+        Computed on absolute weights: with signed weights the adjacency matrix
+        loses the Perron-Frobenius guarantee of a non-negative leading
+        eigenvector, and nodes can receive negative scores. Falls back to the
+        NumPy solver if the power iteration does not converge.
+
+        Returns
+        -------
+        pd.Series
+            Eigenvector centrality for each node, sorted descending.
+        """
+        try:
+            values = nx.eigenvector_centrality(self._abs_graph, weight="weight")
+        except nx.PowerIterationFailedConvergence:
+            values = nx.eigenvector_centrality_numpy(self._abs_graph, weight="weight")
+        return pd.Series(values, name="eigenvector").sort_values(ascending=False)
+
+    def closeness(self) -> pd.Series:
+        """Closeness centrality.
+
+        Association values are converted to distances (``1 - |weight|``) so
+        that strongly associated nodes are treated as close together.
+
+        Returns
+        -------
+        pd.Series
+            Closeness centrality for each node, sorted descending.
+        """
+        return pd.Series(
+            nx.closeness_centrality(self._distance_graph, distance="weight"),
+            name="closeness",
+        ).sort_values(ascending=False)
+
+    def summary(self) -> pd.DataFrame:
+        """Compute all centrality metrics and return as a DataFrame.
+
+        Returns
+        -------
+        pd.DataFrame
+            DataFrame with columns: degree, strength, betweenness,
+            eigenvector, closeness. Indexed by node name.
+        """
+        return pd.DataFrame(
+            {
+                "degree": self.degree(),
+                "strength": self.strength(),
+                "betweenness": self.betweenness(),
+                "eigenvector": self.eigenvector(),
+                "closeness": self.closeness(),
+            }
+        )

correlation_network/exceptions.py

@@ -0,0 +1,61 @@
+"""Custom exception hierarchy for correlation-network."""
+
+
+class CorrelationNetworkError(Exception):
+    """Base class for all errors raised by correlation-network.
+
+    Every concrete error also inherits from the built-in it historically
+    derived from (``ValueError``, ``AttributeError``), so existing handlers
+    keep working.
+    """
+
+
+class NotFittedError(CorrelationNetworkError, ValueError, AttributeError):
+    """Raised when an estimator is used before fitting.
+
+    Inherits from both ValueError and AttributeError for compatibility
+    with scikit-learn-style exception handling.
+    """
+
+
+class NoCompleteObservationsError(CorrelationNetworkError, ValueError):
+    """Raised when a column pair shares no rows where both values are present.
+
+    Attributes
+    ----------
+    columns : tuple[str, str]
+        The pair of column names with no overlapping complete rows.
+    """
+
+    def __init__(self, columns: tuple[str, str]) -> None:
+        self.columns = columns
+        left, right = columns
+        super().__init__(
+            f"Columns {left!r} and {right!r} share no rows where both values "
+            f"are present, so their association is undefined. Drop or impute "
+            f"the missing values, or exclude one of the columns."
+        )
+
+
+class InsufficientColumnsError(CorrelationNetworkError, ValueError):
+    """Raised when a strategy receives too few columns of the type it needs.
+
+    Attributes
+    ----------
+    method : str
+        Name of the strategy that rejected the input.
+    required : str
+        Human-readable description of the columns the strategy needs.
+    found : list[str]
+        Columns of the required type that were actually present.
+    """
+
+    def __init__(self, method: str, required: str, found: list[str]) -> None:
+        self.method = method
+        self.required = required
+        self.found = found
+        super().__init__(
+            f"{method} requires {required}, but the DataFrame provides "
+            f"{len(found)}: {found}. Pick a method suited to these column "
+            f"types, or select only compatible columns."
+        )