catstat 0.1.1__py3-none-any.whl

catstat/__init__.py

@@ -0,0 +1,15 @@
+"""catstat -- unified CPU/GPU statistical categorical encoding.
+
+Leakage-safe target encoding generalized to arbitrary statistics, with one sklearn-compatible API.
+Runs on CPU (pandas/numpy) today; the GPU path (cuDF/CuPy) is parity-validated but auto-selection
+stays on CPU until it is faster (see docs/roadmap.md and docs/known_issues.md, KI-020).
+"""
+
+from __future__ import annotations
+
+from .count_encoder import CountEncoder
+from .frequency_encoder import FrequencyEncoder
+from .target_encoder import TargetEncoder
+
+__all__ = ["TargetEncoder", "CountEncoder", "FrequencyEncoder", "__version__"]
+__version__ = "0.1.1"

catstat/_aggregations.py

@@ -0,0 +1,57 @@
+"""Non-mean target statistics: var / std / median / min / max.
+
+These have **no principled smoothing** (the smoothing honesty rule): order statistics never blend,
+and var/std default to no shrinkage. Each falls back to the **global** statistic for unseen
+categories and for categories below ``min_samples_category`` (or where the statistic is undefined,
+e.g. the sample variance of a singleton). Continuous targets only -- the encoders reject these for
+classification.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from .backends import _cpu
+
+
+def global_stat(y, stat: str) -> float:
+    y = np.asarray(y, dtype=float)
+    if stat == "var":
+        return float(np.var(y, ddof=1)) if len(y) > 1 else 0.0
+    if stat == "std":
+        return float(np.std(y, ddof=1)) if len(y) > 1 else 0.0
+    if stat == "median":
+        return float(np.median(y))
+    if stat == "min":
+        return float(np.min(y))
+    if stat == "max":
+        return float(np.max(y))
+    if stat == "skew":
+        s = pd.Series(y).skew()  # NaN for n < 3
+        return float(s) if pd.notna(s) else 0.0
+    raise ValueError(f"Unknown non-mean stat {stat!r}.")
+
+
+def fit_custom_encoding(keys, y, fn, min_samples: int) -> tuple[pd.Series, float]:
+    """Return ``(encoding_by_category, global_fallback)`` for a custom aggregation (CPU only)."""
+    per_cat = _cpu.category_agg_custom(keys, y, fn)
+    counts = pd.Series(keys).value_counts().reindex(per_cat.index)
+    gv = float(fn(np.asarray(y, dtype=float)))
+    fallback_mask = per_cat.isna() | (counts < max(int(min_samples), 1))
+    return per_cat.where(~fallback_mask, gv).astype(float), gv
+
+
+def fit_stat_encoding(
+    keys, y, stat: str, min_samples: int, backend=None
+) -> tuple[pd.Series, float]:
+    """Return ``(encoding_by_category, global_fallback)`` for a dispersion/order statistic."""
+    if backend is None:
+        backend = _cpu
+    per_cat = backend.category_agg(keys, y, stat)  # Series; NaN where undefined (e.g. var of n=1)
+    counts = pd.Series(keys).value_counts().reindex(per_cat.index)
+    gv = global_stat(y, stat)
+    # fall back to the global statistic for undefined or under-supported categories
+    fallback_mask = per_cat.isna() | (counts < max(int(min_samples), 1))
+    enc = per_cat.where(~fallback_mask, gv).astype(float)
+    return enc, gv

catstat/_base.py

@@ -0,0 +1,387 @@
+"""``_BaseStatEncoder`` -- the shared fit/transform/fit_transform skeleton.
+
+All statistics/leakage logic lives here and in the small helper modules; only ``backends/``
+knows pandas vs cuDF. Subclasses define the sklearn ``__init__`` params and two hooks:
+``_is_supervised`` and ``_resolve_stat_specs``.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from sklearn.base import BaseEstimator, TransformerMixin
+from sklearn.utils import check_random_state
+from sklearn.utils.validation import check_is_fitted
+
+from ._aggregations import fit_custom_encoding, fit_stat_encoding
+from ._cross_fit import loo_encode, make_folds, ordered_encode, resolve_cv
+from ._feature_names import build_columns
+from ._smoothing import fit_mean_encoding
+from ._validation import (
+    check_handle,
+    infer_target_type,
+    normalize_keys,
+    prepare_X,
+    select_cols,
+)
+from .backends import _cpu
+from .backends._dispatch import backend_module, select_backend
+
+_VALID_OUTPUT = ("auto", "numpy", "pandas", "polars")
+_DEFERRED_OUTPUT = ("cudf", "cupy")
+
+
+class _BaseStatEncoder(TransformerMixin, BaseEstimator):
+    # ---- hooks the subclasses must implement -------------------------------------------------
+    def _is_supervised(self) -> bool:
+        raise NotImplementedError
+
+    def _resolve_stat_specs(self):
+        raise NotImplementedError
+
+    # ---- scikit-learn estimator tags ---------------------------------------------------------
+    # catstat encoders are categorical encoders: they accept string/categorical columns and learn
+    # NaN as its own level when handle_missing="value"; supervised encoders additionally require y.
+    # Both tag APIs are provided -- __sklearn_tags__ for scikit-learn >= 1.6, and _more_tags for
+    # < 1.6 (newer versions ignore it; older ones ignore __sklearn_tags__).
+    def __sklearn_tags__(self):
+        tags = super().__sklearn_tags__()
+        tags.target_tags.required = self._is_supervised()
+        tags.input_tags.categorical = True
+        tags.input_tags.string = True
+        tags.input_tags.allow_nan = True
+        return tags
+
+    def _more_tags(self):
+        return {
+            "requires_y": self._is_supervised(),
+            "X_types": ["categorical", "string", "2darray"],
+            "allow_nan": True,
+        }
+
+    # ---- key helper --------------------------------------------------------------------------
+    @staticmethod
+    def _key(meta):
+        return (meta.feature, meta.stat, meta.class_label)
+
+    # ---- fit ---------------------------------------------------------------------------------
+    def fit(self, X, y=None):
+        check_handle("handle_unknown", self.handle_unknown)
+        check_handle("handle_missing", self.handle_missing)
+        mode = getattr(self, "multi_feature_mode", "independent")
+        if mode not in ("independent", "combination"):
+            raise ValueError(
+                f"multi_feature_mode={mode!r} must be 'independent' or 'combination'."
+            )
+        if self.output in _DEFERRED_OUTPUT:
+            raise NotImplementedError(f"output={self.output!r} is not supported in M0 (CPU).")
+        if self.output not in _VALID_OUTPUT:
+            raise ValueError(f"output={self.output!r} must be one of {_VALID_OUTPUT}.")
+
+        Xdf, was_df, all_cols = prepare_X(X)
+        self.n_features_in_ = Xdf.shape[1]
+        if was_df:
+            self.feature_names_in_ = np.asarray(all_cols, dtype=object)
+        self._cat_cols = select_cols(Xdf, self.cols)
+        # Encoding units: independent -> one per column; combination -> one joint unit.
+        if mode == "combination" and len(self._cat_cols) > 1:
+            joint = "+".join(str(c) for c in self._cat_cols)
+            self._units = [(joint, list(self._cat_cols))]
+        else:
+            self._units = [(c, [c]) for c in self._cat_cols]
+        self._unit_cols = dict(self._units)
+        self._specs = self._resolve_stat_specs()
+        self.stats_ = [s.name for s in self._specs]
+
+        supervised = self._is_supervised()
+        if supervised:
+            if y is None:
+                raise ValueError(f"{type(self).__name__} requires y to be supplied to fit().")
+            y_arr = np.asarray(y)
+            if len(y_arr) != Xdf.shape[0]:
+                raise ValueError("X and y have inconsistent lengths.")
+            self.target_type_ = infer_target_type(y_arr, self.target_type)
+            self.classes_ = (
+                np.unique(y_arr) if self.target_type_ in ("binary", "multiclass") else None
+            )
+        else:
+            y_arr = None
+            self.target_type_ = None
+            self.classes_ = None
+
+        for spec in self._specs:
+            if spec.continuous_only and self.target_type_ != "continuous":
+                raise ValueError(
+                    f"stat={spec.name!r} requires a continuous target; got "
+                    f"target_type={self.target_type_!r}. Dispersion/order statistics on "
+                    "classification targets are not supported."
+                )
+
+        scheme = getattr(self, "scheme", "kfold")
+        if scheme not in ("kfold", "loo", "ordered"):
+            raise ValueError(f"scheme={scheme!r} must be 'kfold', 'loo', or 'ordered'.")
+        if scheme != "kfold":
+            bad = [s.name for s in self._specs if s.target_dependent and s.name != "mean"]
+            if bad:
+                raise ValueError(
+                    f"scheme={scheme!r} cross-fits the mean only (count/frequency are allowed "
+                    f"too); got target-dependent stats {bad}. Use scheme='kfold' for those."
+                )
+
+        self._columns_meta = build_columns(
+            [name for name, _ in self._units], self._specs, self.target_type_, self.classes_
+        )
+        self.feature_names_out_ = np.asarray([m.name for m in self._columns_meta], dtype=object)
+
+        all_gpu = all(s.gpu_supported for s in self._specs)
+        self._backend_mod, self.backend_ = select_backend(
+            self.backend, Xdf.shape[0], len(self._cat_cols), all_gpu
+        )
+        # GPU can't run tuple keys (combination) or CPU-only stats (skew/custom) -> host only.
+        host_only = (not all_gpu) or any(len(cols) > 1 for _, cols in self._units)
+        if self.backend_ == "gpu" and host_only:
+            self._backend_mod, self.backend_ = _cpu, _cpu.NAME
+
+        self._fit_tables = self._fit_all(Xdf, y_arr)
+
+        # public fitted attributes derived from the full-data tables
+        self.categories_ = {}
+        self.global_stats_ = {}
+        for meta in self._columns_meta:
+            enc, fb = self._fit_tables[self._key(meta)]
+            self.global_stats_[meta.name] = fb
+            self.categories_.setdefault(meta.feature, np.asarray(list(enc.index), dtype=object))
+        self._set_target_mean()
+        return self
+
+    def _set_target_mean(self):
+        if not self._is_supervised() or "mean" not in self.stats_:
+            return
+        f0 = self._units[0][0]
+        if self.target_type_ == "multiclass":
+            self.target_mean_ = np.asarray(
+                [self._fit_tables[(f0, "mean", c)][1] for c in self.classes_], dtype=float
+            )
+        else:
+            self.target_mean_ = float(self._fit_tables[(f0, "mean", None)][1])
+
+    # ---- per-statistic fitting ---------------------------------------------------------------
+    def _fit_all(self, Xdf, y_arr):
+        """Return the full encoding tables: ``{(feature, stat, class): (Series, fallback)}``."""
+        tables = {}
+        hm = self.handle_missing
+        for feat, cols in self._units:
+            keys_full, missing_mask = self._unit_keys(Xdf, cols)
+            if hm == "error" and missing_mask.any():
+                raise ValueError(
+                    f"Missing values in unit {feat!r} with handle_missing='error'."
+                )
+            sel = np.ones(len(keys_full), dtype=bool) if hm == "value" else ~missing_mask
+            keys = keys_full[sel]
+            n_total = int(sel.sum())
+            for spec in self._specs:
+                if spec.name == "count":
+                    tables[(feat, "count", None)] = self._fit_count(keys, False, n_total)
+                elif spec.name == "frequency":
+                    tables[(feat, "frequency", None)] = self._fit_count(keys, True, n_total)
+                elif spec.name == "mean":
+                    y_sel = y_arr[sel]
+                    bk = self._backend_mod
+                    if self.target_type_ == "continuous":
+                        tables[(feat, "mean", None)] = fit_mean_encoding(
+                            keys, y_sel.astype(float), self.smooth, bk
+                        )
+                    elif self.target_type_ == "binary":
+                        yb = (y_sel == self.classes_[1]).astype(float)
+                        tables[(feat, "mean", None)] = fit_mean_encoding(keys, yb, self.smooth, bk)
+                    else:  # multiclass: one-vs-rest per global class
+                        for c in self.classes_:
+                            yc = (y_sel == c).astype(float)
+                            tables[(feat, "mean", c)] = fit_mean_encoding(keys, yc, self.smooth, bk)
+                else:  # var/std/median/min/max/skew or custom (continuous-only, target-dependent)
+                    min_samples = getattr(self, "min_samples_category", 1)
+                    y_sel_f = y_arr[sel].astype(float)
+                    if spec.func is not None:
+                        tables[(feat, spec.name, None)] = fit_custom_encoding(
+                            keys, y_sel_f, spec.func, min_samples
+                        )
+                    else:
+                        tables[(feat, spec.name, None)] = fit_stat_encoding(
+                            keys, y_sel_f, spec.name, min_samples, self._backend_mod
+                        )
+        return tables
+
+    @staticmethod
+    def _fit_count(keys, normalize, n_total):
+        vc = pd.Series(keys).value_counts().astype(float)
+        if normalize:
+            vc = vc / float(max(n_total, 1))
+        return vc, 0.0
+
+    def _unit_keys(self, Xdf, cols):
+        """Return ``(keys, missing_mask)`` for an encoding unit.
+
+        A single-column unit uses the column's normalized keys directly. A combination unit uses
+        the tuple of its components' keys as one joint category; the row counts as missing if any
+        component is missing.
+        """
+        if len(cols) == 1:
+            return normalize_keys(Xdf[cols[0]].to_numpy())
+        comp_keys = []
+        missing = np.zeros(Xdf.shape[0], dtype=bool)
+        for c in cols:
+            k, m = normalize_keys(Xdf[c].to_numpy())
+            comp_keys.append(k)
+            missing = missing | m
+        joint = np.empty(Xdf.shape[0], dtype=object)
+        for i in range(Xdf.shape[0]):
+            joint[i] = tuple(ck[i] for ck in comp_keys)
+        return joint, missing
+
+    # ---- transform ---------------------------------------------------------------------------
+    def _transform_array(self, Xdf, tables) -> np.ndarray:
+        n = Xdf.shape[0]
+        out = np.full((n, len(self._columns_meta)), np.nan, dtype=float)
+        hm, hu = self.handle_missing, self.handle_unknown
+        cache: dict = {}
+        for j, meta in enumerate(self._columns_meta):
+            feat = meta.feature
+            if feat not in cache:
+                keys, missing_mask = self._unit_keys(Xdf, self._unit_cols[feat])
+                if hm == "error" and missing_mask.any():
+                    raise ValueError(
+                        f"Missing values in unit {feat!r} with handle_missing='error'."
+                    )
+                cache[feat] = (keys, missing_mask)
+            keys, missing_mask = cache[feat]
+
+            enc_series, fallback = tables[self._key(meta)]
+            mapped = pd.Series(keys).map(enc_series).to_numpy(dtype=float)
+            col = mapped.copy()
+            notfound = np.isnan(mapped)
+
+            if hm == "return_nan":
+                col[missing_mask] = np.nan
+                self._apply_unknown(col, notfound & ~missing_mask, fallback, hu, feat)
+            elif hm == "value":
+                # rows not found are either unseen real categories OR an unseen missing level
+                self._apply_unknown(col, notfound, fallback, hu, feat)
+            else:  # "error" already raised above if any missing present
+                self._apply_unknown(col, notfound & ~missing_mask, fallback, hu, feat)
+            out[:, j] = col
+        return out
+
+    @staticmethod
+    def _apply_unknown(col, mask, fallback, hu, feat):
+        if not mask.any():
+            return col
+        if hu == "error":
+            raise ValueError(
+                f"Found unknown categories in column {feat!r} with handle_unknown='error'."
+            )
+        if hu == "value":
+            col[mask] = fallback
+        # "return_nan": leave the NaN in place
+        return col
+
+    # ---- pickle support ----------------------------------------------------------------------
+    # A fitted estimator caches its backend *module* in `_backend_mod`; modules aren't picklable,
+    # so drop it on pickle and re-resolve it from the recorded backend name (`backend_`) on load.
+    def __getstate__(self):
+        state = dict(super().__getstate__())
+        state.pop("_backend_mod", None)
+        return state
+
+    def __setstate__(self, state):
+        super().__setstate__(state)
+        if "backend_" in state:
+            self._backend_mod = backend_module(state["backend_"])
+
+    def transform(self, X):
+        check_is_fitted(self, "_fit_tables")
+        Xdf, was_df, _ = prepare_X(X)
+        arr = self._transform_array(Xdf, self._fit_tables)
+        return self._wrap_output(arr, was_df, Xdf)
+
+    def fit_transform(self, X, y=None, **fit_params):
+        self.fit(X, y)
+        Xdf, was_df, _ = prepare_X(X)
+        full = self._transform_array(Xdf, self._fit_tables)
+
+        if self._is_supervised() and any(m.target_dependent for m in self._columns_meta):
+            y_arr = np.asarray(y)
+            scheme = getattr(self, "scheme", "kfold")
+            if scheme == "kfold":
+                oof = self._kfold_oof(Xdf, y_arr, full.shape)
+            else:
+                oof = self._loo_ordered_oof(Xdf, y_arr, scheme, full.shape)
+            for j, meta in enumerate(self._columns_meta):
+                if meta.target_dependent:
+                    full[:, j] = oof[:, j]
+        return self._wrap_output(full, was_df, Xdf)
+
+    def _kfold_oof(self, Xdf, y_arr, shape):
+        splitter = resolve_cv(self.cv, self.target_type_, self.shuffle, self.random_state)
+        folds = make_folds(Xdf.shape[0], y_arr, splitter)
+        oof = np.full(shape, np.nan)
+        for tr, te in folds:
+            tbl = self._fit_all(Xdf.iloc[tr], y_arr[tr])
+            oof[te, :] = self._transform_array(Xdf.iloc[te], tbl)
+        return oof
+
+    def _mean_y_vector(self, y_arr, meta):
+        if self.target_type_ == "continuous":
+            return y_arr.astype(float)
+        if self.target_type_ == "binary":
+            return (y_arr == self.classes_[1]).astype(float)
+        return (y_arr == meta.class_label).astype(float)  # multiclass one-vs-rest
+
+    def _loo_ordered_oof(self, Xdf, y_arr, scheme, shape):
+        """Leave-one-out / ordered encodings for the mean columns (validated: mean-only)."""
+        oof = np.full(shape, np.nan)
+        m = 0.0 if isinstance(self.smooth, str) else float(self.smooth)  # loo pseudo-count
+        # ordered prior weight a (CatBoost) must be > 0; default 1 for "auto"/non-positive smooth.
+        smooth_pos = (not isinstance(self.smooth, str)) and float(self.smooth) > 0
+        a = float(self.smooth) if smooth_pos else 1.0
+        perm = (
+            check_random_state(self.random_state).permutation(len(y_arr))
+            if scheme == "ordered"
+            else None
+        )
+        for j, meta in enumerate(self._columns_meta):
+            if not (meta.target_dependent and meta.stat == "mean"):
+                continue
+            keys, missing_mask = self._unit_keys(Xdf, self._unit_cols[meta.feature])
+            yv = self._mean_y_vector(y_arr, meta)
+            prior = float(yv.mean())
+            if scheme == "loo":
+                vals = loo_encode(keys, yv, m, prior)
+            else:
+                vals = ordered_encode(keys, yv, a, prior, perm)
+            if self.handle_missing == "return_nan":
+                vals = vals.copy()
+                vals[missing_mask] = np.nan
+            oof[:, j] = vals
+        return oof
+
+    # ---- output container --------------------------------------------------------------------
+    def _wrap_output(self, arr, was_df, Xdf):
+        if self.output == "numpy":
+            return arr
+        if self.output == "pandas":
+            idx = Xdf.index if was_df else None
+            return pd.DataFrame(arr, columns=self.feature_names_out_, index=idx)
+        if self.output == "polars":
+            try:
+                import polars as pl
+            except ImportError as e:  # pragma: no cover - exercised only without polars
+                raise ImportError("output='polars' requires polars (pip install polars).") from e
+            return pl.from_numpy(arr, schema=list(self.feature_names_out_))
+        # "auto": mirror the input container
+        if was_df:
+            return pd.DataFrame(arr, columns=self.feature_names_out_, index=Xdf.index)
+        return arr
+
+    def get_feature_names_out(self, input_features=None):
+        check_is_fitted(self, "_fit_tables")
+        return np.asarray(self.feature_names_out_, dtype=object)

catstat/_cross_fit.py

@@ -0,0 +1,83 @@
+"""Cross-fitting: deterministic fold assignment for leakage-safe ``fit_transform``.
+
+``catstat`` owns fold assignment so CPU and (future) GPU produce identical out-of-fold encodings.
+``random_state`` flows only through the resolved splitter; the global numpy RNG is never touched.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from sklearn.model_selection import KFold, StratifiedKFold
+
+
+class _PrecomputedSplitter:
+    """Wrap a user-provided iterable of ``(train_idx, test_idx)`` tuples."""
+
+    def __init__(self, splits):
+        self._splits = [(np.asarray(tr), np.asarray(te)) for tr, te in splits]
+
+    def split(self, X, y=None, groups=None):
+        return iter(self._splits)
+
+
+def resolve_cv(cv, target_type: str, shuffle: bool, random_state):
+    """Return a splitter object for the given ``cv`` argument.
+
+    int -> KFold (continuous) or StratifiedKFold (binary/multiclass). A splitter object is
+    returned as-is. An iterable of index pairs is wrapped.
+    """
+    if hasattr(cv, "split"):
+        return cv
+    if isinstance(cv, (int, np.integer)):
+        rs = random_state if shuffle else None
+        if target_type == "continuous":
+            return KFold(n_splits=int(cv), shuffle=shuffle, random_state=rs)
+        return StratifiedKFold(n_splits=int(cv), shuffle=shuffle, random_state=rs)
+    # assume an iterable of (train, test) index arrays
+    return _PrecomputedSplitter(cv)
+
+
+def make_folds(n_rows: int, y, splitter) -> list[tuple[np.ndarray, np.ndarray]]:
+    """Materialize the ``(train_idx, test_idx)`` folds.
+
+    A dummy feature matrix is passed for shape; stratified splitters use ``y``.
+    """
+    dummy_X = np.zeros((n_rows, 1))
+    return list(splitter.split(dummy_X, y))
+
+
+def loo_encode(keys, y, m: float, prior: float) -> np.ndarray:
+    """Leave-one-out mean encoding (deterministic, leakage-safe for the training set).
+
+    Each row is encoded by its category mean computed from **every other row**:
+    ``(cat_sum - y_i + m*prior) / (cat_count - 1 + m)``. With ``m=0`` this is the classic LOO mean;
+    singletons (empty denominator) fall back to the global ``prior``.
+    """
+    yv = np.asarray(y, dtype=float)
+    grp = pd.DataFrame({"k": pd.Series(keys), "y": yv}).groupby("k", sort=False)["y"]
+    cat_sum = grp.transform("sum").to_numpy()
+    cat_cnt = grp.transform("count").to_numpy()
+    num = cat_sum - yv + m * prior
+    den = cat_cnt - 1.0 + m
+    den_safe = np.where(den > 0, den, 1.0)  # avoid 0/0 warning; result is overwritten by prior
+    return np.where(den > 0, num / den_safe, prior)
+
+
+def ordered_encode(keys, y, a: float, prior: float, perm: np.ndarray) -> np.ndarray:
+    """CatBoost-style ordered target statistics.
+
+    Walk the rows in a random permutation; each row is encoded from only the **prior** rows of its
+    category in that order: ``(prior_sum + a*prior) / (prior_count + a)`` (first occurrence ->
+    prior).
+    """
+    yv = np.asarray(y, dtype=float)
+    ks = np.asarray(keys, dtype=object)[perm]
+    ys = yv[perm]
+    g = pd.Series(ys).groupby(ks, sort=False)
+    prior_sum = g.cumsum().to_numpy() - ys  # cumsum includes current -> subtract it
+    prior_cnt = g.cumcount().to_numpy()  # 0-based position == count of earlier rows
+    enc_perm = (prior_sum + a * prior) / (prior_cnt + a)
+    out = np.empty(len(yv), dtype=float)
+    out[perm] = enc_perm
+    return out

catstat/_feature_names.py

@@ -0,0 +1,49 @@
+"""Output column metadata and feature-name construction.
+
+Column order is feature-major, then stat order, then (for class-expanded multiclass stats) class
+order. The same metadata list drives both ``transform`` assembly and ``get_feature_names_out`` so
+they can never disagree.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ._stats import StatSpec
+
+
+@dataclass(frozen=True)
+class ColumnMeta:
+    feature: object
+    stat: str
+    class_label: object  # None unless a class-expanded multiclass column
+    target_dependent: bool
+    name: str
+
+
+def build_columns(cat_cols, specs: list[StatSpec], target_type, classes) -> list[ColumnMeta]:
+    cols: list[ColumnMeta] = []
+    for feat in cat_cols:
+        for spec in specs:
+            if spec.class_expanded and target_type == "multiclass":
+                for c in classes:
+                    cols.append(
+                        ColumnMeta(
+                            feature=feat,
+                            stat=spec.name,
+                            class_label=c,
+                            target_dependent=spec.target_dependent,
+                            name=f"{feat}__{spec.name_infix}__class_{c}",
+                        )
+                    )
+            else:
+                cols.append(
+                    ColumnMeta(
+                        feature=feat,
+                        stat=spec.name,
+                        class_label=None,
+                        target_dependent=spec.target_dependent,
+                        name=f"{feat}__{spec.name_infix}",
+                    )
+                )
+    return cols

catstat/_smoothing.py

@@ -0,0 +1,56 @@
+"""Smoothing for mean/probability statistics.
+
+Only mean/probability admit principled smoothing (see docs: the "smoothing honesty rule").
+This module implements the fixed m-estimate and the ``smooth='auto'`` empirical-Bayes estimate.
+
+For ``smooth='auto'`` we use the documented empirical-Bayes form ``m_i = sigma_i^2 / tau^2`` with
+population (ddof=0) variances, blending ``lambda_i = n_i / (n_i + m_i)`` toward the global mean.
+The exact parity with scikit-learn's auto formula is a known follow-up (docs/known_issues KI-010);
+the leakage/determinism guarantees do not depend on the smoothing constant.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from .backends import _cpu
+
+
+def fit_mean_encoding(
+    keys: np.ndarray, y: np.ndarray, smooth, backend=None
+) -> tuple[pd.Series, float]:
+    """Return ``(encoding_by_category, global_mean)`` for a mean/probability target statistic.
+
+    ``y`` is the (possibly binarized, for classification) target aligned with ``keys``. The heavy
+    group-by runs on ``backend`` (CPU by default); the rest is host arithmetic, so CPU and GPU
+    produce the same table (to ``allclose``).
+    """
+    if backend is None:
+        backend = _cpu
+    stats = backend.category_reduce(keys, y)
+    count = stats["count"]
+    mean = stats["mean"]
+    global_mean = float(np.mean(np.asarray(y, dtype=float)))
+
+    if isinstance(smooth, str):
+        if smooth != "auto":
+            raise ValueError(f"smooth={smooth!r}: only 'auto' or a float >= 0 is allowed.")
+        var_pop = (stats["sumsq"] / count - mean**2).clip(lower=0.0)
+        tau2 = float(np.var(np.asarray(y, dtype=float)))  # population variance
+        if tau2 > 0:
+            m = var_pop / tau2
+        else:  # constant target -> every category mean equals the global mean
+            m = pd.Series(0.0, index=count.index)
+        lam = count / (count + m)
+        enc = lam * mean + (1.0 - lam) * global_mean
+    else:
+        m = float(smooth)
+        if m < 0:
+            raise ValueError("smooth must be >= 0.")
+        if m == 0.0:
+            enc = mean.copy()
+        else:
+            enc = (count * mean + m * global_mean) / (count + m)
+
+    return enc.astype(float), global_mean