pycatdap 0.2.0__py3-none-any.whl

pycatdap/__init__.py

@@ -0,0 +1,30 @@
+"""pycatdap: Python implementation of CATDAP (CATegorical Data Analysis Program).
+
+CATDAP applies Akaike's Information Criterion (AIC) to categorical data analysis.
+Originally developed by Sakamoto & Katsura (1980) at the Institute of Statistical
+Mathematics, Japan.
+
+Main functions:
+    catdap1 -- Pairwise AIC evaluation of categorical variable
+               associations
+    catdap2 -- Optimal explanatory variable subset search
+               with continuous variable binning
+"""
+
+from __future__ import annotations
+
+from pycatdap._version import (
+    __version__,
+    __version_tuple__,
+)
+from pycatdap.catdap1 import Catdap1Result, catdap1
+from pycatdap.catdap2 import Catdap2Result, catdap2
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "Catdap1Result",
+    "Catdap2Result",
+    "catdap1",
+    "catdap2",
+]

pycatdap/_aic.py

@@ -0,0 +1,194 @@
+"""Core AIC computation for contingency tables.
+
+Implements the AIC statistics for two-way contingency tables as defined by
+Sakamoto & Katsura (1980).  Zero-frequency cells use the convention
+``0 * ln(0) = 0``.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import numpy.typing as npt
+
+# ---------------------------------------------------------------------------
+# Safe x*log(y) with 0*log(0) = 0
+# ---------------------------------------------------------------------------
+
+try:
+    from scipy.special import xlogy as _scipy_xlogy  # type: ignore[import-untyped]
+
+    def _safe_xlogy(
+        x: npt.NDArray[np.float64],
+        y: npt.NDArray[np.float64],
+    ) -> npt.NDArray[np.float64]:
+        """Compute ``x * ln(y)`` with the convention ``0 * ln(0) = 0``.
+
+        Uses :func:`scipy.special.xlogy` when available.
+
+        Parameters
+        ----------
+        x : ndarray
+            Frequencies (non-negative).
+        y : ndarray
+            Denominators (non-negative).
+
+        Returns
+        -------
+        ndarray
+            Element-wise ``x * ln(y)``, with 0 where *x* is zero.
+        """
+        return np.asarray(_scipy_xlogy(x, y), dtype=np.float64)
+
+except ImportError:  # pragma: no cover – scipy optional
+
+    def _safe_xlogy(
+        x: npt.NDArray[np.float64],
+        y: npt.NDArray[np.float64],
+    ) -> npt.NDArray[np.float64]:
+        """Compute ``x * ln(y)`` with the convention ``0 * ln(0) = 0``.
+
+        Pure-numpy fallback when scipy is not installed.
+        """
+        x = np.asarray(x, dtype=np.float64)
+        y = np.asarray(y, dtype=np.float64)
+        # Guard: negative y with non-zero x indicates a bug upstream
+        if np.any((y < 0) & (x != 0)):
+            msg = "negative y with non-zero x: frequencies must be non-negative"
+            raise ValueError(msg)
+        return np.where(x == 0, 0.0, x * np.log(np.where(y > 0, y, 1.0)))
+
+
+# ---------------------------------------------------------------------------
+# AIC(E; F) — two-way contingency table model
+# ---------------------------------------------------------------------------
+
+
+def compute_aic_twoway(
+    cross_freq: npt.NDArray[np.float64],
+    marginal_f: npt.NDArray[np.float64],
+) -> float:
+    r"""Compute AIC for the two-way table model.
+
+    .. math::
+
+        AIC(E; F) = -2 \sum_{i,j} n_{EF}(i,j) \ln \frac{n_{EF}(i,j)}{n_F(j)}
+                    + 2 (C_E - 1) C_F
+
+    Parameters
+    ----------
+    cross_freq : ndarray, shape (C_E, C_F)
+        Cross-frequency table.
+    marginal_f : ndarray, shape (C_F,)
+        Marginal frequencies of the explanatory variable.
+
+    Returns
+    -------
+    float
+        AIC value for the two-way model.
+    """
+    if cross_freq.sum() == 0:
+        msg = "cross_freq must contain at least one observation"
+        raise ValueError(msg)
+
+    c_e: int = cross_freq.shape[0]
+    c_f: int = cross_freq.shape[1]
+
+    if marginal_f.shape[0] != c_f:
+        msg = (
+            f"marginal_f length ({marginal_f.shape[0]}) must equal "
+            f"cross_freq columns ({c_f})"
+        )
+        raise ValueError(msg)
+
+    # n_EF(i,j) / n_F(j) — broadcast marginal_f across rows
+    ratio = np.where(marginal_f > 0, cross_freq / marginal_f, 0.0)
+    log_likelihood = float(np.sum(_safe_xlogy(cross_freq, ratio)))
+
+    penalty = 2.0 * (c_e - 1) * c_f
+    return float(-2.0 * log_likelihood + penalty)
+
+
+# ---------------------------------------------------------------------------
+# AIC(E; φ) — null (base) model
+# ---------------------------------------------------------------------------
+
+
+def compute_base_aic(
+    marginal_e: npt.NDArray[np.float64],
+    n: int,
+) -> float:
+    r"""Compute AIC for the null model (no explanatory variable).
+
+    .. math::
+
+        AIC(E; \phi) = -2 \sum_i n_E(i) \ln \frac{n_E(i)}{n} + 2 (C_E - 1)
+
+    Parameters
+    ----------
+    marginal_e : ndarray, shape (C_E,)
+        Marginal frequencies of the response variable.
+    n : int
+        Total number of observations.
+
+    Returns
+    -------
+    float
+        AIC value for the null model.
+
+    Raises
+    ------
+    ValueError
+        If *n* is not positive.
+    """
+    if n <= 0:
+        msg = "n must be positive; received an empty dataset"
+        raise ValueError(msg)
+
+    c_e = len(marginal_e)
+
+    ratio = marginal_e / n
+    log_likelihood: float = float(np.sum(_safe_xlogy(marginal_e, ratio)))
+
+    penalty = 2.0 * (c_e - 1)
+    return -2.0 * log_likelihood + penalty
+
+
+# ---------------------------------------------------------------------------
+# ΔAIC = AIC(E; F) − AIC(E; φ)
+# ---------------------------------------------------------------------------
+
+
+def compute_delta_aic(
+    cross_freq: npt.NDArray[np.float64],
+    marginal_e: npt.NDArray[np.float64],
+    marginal_f: npt.NDArray[np.float64],
+    n: int,
+) -> float:
+    r"""Compute the delta AIC between two-way and null models.
+
+    .. math::
+
+        \Delta AIC = AIC(E; F) - AIC(E; \phi)
+
+    A negative value indicates that the explanatory variable *F* is
+    informative about the response *E*.
+
+    Parameters
+    ----------
+    cross_freq : ndarray, shape (C_E, C_F)
+        Cross-frequency table.
+    marginal_e : ndarray, shape (C_E,)
+        Marginal frequencies of the response variable.
+    marginal_f : ndarray, shape (C_F,)
+        Marginal frequencies of the explanatory variable.
+    n : int
+        Total number of observations.
+
+    Returns
+    -------
+    float
+        ΔAIC value (negative = explanatory variable is useful).
+    """
+    aic_twoway = compute_aic_twoway(cross_freq, marginal_f)
+    aic_base = compute_base_aic(marginal_e, n)
+    return aic_twoway - aic_base

pycatdap/_contingency.py

@@ -0,0 +1,130 @@
+"""Contingency table construction utilities.
+
+Converts pandas DataFrames into numpy arrays suitable for AIC computation.
+Input DataFrames are never mutated.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from numpy.typing import NDArray
+
+
+def build_crosstab(
+    data: pd.DataFrame,
+    response: str,
+    explanatory: str,
+) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64], int]:
+    """Build a two-way frequency table from a DataFrame.
+
+    Rows with ``NaN`` in either column are dropped before tabulation.
+
+    Parameters
+    ----------
+    data : DataFrame
+        Input data (not modified).
+    response : str
+        Column name of the response variable (rows of cross-table).
+    explanatory : str
+        Column name of the explanatory variable (columns of cross-table).
+
+    Returns
+    -------
+    cross_freq : ndarray, shape (C_E, C_F)
+        Cross-frequency table.
+    marginal_e : ndarray, shape (C_E,)
+        Marginal frequencies of the response variable.
+    marginal_f : ndarray, shape (C_F,)
+        Marginal frequencies of the explanatory variable.
+    n : int
+        Total number of valid observations.
+
+    Raises
+    ------
+    KeyError
+        If *response* or *explanatory* is not in the DataFrame.
+    """
+    # Validate columns exist (raises KeyError if not)
+    _ = data[response], data[explanatory]
+
+    # Drop NaN in the two relevant columns only — do not modify input
+    subset = data[[response, explanatory]].dropna()
+
+    ct = pd.crosstab(subset[response], subset[explanatory])
+    cross_freq = ct.to_numpy(dtype=np.float64)
+    marginal_e = cross_freq.sum(axis=1).astype(np.float64)
+    marginal_f = cross_freq.sum(axis=0).astype(np.float64)
+    n = int(cross_freq.sum())
+
+    return cross_freq, marginal_e, marginal_f, n
+
+
+def build_multidim_crosstab(
+    data: pd.DataFrame,
+    response: str,
+    explanatory_set: list[str],
+) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64], int]:
+    """Build a cross-frequency table with a composite explanatory variable.
+
+    The explanatory variables are combined into a single composite variable
+    (tupled categories) before tabulation.
+
+    Parameters
+    ----------
+    data : DataFrame
+        Input data (not modified).
+    response : str
+        Column name of the response variable.
+    explanatory_set : list[str]
+        Column names of the explanatory variables to combine.
+
+    Returns
+    -------
+    cross_freq : ndarray, shape (C_E, C_F_combined)
+        Cross-frequency table.
+    marginal_e : ndarray, shape (C_E,)
+        Marginal frequencies of the response variable.
+    marginal_f : ndarray, shape (C_F_combined,)
+        Marginal frequencies of the composite explanatory variable.
+    n : int
+        Total number of valid observations.
+
+    Raises
+    ------
+    ValueError
+        If *explanatory_set* is empty.
+    KeyError
+        If *response* or any column in *explanatory_set* is not in the DataFrame.
+    """
+    if not explanatory_set:
+        msg = "explanatory_set must not be empty"
+        raise ValueError(msg)
+
+    # Validate all columns exist
+    _ = data[response]
+    for col in explanatory_set:
+        _ = data[col]
+
+    if len(explanatory_set) == 1:
+        return build_crosstab(data, response, explanatory_set[0])
+
+    cols = [response, *explanatory_set]
+    subset = data[cols].dropna()
+
+    # Use unit separator (U+001F) to avoid collisions with category labels
+    composite = subset[explanatory_set].astype(str).agg("\x1f".join, axis=1)
+    temp = pd.DataFrame(
+        {
+            "_response_": subset[response].to_numpy(),
+            "_composite_": composite.to_numpy(),
+        }
+    )
+
+    ct = pd.crosstab(temp["_response_"], temp["_composite_"])
+    cross_freq = ct.to_numpy(dtype=np.float64)
+    marginal_e = cross_freq.sum(axis=1).astype(np.float64)
+    marginal_f = cross_freq.sum(axis=0).astype(np.float64)
+    n = int(cross_freq.sum())
+
+    return cross_freq, marginal_e, marginal_f, n

pycatdap/_pooling.py

@@ -0,0 +1,349 @@
+"""Continuous variable categorization (pooling) via AIC minimization.
+
+Converts continuous variables into categorical ones by finding AIC-optimal
+bin boundaries.  Two methods are provided:
+
+* **Equal pooling** (``pool=0``): top-down, equal-interval bins merged greedily.
+* **Unequal pooling** (``pool=1``, default): bottom-up, fine bins merged until
+  no merge improves AIC.
+
+Input arrays are never mutated.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import numpy.typing as npt
+
+from pycatdap._aic import _safe_xlogy
+
+# ---------------------------------------------------------------------------
+# Result container
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PoolingResult:
+    """Result of AIC-optimal binning.
+
+    Attributes
+    ----------
+    codes : ndarray of int
+        Bin assignment for each observation (0-indexed).
+    boundaries : list[float]
+        Sorted internal bin boundary values.  ``len(boundaries) == n_bins - 1``
+        where *n_bins* is the number of distinct bins.
+    """
+
+    codes: npt.NDArray[np.intp]
+    boundaries: list[float]
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _auto_accuracy(values: npt.NDArray[np.float64]) -> float:
+    """Guess accuracy from the smallest non-zero gap between sorted values."""
+    sorted_vals = np.sort(np.unique(values))
+    if len(sorted_vals) <= 1:
+        return 1.0
+    diffs = np.diff(sorted_vals)
+    positive_diffs = diffs[diffs > 0]
+    if len(positive_diffs) == 0:
+        return 1.0
+    return float(np.min(positive_diffs))
+
+
+def _initial_bins(
+    values: npt.NDArray[np.float64],
+    accuracy: float,
+) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.float64]]:
+    """Divide the value range into fine-grained bins of width *accuracy*.
+
+    Returns
+    -------
+    bin_codes : ndarray of int
+        Bin index for each observation.
+    edges : ndarray of float
+        Bin edge values (length = n_bins + 1).
+    """
+    vmin, vmax = float(values.min()), float(values.max())
+
+    if vmax - vmin < accuracy:
+        # All values in a single bin
+        return np.zeros(len(values), dtype=np.intp), np.array([vmin, vmax + accuracy])
+
+    n_bins = max(1, int(np.ceil((vmax - vmin) / accuracy)))
+    edges: npt.NDArray[np.float64] = np.linspace(
+        vmin, vmax + accuracy * 0.01, n_bins + 1
+    ).astype(np.float64)
+    # np.digitize returns 1-based indices; subtract 1, clip to valid range
+    codes = np.clip(np.digitize(values, edges[1:-1]), 0, n_bins - 1).astype(np.intp)
+    return codes, edges
+
+
+def _build_bin_freq_table(
+    bin_codes: npt.NDArray[np.intp],
+    response_codes: npt.NDArray[np.intp],
+    n_bins: int,
+    n_resp_cats: int,
+) -> npt.NDArray[np.float64]:
+    """Build a (n_resp_cats, n_bins) frequency table from bin and response codes."""
+    freq = np.zeros((n_resp_cats, n_bins), dtype=np.float64)
+    np.add.at(freq, (response_codes, bin_codes), 1)
+    return freq
+
+
+def _bin_aic(freq: npt.NDArray[np.float64]) -> float:
+    """Compute AIC(E; F) for a frequency table (response x bins).
+
+    AIC = -2 * sum(n_ij * ln(n_ij / n_j)) + 2 * (C_E - 1) * C_F
+    """
+    c_e, c_f = freq.shape
+    marg_f = freq.sum(axis=0)
+    ratio = np.where(marg_f > 0, freq / marg_f, 0.0)
+    loglik = float(np.sum(_safe_xlogy(freq, ratio)))
+    penalty = 2.0 * (c_e - 1) * c_f
+    return float(-2.0 * loglik + penalty)
+
+
+def _merge_bins(
+    freq: npt.NDArray[np.float64],
+    i: int,
+) -> npt.NDArray[np.float64]:
+    """Return a new frequency table with bins *i* and *i+1* merged."""
+    new_freq: npt.NDArray[np.float64] = np.delete(freq, i + 1, axis=1).copy()
+    new_freq[:, i] = freq[:, i] + freq[:, i + 1]
+    return new_freq
+
+
+def _encode_response(
+    response: npt.NDArray[np.object_],
+) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.object_]]:
+    """Encode response labels to integer codes."""
+    uniq, codes = np.unique(response, return_inverse=True)
+    return codes.astype(np.intp), uniq
+
+
+def _codes_from_boundaries(
+    values: npt.NDArray[np.float64],
+    boundaries: list[float],
+) -> npt.NDArray[np.intp]:
+    """Assign bin codes from a sorted boundary list."""
+    if not boundaries:
+        return np.zeros(len(values), dtype=np.intp)
+    return np.digitize(values, boundaries).astype(np.intp)
+
+
+# ---------------------------------------------------------------------------
+# Equal pooling (pool=0, top-down)
+# ---------------------------------------------------------------------------
+
+
+def equal_pooling(
+    values: npt.NDArray[np.float64],
+    response: npt.NDArray[np.object_],
+    accuracy: float,
+) -> PoolingResult:
+    """Equal-interval pooling (top-down greedy merge).
+
+    Start with bins of width *accuracy*, then greedily merge adjacent
+    bins when merging reduces AIC.
+
+    Parameters
+    ----------
+    values : ndarray
+        Continuous variable values.
+    response : ndarray
+        Response variable labels (categorical).
+    accuracy : float
+        Minimum bin width (observation precision).
+
+    Returns
+    -------
+    PoolingResult
+    """
+    values = np.asarray(values, dtype=np.float64)
+    if len(values) == 0:
+        return PoolingResult(codes=np.array([], dtype=np.intp), boundaries=[])
+
+    resp_codes, _ = _encode_response(np.asarray(response))
+
+    bin_codes, edges = _initial_bins(values, accuracy)
+    n_bins = len(edges) - 1
+    n_resp_cats = int(resp_codes.max()) + 1
+
+    freq = _build_bin_freq_table(bin_codes, resp_codes, n_bins, n_resp_cats)
+
+    # Remove empty bins
+    nonempty = freq.sum(axis=0) > 0
+    if not np.all(nonempty):
+        freq = freq[:, nonempty]
+        edges = np.concatenate(
+            # Keep first edge, then non-empty right edges
+            [edges[:1], edges[1:][nonempty]]
+        )
+        # Pad last edge if needed
+        if len(edges) <= freq.shape[1]:
+            edges = np.append(edges, edges[-1] + accuracy)
+
+    # Greedy merge: merge the pair that most decreases AIC
+    current_aic = _bin_aic(freq)
+    changed = True
+    while changed and freq.shape[1] > 1:
+        changed = False
+        best_delta = 0.0
+        best_idx = -1
+        best_freq: npt.NDArray[np.float64] | None = None
+
+        for i in range(freq.shape[1] - 1):
+            merged = _merge_bins(freq, i)
+            new_aic = _bin_aic(merged)
+            delta = new_aic - current_aic
+            if delta < best_delta:
+                best_delta = delta
+                best_idx = i
+                best_freq = merged
+
+        if best_freq is not None:
+            freq = best_freq
+            # Remove the merged edge
+            edges = np.delete(edges, best_idx + 1)
+            current_aic += best_delta
+            changed = True
+
+    # Build boundaries (internal edges, excluding first and last)
+    boundaries = sorted(float(e) for e in edges[1:-1])
+    codes = _codes_from_boundaries(values, boundaries)
+    return PoolingResult(codes=codes, boundaries=boundaries)
+
+
+# ---------------------------------------------------------------------------
+# Unequal pooling (pool=1, bottom-up) — default
+# ---------------------------------------------------------------------------
+
+
+def unequal_pooling(
+    values: npt.NDArray[np.float64],
+    response: npt.NDArray[np.object_],
+    accuracy: float,
+) -> PoolingResult:
+    """Unequal-interval pooling (bottom-up greedy merge).
+
+    Start with fine bins of width *accuracy*, then iteratively merge the
+    adjacent pair that yields the largest AIC decrease.  Stop when no
+    merge improves AIC.
+
+    Parameters
+    ----------
+    values : ndarray
+        Continuous variable values.
+    response : ndarray
+        Response variable labels (categorical).
+    accuracy : float
+        Minimum bin width.
+
+    Returns
+    -------
+    PoolingResult
+    """
+    values = np.asarray(values, dtype=np.float64)
+    if len(values) == 0:
+        return PoolingResult(codes=np.array([], dtype=np.intp), boundaries=[])
+
+    resp_codes, _ = _encode_response(np.asarray(response))
+
+    bin_codes, edges = _initial_bins(values, accuracy)
+    n_bins = len(edges) - 1
+    n_resp_cats = int(resp_codes.max()) + 1
+
+    freq = _build_bin_freq_table(bin_codes, resp_codes, n_bins, n_resp_cats)
+
+    # Remove empty bins
+    nonempty = freq.sum(axis=0) > 0
+    if not np.all(nonempty):
+        freq = freq[:, nonempty]
+        edges = np.concatenate([edges[:1], edges[1:][nonempty]])
+        if len(edges) <= freq.shape[1]:
+            edges = np.append(edges, edges[-1] + accuracy)
+
+    # Bottom-up: iteratively merge best adjacent pair
+    current_aic = _bin_aic(freq)
+    while freq.shape[1] > 1:
+        best_delta = 0.0
+        best_idx = -1
+        best_freq: npt.NDArray[np.float64] | None = None
+
+        for i in range(freq.shape[1] - 1):
+            merged = _merge_bins(freq, i)
+            new_aic = _bin_aic(merged)
+            delta = new_aic - current_aic
+            if delta < best_delta:
+                best_delta = delta
+                best_idx = i
+                best_freq = merged
+
+        if best_freq is None:
+            break  # No merge improves AIC
+
+        freq = best_freq
+        edges = np.delete(edges, best_idx + 1)
+        current_aic += best_delta
+
+    boundaries = sorted(float(e) for e in edges[1:-1])
+    codes = _codes_from_boundaries(values, boundaries)
+    return PoolingResult(codes=codes, boundaries=boundaries)
+
+
+# ---------------------------------------------------------------------------
+# Public dispatch
+# ---------------------------------------------------------------------------
+
+
+def optimal_binning(
+    values: npt.NDArray[np.float64],
+    response: npt.NDArray[np.object_],
+    method: str = "bottom_up",
+    accuracy: float | None = None,
+) -> PoolingResult:
+    """Categorize a continuous variable via AIC-optimal binning.
+
+    Parameters
+    ----------
+    values : ndarray
+        Continuous variable values.
+    response : ndarray
+        Response variable labels (categorical).
+    method : {'bottom_up', 'top_down'}
+        ``'bottom_up'`` (default) uses unequal pooling;
+        ``'top_down'`` uses equal pooling.
+    accuracy : float or None
+        Minimum bin width.  If ``None``, auto-detected from data.
+
+    Returns
+    -------
+    PoolingResult
+        Bin codes and boundary values.
+
+    Raises
+    ------
+    ValueError
+        If *method* is not ``'bottom_up'`` or ``'top_down'``.
+    """
+    values = np.asarray(values, dtype=np.float64)
+    response = np.asarray(response)
+
+    if accuracy is None:
+        accuracy = _auto_accuracy(values)
+
+    if method == "bottom_up":
+        return unequal_pooling(values, response, accuracy)
+    if method == "top_down":
+        return equal_pooling(values, response, accuracy)
+
+    msg = f"method must be 'bottom_up' or 'top_down', got '{method}'"
+    raise ValueError(msg)