AutoCarver 7.3.3__tar.gz → 7.3.4__tar.gz

{autocarver-7.3.3 → autocarver-7.3.4}/AutoCarver/__init__.py

@@ -3,14 +3,17 @@
 from AutoCarver.carvers.binary_carver import BinaryCarver
 from AutoCarver.carvers.continuous_carver import ContinuousCarver
 from AutoCarver.carvers.multiclass_carver import MulticlassCarver
+from AutoCarver.carvers.ordinal_carver import OrdinalCarver
 from AutoCarver.features import Features
-from AutoCarver.selectors import ClassificationSelector, RegressionSelector
+from AutoCarver.selectors import ClassificationSelector, OrdinalSelector, RegressionSelector
 
 __all__ = [
     "BinaryCarver",
     "ContinuousCarver",
     "Features",
     "MulticlassCarver",
+    "OrdinalCarver",
     "ClassificationSelector",
+    "OrdinalSelector",
     "RegressionSelector",
 ]

{autocarver-7.3.3 → autocarver-7.3.4}/AutoCarver/carvers/__init__.py

@@ -3,5 +3,6 @@
 from AutoCarver.carvers.binary_carver import BinaryCarver
 from AutoCarver.carvers.continuous_carver import ContinuousCarver
 from AutoCarver.carvers.multiclass_carver import MulticlassCarver
+from AutoCarver.carvers.ordinal_carver import OrdinalCarver
 
-__all__ = ["BinaryCarver", "ContinuousCarver", "MulticlassCarver"]
+__all__ = ["BinaryCarver", "ContinuousCarver", "MulticlassCarver", "OrdinalCarver"]

autocarver-7.3.4/AutoCarver/carvers/ordinal_carver.py

@@ -0,0 +1,101 @@
+"""Tool to build optimized buckets out of Quantitative and Qualitative features
+for ordinal targets (ordered, integer-encoded modalities).
+"""
+
+import numpy as np
+import pandas as pd
+
+from AutoCarver.carvers.binary_carver import get_crosstab
+from AutoCarver.carvers.utils.base_carver import BaseCarver, Samples
+from AutoCarver.combinations import CombinationEvaluator, KendallTauCCombinations
+from AutoCarver.discretizers.utils.base_discretizer import ProcessingConfig
+from AutoCarver.features import Features
+from AutoCarver.utils import extend_docstring
+
+
+class OrdinalCarver(BaseCarver):
+    """Automatic carving of continuous, discrete, categorical and ordinal
+    features that maximizes association with an **ordinal** target.
+
+    The target must be **integer-encoded** with ordered levels (e.g. ``1..K``,
+    ``K > 2``); the level order is taken from the ascending integer values.
+
+    For ordinal targets, Kendall's :ref:`tau_c` is the default association
+    measure to sort combinations — it rewards groupings whose order matches the
+    target's while favouring robust, parsimonious cardinality. :ref:`tau_b` and
+    the original Somers' D (:ref:`somersd`) are also available via
+    ``combination_evaluator``.
+    """
+
+    __name__ = "OrdinalCarver"
+    is_y_ordinal = True
+
+    @extend_docstring(BaseCarver.__init__, exclude=["combination_evaluator"])
+    def __init__(
+        self,
+        features: Features,
+        min_freq: float,
+        max_n_mod: int,
+        *,
+        combination_evaluator: CombinationEvaluator | None = None,
+        config: ProcessingConfig | None = None,
+    ) -> None:
+        """
+        Parameters
+        ----------
+        combination_evaluator : CombinationEvaluator, optional
+            Pre-built evaluator instance measuring association between
+            :class:`Features` and an ordinal target. Defaults to
+            :class:`KendallTauCCombinations`.
+
+            Choose from: :class:`KendallTauCCombinations` (default),
+            :class:`KendallTauBCombinations`, :class:`SomersDCombinations`.
+        """
+        if combination_evaluator is None:
+            combination_evaluator = KendallTauCCombinations()
+        if not combination_evaluator.is_y_ordinal:
+            raise ValueError(
+                f"[{self.__name__}] {type(combination_evaluator).__name__} is not suited for ordinal targets. "
+                f"Choose from: KendallTauCCombinations, KendallTauBCombinations, SomersDCombinations."
+            )
+
+        super().__init__(
+            features=features,
+            min_freq=min_freq,
+            max_n_mod=max_n_mod,
+            combination_evaluator=combination_evaluator,
+            config=config,
+        )
+
+    def _prepare_samples(self, samples: Samples) -> Samples:
+        """Validates format and content of X and y."""
+        if samples.train.y is None:
+            raise ValueError(f"[{self.__name__}] y must be provided")
+        if not pd.api.types.is_numeric_dtype(samples.train.y):
+            raise ValueError(
+                f"[{self.__name__}] y must be an integer-encoded ordinal Series; "
+                "integer-encode your ordered target (e.g. 1..K) before carving."
+            )
+
+        y_values = np.unique(samples.train.y)
+        if len(y_values) <= 2:
+            raise ValueError(f"[{self.__name__}] provided y has <=2 levels, consider using BinaryCarver instead.")
+        if not np.all(np.equal(np.mod(y_values, 1), 0)):
+            raise ValueError(
+                f"[{self.__name__}] y must be integer-encoded ordered levels (e.g. 1..K); got non-integer values."
+            )
+
+        return super()._prepare_samples(samples)
+
+    def _aggregator(self, X: pd.DataFrame, y: pd.Series) -> dict[str, pd.Series | pd.DataFrame | None]:
+        """Computes ordered contingency tables (feature modalities × ordinal target
+        levels) for specified features, ordered according to the known labels."""
+        # checking for empty datasets (dev)
+        xtabs = {feature.version: None for feature in self.features}
+        if X is not None:
+            # crosstab for each feature — pd.crosstab emits one column per ordinal
+            # level and sorts them ascending (correct ordinal column order)
+            for feature in self.features:
+                xtabs.update({feature.version: get_crosstab(X, y, feature)})
+
+        return xtabs

{autocarver-7.3.3 → autocarver-7.3.4}/AutoCarver/carvers/utils/base_carver.py

@@ -90,7 +90,7 @@ def _drop_reason_from_history(history: pd.DataFrame) -> str:
     of historized non-viable combinations.
     """
     if history.empty:
-        return "No combination historized"
+        return "No combination possible"
 
     info_counts: dict[str, int] = {}
     for _, row in history.iterrows():
@@ -121,6 +121,7 @@ class BaseCarver(BaseDiscretizer, ABC):
     is_y_binary = False
     is_y_continuous = False
     is_y_multiclass = False
+    is_y_ordinal = False
 
     @extend_docstring(BaseDiscretizer.__init__, exclude=["min_freq", "config"])
     def __init__(

{autocarver-7.3.3 → autocarver-7.3.4}/AutoCarver/combinations/__init__.py

@@ -9,6 +9,12 @@ from AutoCarver.combinations.continuous.continuous_combination_evaluators import
     ContinuousCombinationEvaluator,
     KruskalCombinations,
 )
+from AutoCarver.combinations.ordinal.ordinal_combination_evaluators import (
+    KendallTauBCombinations,
+    KendallTauCCombinations,
+    OrdinalCombinationEvaluator,
+    SomersDCombinations,
+)
 from AutoCarver.combinations.utils.combination_evaluator import CombinationEvaluator
 
 __all__ = [
@@ -18,4 +24,8 @@ __all__ = [
     "CramervCombinations",
     "ContinuousCombinationEvaluator",
     "KruskalCombinations",
+    "OrdinalCombinationEvaluator",
+    "KendallTauCCombinations",
+    "KendallTauBCombinations",
+    "SomersDCombinations",
 ]

autocarver-7.3.4/AutoCarver/combinations/ordinal/__init__.py

@@ -0,0 +1,15 @@
+"""This module contains the ordinal combinations module."""
+
+from AutoCarver.combinations.ordinal.ordinal_combination_evaluators import (
+    KendallTauBCombinations,
+    KendallTauCCombinations,
+    OrdinalCombinationEvaluator,
+    SomersDCombinations,
+)
+
+__all__ = [
+    "OrdinalCombinationEvaluator",
+    "KendallTauCCombinations",
+    "KendallTauBCombinations",
+    "SomersDCombinations",
+]

autocarver-7.3.4/AutoCarver/combinations/ordinal/ordinal_combination_evaluators.py

@@ -0,0 +1,424 @@
+"""Module for ordinal combination evaluators."""
+
+import math
+from abc import ABC
+
+import numpy as np
+import pandas as pd
+
+from AutoCarver.combinations.ordinal.ordinal_target_rates import OrdinalTargetRate, TargetMeanLevel
+from AutoCarver.combinations.utils.combination_evaluator import AggregatedSample, CombinationEvaluator
+from AutoCarver.combinations.utils.combinations import combination_formatter, group_crosstab
+from AutoCarver.combinations.utils.target_rate import TargetRate
+from AutoCarver.features import GroupedList
+
+
+class OrdinalCombinationEvaluator(CombinationEvaluator[pd.DataFrame], ABC):
+    """Ordinal combination evaluator class.
+
+    The aggregation is an ordered contingency table
+    ``feature-groups (rows, in target-rate order) × ordinal-target-levels
+    (cols, ascending)`` — the binary crosstab generalised from 2 columns to as
+    many columns as the target has levels. Three rank-association statistics are
+    computed per combination; concrete subclasses pick which one ranks
+    combinations via :attr:`sort_by`:
+
+    * :ref:`tau_c` — Kendall/Stuart's tau-c (**default**, rectangular-table
+      correction; self-balances to a robust, meaningful number of modalities);
+    * :ref:`tau_b` — Kendall's tau-b (matches :func:`scipy.stats.kendalltau`);
+    * :ref:`somersd` — the original asymmetric Somers' D ``D(Y|X)`` (target given
+      feature).
+
+    The symmetric Kendall taus reward a split only when it is genuinely
+    discriminative and otherwise favour fewer, more robust modalities — like
+    :class:`TschuprowtCombinations` and the Kruskal effect sizes. Somers' D is
+    asymmetric and leans strongly toward the coarsest split.
+
+    Search uses the inherited enumerate-and-score path.
+    """
+
+    is_y_ordinal = True
+    _target_rate_classes: list[type[OrdinalTargetRate]] = [TargetMeanLevel]
+    # narrow inherited attribute: ordinal evaluators always carry an OrdinalTargetRate
+    # (enforced by _init_target_rate).
+    target_rate: OrdinalTargetRate
+    # narrow inherited `sort_by: str | None`: concrete subclasses always set a str.
+    sort_by: str
+
+    def _init_target_rate(self, target_rate: TargetRate[pd.DataFrame] | None) -> OrdinalTargetRate:
+        """Initializes target rate."""
+        if target_rate is None:
+            return TargetMeanLevel()
+        if not isinstance(target_rate, OrdinalTargetRate):
+            raise ValueError("target_rate must be an OrdinalTargetRate")
+        return target_rate
+
+    def _grouper(self, xagg: AggregatedSample, groupby: dict) -> pd.DataFrame:
+        """Groups a crosstab by ``groupby`` and sums column values by group.
+
+        Shares :func:`group_crosstab` with the binary path: leaders are ordered
+        by first appearance so grouping stays independent of label text.
+        """
+        return group_crosstab(xagg, groupby)
+
+    def _association_measure(
+        self,
+        xagg: AggregatedSample | pd.Series | pd.DataFrame,
+        n_obs: int | None = None,
+        tol: float = 1e-10,
+    ) -> dict[str, float | None]:
+        """Computes Kendall's tau-b, tau-c and Somers' D between feature and target.
+
+        Parameters
+        ----------
+        xagg : pd.DataFrame
+            Ordered contingency table (rows = feature groups, cols = ordinal
+            target levels). ``n_obs`` / ``tol`` are unused (the rank statistics
+            only depend on the table's cell counts).
+
+        Returns
+        -------
+        dict[str, float | None]
+            ``{"tau_b": ..., "tau_c": ..., "somersd": ...}``; any may be
+            ``None`` for a degenerate table.
+        """
+        _, _ = n_obs, tol  # unused
+        return _ordinal_associations(np.asarray(xagg.values, dtype=float))
+
+    def _get_best_combination_non_nan(self) -> dict | None:
+        """DP-based override with progressive top-K (mirrors the continuous path).
+
+        Replaces ``consecutive_combinations`` + enumerate-and-score with the
+        interval-DP in :func:`_top_k_partitions_ordinal_dp` over the additively
+        decomposable ``C−D`` numerator. Exact for tau-c (per-k constant
+        denominator); a progressively-grown top-K approximation for tau-b /
+        Somers' D, whose denominators depend on the group sizes.
+
+        The NaN path (:meth:`_get_best_combination_with_nan`) is **not** overridden:
+        it runs after this method has applied the best non-NaN grouping, so it
+        enumerates over the already-small grouped label set and the inherited
+        enumerate-and-score path is cheap there.
+        """
+        feature_labels = self.feature.labels
+        if feature_labels is None:
+            raise RuntimeError(f"[{self.__name__}] feature labels are not populated")
+        raw_labels = GroupedList(feature_labels[:])
+
+        if self.feature.has_nan:
+            if self.feature.dropna:
+                raw_labels.remove(self.feature.nan)
+            self.samples.dropna(self.feature.nan)
+
+        if self.samples.train.shape[0] <= 1:
+            return None
+
+        self._historize_raw_combination()
+
+        raw_index = list(raw_labels)
+        # samples.train.xagg is a crosstab DataFrame for ordinal evaluators
+        M, n_per_mod, col_sums = _dp_inputs_from_xagg(self.samples.train.xagg, raw_index)  # type: ignore
+
+        # Progressive top-K with doubling, mirroring the binary/continuous DPs.
+        top_k = self.dp_top_k_initial
+        walked = 0
+        viable: dict | None = None
+        while True:
+            associations = _top_k_partitions_ordinal_dp(
+                M,
+                n_per_mod,
+                col_sums,
+                max_n_mod=self.max_n_mod,
+                raw_index=raw_index,
+                sort_by=self.sort_by,
+                top_k=top_k,
+            )
+            viable, walked = self._walk_for_viable(associations, start=walked)
+            if viable is not None:
+                break
+            if walked < top_k:
+                break  # DP exhausted every consecutive partition; no viable exists
+            top_k *= 2
+
+        if viable is not None and viable.get("xagg") is None:
+            index_to_groupby = viable.get("index_to_groupby") or combination_formatter(viable["combination"])
+            viable["xagg"] = self._grouper(self.samples.train, index_to_groupby)
+
+        self._apply_best_combination(viable)
+        return viable
+
+
+class KendallTauCCombinations(OrdinalCombinationEvaluator):
+    """Kendall's tau-c based combination evaluation toolkit (ordinal default).
+
+    Stuart's tau-c applies a ``min(r, c)`` correction tailored to **rectangular**
+    tables — exactly our shape (few feature groups × many target levels) — so its
+    magnitude stays comparable across combinations with different group counts and
+    it leans toward fewer, robust modalities, only adding one when a split is
+    genuinely meaningful.
+    """
+
+    sort_by = "tau_c"
+
+
+class KendallTauBCombinations(OrdinalCombinationEvaluator):
+    """Kendall's tau-b based combination evaluation toolkit.
+
+    Bit-exact with :func:`scipy.stats.kendalltau` (the ``tau-b`` variant) on the
+    grouped contingency table — pinned by parity tests. Normalised by the
+    geometric mean of both margins' untied pairs; tends to retain more modalities
+    on smoothly monotone signals than :class:`KendallTauCCombinations`.
+    """
+
+    sort_by = "tau_b"
+
+
+class SomersDCombinations(OrdinalCombinationEvaluator):
+    """Somers' D based combination evaluation toolkit.
+
+    The original asymmetric Somers' D ``D(Y|X)`` — concordant minus discordant
+    pairs over pairs untied on the feature ``X`` — matching
+    ``scipy.stats.somersd(table).statistic``. Being asymmetric it leans strongly
+    toward the coarsest split (its maximum over groupings is typically two
+    modalities); offered for users who specifically want raw Somers' D rather
+    than the self-balancing Kendall taus.
+    """
+
+    sort_by = "somersd"
+
+
+def _concordant_minus_discordant(values: np.ndarray) -> float:
+    """Concordant minus discordant pairs ``C − D`` of an ordered table.
+
+    ``values`` is ``(r, c)`` with rows / columns already ascending.
+    """
+    # concordant partners of each cell: counts strictly down-right (k>i, l>j)
+    suffix = np.cumsum(np.cumsum(values[::-1, ::-1], axis=0), axis=1)[::-1, ::-1]
+    down_right = np.zeros_like(values)
+    down_right[:-1, :-1] = suffix[1:, 1:]
+
+    # discordant partners of each cell: counts strictly down-left (k>i, l<j)
+    suffix_rows_prefix_cols = np.cumsum(np.cumsum(values[::-1, :], axis=0)[::-1, :], axis=1)
+    down_left = np.zeros_like(values)
+    down_left[:-1, 1:] = suffix_rows_prefix_cols[1:, :-1]
+
+    return float((values * down_right).sum()) - float((values * down_left).sum())
+
+
+def _taus_from_counts(
+    cd: float, n: float, untied_on_feature: float, untied_on_target: float, m: int
+) -> dict[str, float | None]:
+    """Assembles tau-b, tau-c and Somers' D from pre-computed pair counts.
+
+    Shared by the closed form (:func:`_ordinal_associations`) and the DP path
+    so both produce bit-identical values.
+
+    * ``tau_b = (C − D) / sqrt((P0 − T_X)(P0 − T_Y))`` — matches
+      ``scipy.stats.kendalltau``;
+    * ``tau_c = 2·m·(C − D) / (n²·(m − 1))`` (Stuart's rectangular-table
+      correction);
+    * ``somersd = (C − D) / (P0 − T_X)`` — the original Somers' D ``D(Y|X)``.
+
+    Each measure is ``None`` when its denominator vanishes.
+    """
+    denominator_b = math.sqrt(untied_on_feature * untied_on_target)
+    return {
+        "tau_b": cd / denominator_b if denominator_b > 0 else None,
+        "tau_c": (2.0 * m * cd) / (n * n * (m - 1)) if m > 1 else None,
+        "somersd": cd / untied_on_feature if untied_on_feature > 0 else None,
+    }
+
+
+def _ordinal_associations(values: np.ndarray) -> dict[str, float | None]:
+    """Kendall's tau-b, tau-c and Somers' D ``D(Y|X)`` for an ordered table.
+
+    ``values`` is the ``(r, c)`` cell-count array with rows = ``X`` (feature
+    groups) and columns = ``Y`` (target levels), both already in ascending order.
+    Each measure is ``None`` when its denominator vanishes (degenerate table),
+    mirroring the continuous evaluator's ``None`` convention.
+    """
+    n = float(values.sum())
+    if n < 2:
+        return {"tau_b": None, "tau_c": None, "somersd": None}
+
+    cd = _concordant_minus_discordant(values)
+    row = values.sum(axis=1)
+    col = values.sum(axis=0)
+    all_pairs = n * (n - 1) / 2.0
+    untied_on_feature = all_pairs - float((row * (row - 1) / 2.0).sum())
+    untied_on_target = all_pairs - float((col * (col - 1) / 2.0).sum())
+    m = min(int((row > 0).sum()), int((col > 0).sum()))
+    return _taus_from_counts(cd, n, untied_on_feature, untied_on_target, m)
+
+
+# ---------------------------------------------------------------------------
+# Phase-B: progressive top-K interval DP over the additive C−D numerator
+# ---------------------------------------------------------------------------
+#
+# C−D of a consecutive grouping decomposes additively:
+#
+#     C−D(grouping) = TotalBetween − Σ_g WithinSegment(g)
+#
+# where TotalBetween (the C−D of the fully-split table) is constant and
+# WithinSegment is prefix-summable. So an interval DP that keeps, per number of
+# groups k, the partitions with the largest numerator (smallest Σ WithinSegment)
+# enumerates the best candidates without materialising every consecutive
+# partition. For tau-c the per-k denominator is constant, so numerator-optimal
+# == metric-optimal (the DP is exact). For tau-b / Somers' D the denominator
+# depends on the group sizes (T_X), so the kept top-K candidates are re-scored
+# with their true denominators and ranked — exact when top_k is exhaustive, a
+# top-K approximation otherwise.
+
+
+def _dp_inputs_from_xagg(raw_xagg: pd.DataFrame, raw_index: list) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Aligns a raw crosstab to ``raw_index`` for the DP.
+
+    Returns ``(M, n_per_mod, col_sums)`` where ``M`` is the ``(len(raw_index), c)``
+    per-modality column-count matrix (rows absent from ``raw_xagg`` are zero),
+    ``n_per_mod`` the row totals and ``col_sums`` the target marginal.
+    """
+    position = {label: i for i, label in enumerate(raw_xagg.index)}
+    values = np.asarray(raw_xagg.values, dtype=float)
+    M = np.zeros((len(raw_index), values.shape[1]))
+    for row, label in enumerate(raw_index):
+        source = position.get(label)
+        if source is not None:
+            M[row] = values[source]
+    return M, M.sum(axis=1), M.sum(axis=0)
+
+
+def _segment_within_costs(M: np.ndarray) -> np.ndarray:
+    """WithinSegment ``C−D`` for every consecutive row segment.
+
+    Returns ``seg`` of shape ``(n_mod, n_mod + 1)`` where ``seg[a, b]`` is the
+    concordant−discordant count among observations whose modalities both lie in
+    the consecutive block ``[a, b)`` — the within-segment pairs that grouping
+    removes from ``C−D``. Computed in ``O(n_mod² · c)`` via the bilinearity of
+    the between-modality concordance in the two rows' column vectors.
+    """
+    n_mod, c = M.shape
+    seg = np.zeros((n_mod, n_mod + 1))
+    for a in range(n_mod):
+        block = M[a].astype(float).copy()
+        within = 0.0
+        for b in range(a + 1, n_mod):
+            # between(block=[a,b) lower rows, row b higher): bilinear in column vectors
+            inclusive = np.cumsum(block)
+            strictly_lower = inclusive - block  # target mass below each column, within the block
+            strictly_higher = block.sum() - inclusive  # target mass above each column, within the block
+            within += float((M[b] * (strictly_lower - strictly_higher)).sum())
+            block = block + M[b]
+            seg[a, b + 1] = within
+    return seg
+
+
+def _build_partition_dp(
+    seg: np.ndarray, *, n_mod: int, cap: int, top_k: int
+) -> list[list[list[tuple[float, tuple[int, ...]]]]]:
+    """dp[g][j]: up to ``top_k`` ``(sum_seg, splits)`` with the SMALLEST sum_seg
+    (largest numerator), where ``splits = (0, s_1, ..., s_{g-1}, j)`` and ``g`` is
+    the number of groups.
+    """
+    dp: list[list[list[tuple[float, tuple[int, ...]]]]] = [[[] for _ in range(n_mod + 1)] for _ in range(cap + 1)]
+    for j in range(1, n_mod + 1):
+        dp[1][j] = [(float(seg[0, j]), (0, j))]
+    for g in range(2, cap + 1):
+        for j in range(g, n_mod + 1):
+            candidates: list[tuple[float, tuple[int, ...]]] = []
+            for i in range(g - 1, j):
+                seg_ij = float(seg[i, j])
+                for prev_sum, prev_splits in dp[g - 1][i]:
+                    candidates.append((prev_sum + seg_ij, prev_splits + (j,)))
+            if candidates:
+                candidates.sort(key=lambda x: x[0])  # smallest Σ within-segment first
+                dp[g][j] = candidates[:top_k]
+    return dp
+
+
+def _score_partition(
+    sum_seg: float,
+    splits: tuple[int, ...],
+    *,
+    total_between: float,
+    n_prefix: np.ndarray,
+    total_n: float,
+    all_pairs: float,
+    untied_on_target: float,
+    c_nonempty: int,
+) -> dict:
+    """Compute tau_b / tau_c / somersd for a single consecutive partition."""
+    cd = total_between - sum_seg
+    tied_on_feature = 0.0
+    non_empty_groups = 0
+    for g in range(len(splits) - 1):
+        size = n_prefix[splits[g + 1]] - n_prefix[splits[g]]
+        tied_on_feature += size * (size - 1) / 2.0
+        if size > 0:
+            non_empty_groups += 1
+    # m matches the closed form: min over *non-empty* grouped rows and target levels
+    m = min(non_empty_groups, c_nonempty)
+    return _taus_from_counts(cd, total_n, all_pairs - tied_on_feature, untied_on_target, m)
+
+
+def _top_k_partitions_ordinal_dp(
+    M: np.ndarray,
+    n_per_mod: np.ndarray,
+    col_sums: np.ndarray,
+    *,
+    max_n_mod: int,
+    raw_index: list,
+    sort_by: str,
+    top_k: int,
+) -> list[dict]:
+    """Top-K consecutive partitions ranked by ``sort_by`` (tau_b / tau_c / somersd).
+
+    ``M`` is the ``(n_mod, c)`` per-modality column-count matrix aligned to
+    ``raw_index``; ``col_sums`` is the target marginal (for ``T_Y``). Returns a
+    list of ``{combination, index_to_groupby, tau_b, tau_c, somersd}`` dicts
+    sorted by ``sort_by`` desc — same shape the streaming pipeline yields, so it
+    drops into the viability walk.
+    """
+    n_mod = len(raw_index)
+    cap = min(max_n_mod, n_mod)
+    total_n = float(n_per_mod.sum())
+    if cap < 2 or total_n < 2:
+        return []
+
+    all_pairs = total_n * (total_n - 1) / 2.0
+    untied_on_target = all_pairs - float((col_sums * (col_sums - 1) / 2.0).sum())
+    c_nonempty = int((col_sums > 0).sum())
+    total_between = _concordant_minus_discordant(M)
+    seg = _segment_within_costs(M)
+    n_prefix = np.concatenate([[0.0], np.cumsum(n_per_mod.astype(float))])
+
+    dp = _build_partition_dp(seg, n_mod=n_mod, cap=cap, top_k=top_k)
+
+    entries: list[tuple[float, dict, tuple[int, ...]]] = []
+    for k in range(2, cap + 1):
+        for sum_seg, splits in dp[k][n_mod]:
+            metrics = _score_partition(
+                sum_seg,
+                splits,
+                total_between=total_between,
+                n_prefix=n_prefix,
+                total_n=total_n,
+                all_pairs=all_pairs,
+                untied_on_target=untied_on_target,
+                c_nonempty=c_nonempty,
+            )
+            entries.append((_sort_key(metrics.get(sort_by)), metrics, splits))
+
+    entries.sort(key=lambda e: e[0], reverse=True)
+    entries = entries[:top_k]
+
+    out: list[dict] = []
+    for _, metrics, splits in entries:
+        combination = [list(raw_index[splits[g] : splits[g + 1]]) for g in range(len(splits) - 1)]
+        out.append({"combination": combination, "index_to_groupby": combination_formatter(combination), **metrics})
+    return out
+
+
+def _sort_key(value: float | None) -> float:
+    """Sort key putting ``None`` / ``NaN`` metrics last (descending sort)."""
+    if value is None or (isinstance(value, float) and math.isnan(value)):
+        return float("-inf")
+    return float(value)

autocarver-7.3.4/AutoCarver/combinations/ordinal/ordinal_target_rates.py

@@ -0,0 +1,73 @@
+"""set of target rates for ordinal targets"""
+
+from abc import ABC
+from typing import overload
+
+import numpy as np
+import pandas as pd
+
+from AutoCarver.combinations.utils import TargetRate
+
+
+class OrdinalTargetRate(TargetRate[pd.DataFrame], ABC):
+    """Ordinal target rate class.
+
+    Operates on an ordered contingency table ``feature-groups (rows) ×
+    ordinal-target-levels (cols)`` — the same crosstab shape the binary target
+    rates consume, only with one column per ordinal level instead of two.
+    """
+
+    __name__ = "ordinal_target_rate"
+
+    @overload
+    def compute(self, xagg: pd.Series | pd.DataFrame) -> pd.DataFrame: ...
+    @overload
+    def compute(self, xagg: None) -> None: ...
+    def compute(self, xagg: pd.Series | pd.DataFrame | None) -> pd.DataFrame | None:
+        """Computes the target rate.
+
+        Parameters
+        ----------
+        xagg : pd.DataFrame
+            A crosstab (feature groups × ordinal target levels).
+
+        Returns
+        -------
+        pd.DataFrame
+            Per-group target rate, ``frequency`` and ``count``.
+        """
+        # checking for an xtab
+        if xagg is not None:
+            # count + frequency per modality (count carried for CI-based viability tests)
+            count = xagg.sum(axis=1)
+            frequency = count / count.sum()
+
+            # computing target rate. `_compute` expects pd.DataFrame (Generic
+            # XAgg=DataFrame); compute()'s wide signature is for LSP matching,
+            # callers always pass a crosstab here.
+            return pd.DataFrame(
+                {self.__name__: self._compute(xagg), "frequency": frequency, "count": count}  # type: ignore
+            )
+        return None
+
+
+class TargetMeanLevel(OrdinalTargetRate):
+    """Mean ordinal level per modality.
+
+    The per-group rate is ``Σ_j level_j · n_gj / n_g+`` where ``level_j`` is read
+    from the (integer) crosstab columns. It is monotone in the target's order, so
+    it drives both the ``min_freq`` viability test and the train/dev
+    rank-preservation veto exactly like the binary/continuous target means.
+    """
+
+    __name__ = "target_mean_level"
+
+    def _compute(self, xagg: pd.DataFrame) -> pd.Series:
+        """Computes the mean ordinal level per modality."""
+        levels = np.asarray(xagg.columns, dtype=float)
+        counts = xagg.to_numpy(dtype=float)
+        totals = counts.sum(axis=1)
+        # empty modalities legitimately yield NaN: silence numpy's divide warnings
+        with np.errstate(invalid="ignore", divide="ignore"):
+            mean_level = (counts * levels).sum(axis=1) / totals
+        return pd.Series(mean_level, index=xagg.index)

{autocarver-7.3.3 → autocarver-7.3.4}/AutoCarver/combinations/utils/combination_evaluator.py

@@ -154,6 +154,7 @@ class CombinationEvaluator(ABC, Generic[XAgg]):
 
     is_y_binary = False
     is_y_continuous = False
+    is_y_ordinal = False
     sort_by = None
 
     # Initial top-K for the DP-based segmentation

{autocarver-7.3.3 → autocarver-7.3.4}/AutoCarver/combinations/utils/combinations.py

@@ -3,12 +3,17 @@ for any task.
 """
 
 from collections.abc import Generator
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
+import numpy as np
 import pandas as pd
 
 from AutoCarver.features import BaseFeature, GroupedList
 
+if TYPE_CHECKING:
+    # typing-only: avoids a runtime import cycle (combination_evaluator imports this module)
+    from AutoCarver.combinations.utils.combination_evaluator import AggregatedSample
+
 
 def combinations_at_index(
     start_index: int, elements: list[Any] | GroupedList, remaining_groups: int
@@ -161,6 +166,25 @@ def xagg_apply_combination(
     return combi_xagg
 
 
+def group_crosstab(xagg: "AggregatedSample | pd.DataFrame", groupby: dict) -> "pd.DataFrame":
+    """Sums a crosstab's rows into the groups defined by ``groupby``.
+
+    ``groupby`` maps each raw modality to its group leader. Group leaders are
+    ordered by first appearance (ordinal order), keeping the result independent
+    of the cosmetic label strings — the same contract as
+    :meth:`BinaryCombinationEvaluator._grouper`, shared here so crosstab-based
+    evaluators (binary, ordinal) don't each reimplement it.
+
+    Accepts anything exposing ``.index`` and ``.groupby`` (a ``pd.DataFrame`` or
+    an :class:`AggregatedSample`); always returns a ``pd.DataFrame``.
+    """
+    leaders = [groupby.get(index_value, index_value) for index_value in xagg.index]
+    # pass the key as an object ndarray (not a list): a list whose values happen
+    # to match column labels would be read by pandas as "group by these columns"
+    # rather than as a per-row grouping key.
+    return xagg.groupby(np.asarray(leaders, dtype=object), sort=False).sum()
+
+
 def combination_formatter(combination: list[list[str]]) -> dict[str, str]:
     """Attributes the first element of a group to all elements of a group"""
     return {modal: group[0] for group in combination for modal in group}

{autocarver-7.3.3 → autocarver-7.3.4}/AutoCarver/mcp/session.py

@@ -16,12 +16,20 @@ from pathlib import Path
 
 import pandas as pd
 
-from AutoCarver.carvers import BinaryCarver, ContinuousCarver, MulticlassCarver
+from AutoCarver.carvers import BinaryCarver, ContinuousCarver, MulticlassCarver, OrdinalCarver
 from AutoCarver.carvers.utils.base_carver import BaseCarver
 from AutoCarver.features import Features, specs_to_features_kwargs
 from AutoCarver.mcp import inspection
 
-_CARVERS = {"binary": BinaryCarver, "continuous": ContinuousCarver, "multiclass": MulticlassCarver}
+# "ordinal" is opt-in only: integer values alone can't distinguish an ordered
+# ordinal target from an unordered multiclass one, so ``auto`` never resolves to
+# it (see ``_resolve_task``) — the caller must request ``task="ordinal"``.
+_CARVERS = {
+    "binary": BinaryCarver,
+    "continuous": ContinuousCarver,
+    "multiclass": MulticlassCarver,
+    "ordinal": OrdinalCarver,
+}
 
 
 class CarverSession:
@@ -183,7 +191,7 @@ class CarverSession:
         if task in _CARVERS:
             return task
         if task != "auto":
-            raise ValueError(f"[session] unknown task {task!r}; use auto/binary/continuous/multiclass.")
+            raise ValueError(f"[session] unknown task {task!r}; use auto/binary/continuous/multiclass/ordinal.")
         uniques = y.dropna().unique()
         if len(uniques) == 2:
             return "binary"

{autocarver-7.3.3 → autocarver-7.3.4}/AutoCarver/selectors/__init__.py

@@ -29,6 +29,7 @@ from AutoCarver.selectors.measures import (
     TschuprowtMeasure,
     ZscoreOutlierMeasure,
 )
+from AutoCarver.selectors.ordinal_selector import OrdinalSelector
 from AutoCarver.selectors.regression_selector import RegressionSelector
 from AutoCarver.selectors.utils.base_selector import BaseSelector
 
@@ -37,6 +38,7 @@ __all__ = [
     "BaseSelector",
     "RegressionSelector",
     "ClassificationSelector",
+    "OrdinalSelector",
     # filters
     "BaseFilter",
     "QuantitativeFilter",

autocarver-7.3.4/AutoCarver/selectors/ordinal_selector.py

@@ -0,0 +1,23 @@
+"""Tools to select the best Quantitative and Qualitative features for an ordinal target."""
+
+from AutoCarver.selectors.measures import BaseMeasure, KruskalEtaSquaredMeasure, SpearmanMeasure
+from AutoCarver.selectors.utils.base_selector import BaseSelector
+
+
+class OrdinalSelector(BaseSelector):
+    """A pipeline of measures to perform a feature pre-selection that maximizes association
+    with an **ordinal** target.
+
+    The integer-encoded ordinal target is treated as a numeric rank, so the same
+    rank-based measures used for regression apply and stay order-aware w.r.t. the
+    target: Spearman's rho for quantitative features, Kruskal-η² (reversed) for
+    qualitative ones. No ordinal-specific selection statistic is required.
+    """
+
+    __name__ = "OrdinalSelector"
+    # the ordinal target is ranked numerically (like regression) for measure orientation
+    _target_is_qualitative = False
+
+    def _default_measures(self) -> list[BaseMeasure]:
+        """Spearman's rho ranks quantitative features, Kruskal-η² (reversed) ranks qualitative ones."""
+        return [SpearmanMeasure(), KruskalEtaSquaredMeasure()]

{autocarver-7.3.3 → autocarver-7.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AutoCarver
-Version: 7.3.3
+Version: 7.3.4
 Summary: Automatic Discretization of Features with Optimal Target Association
 Keywords: binning,discretization,feature-engineering,credit-scoring,woe,scorecards,tschuprow,tschuprow-t,cramer-v,information-value,iv,monotonic-binning,supervised-discretization,bucketization,risk-modeling,credit-risk,fraud-detection,categorical-encoding
 Author: Mario DEFRANCE

{autocarver-7.3.3 → autocarver-7.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "AutoCarver"
-version = "7.3.3"
+version = "7.3.4"
 description = "Automatic Discretization of Features with Optimal Target Association"
 authors = [{ name = "Mario DEFRANCE", email = "defrancemario@gmail.com" }]
 requires-python = ">=3.11, <3.15"