catstat

https://matapanino.github.io/catstat
Admin
catstat is a Python library for unified CPU and GPU statistical categorical encoding, offering...
Tokens:9,446
Snippets:34
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Package Initialization and Exports

Source: https://matapanino.github.io/catstat

Initializes the catstat package, defining the version and exporting core encoder classes.

```python
 1"""catstat -- unified CPU/GPU statistical categorical encoding.
 2
 3Leakage-safe target encoding generalized to arbitrary statistics
 4(``mean``/``count``/``frequency``/``var``/``std``/``median``/``min``/``max``/``skew``/``kurt``/
 5``woe``/custom callables), with one sklearn-compatible API and three principled mean smoothers
 6(fixed m-estimate; ``"auto"`` empirical-Bayes -- exactly scikit-learn's formula; ``"sigmoid"``,
 7category_encoders' blend).
 8
 9Runs on CPU (pandas/numpy) and on GPU (RAPIDS cuDF/CuPy), CPU/GPU-parity-validated. Pass a cuDF
10DataFrame and the whole encode stays **device-resident** (factorize, cross-fitting, gather, cuDF
11output) -- ~2.6-13x faster than CPU on a T4 at 100k-10M rows. For pandas-origin data the
12host<->device copies eat the win, so ``backend="auto"`` resolves to CPU there (KI-020); cuDF
13input routes to the GPU automatically. See docs/roadmap.md and docs/known_issues.md.
14"""
15
16from __future__ import annotations
17
18from .count_encoder import CountEncoder
19from .frequency_encoder import FrequencyEncoder
20from .target_encoder import TargetEncoder
21
22__all__ = ["TargetEncoder", "CountEncoder", "FrequencyEncoder", "__version__"]
23__version__ = "0.5.3"
```

--------------------------------

### Initialize TargetEncoder

Source: https://matapanino.github.io/catstat

The constructor defines the configuration for target encoding, including statistics, cross-fitting schemes, and binning strategies.

```python
def __init__(
    self,
    cols="auto",
    stats=("mean",),
    target_type="auto",
    smooth="auto",
    cv=5,
    scheme="kfold",
    shuffle=True,
    random_state=None,
    handle_unknown="value",
    handle_missing="value",
    multi_feature_mode="independent",
    min_samples_category=1,
    backend="auto",
    output="auto",
    numeric="ignore",
    cardinality_threshold=10,
    n_bins=10,
    binning="quantile",
    min_bin_size=None,
    interactions=None,
    max_classes=None,
):
    self.cols = cols
    self.stats = stats
    self.target_type = target_type
    self.smooth = smooth
    self.cv = cv
    self.scheme = scheme
    self.shuffle = shuffle
    self.random_state = random_state
    self.handle_unknown = handle_unknown
    self.handle_missing = handle_missing
    self.multi_feature_mode = multi_feature_mode
    self.min_samples_category = min_samples_category
    self.backend = backend
    self.output = output
    self.numeric = numeric
    self.cardinality_threshold = cardinality_threshold
    self.n_bins = n_bins
    self.binning = binning
    self.min_bin_size = min_bin_size
    self.interactions = interactions
    self.max_classes = max_classes
```

--------------------------------

### catstat __init__ method

Source: https://matapanino.github.io/catstat

The constructor for the catstat class, defining parameters for statistical calculations, cross-validation, and feature handling.

```python
 72    def __init__(
 73        self,
 74        cols="auto",
 75        stats=("mean",),
 76        target_type="auto",
 77        smooth="auto",
 78        cv=5,
 79        scheme="kfold",
 80        shuffle=True,
 81        random_state=None,
 82        handle_unknown="value",
 83        handle_missing="value",
 84        multi_feature_mode="independent",
 85        min_samples_category=1,
 86        backend="auto",
 87        output="auto",
 88        numeric="ignore",
 89        cardinality_threshold=10,
 90        n_bins=10,
 91        binning="quantile",
 92        min_bin_size=None,
 93        interactions=None,
 94        max_classes=None,
 95    ):
 96        self.cols = cols
 97        self.stats = stats
 98        self.target_type = target_type
 99        self.smooth = smooth
100        self.cv = cv
101        self.scheme = scheme
102        self.shuffle = shuffle
103        self.random_state = random_state
104        self.handle_unknown = handle_unknown
105        self.handle_missing = handle_missing
106        self.multi_feature_mode = multi_feature_mode
107        self.min_samples_category = min_samples_category
108        self.backend = backend
109        self.output = output
110        self.numeric = numeric
111        self.cardinality_threshold = cardinality_threshold
112        self.n_bins = n_bins
113        self.binning = binning
114        self.min_bin_size = min_bin_size
115        self.interactions = interactions
116        self.max_classes = max_classes
```

--------------------------------

### CountEncoder.__init__

Source: https://matapanino.github.io/catstat

Initializes a CountEncoder instance with configurable parameters for column selection, normalization, smoothing, missing/unknown handling, backend, output, and numeric column processing.

```APIDOC
## CountEncoder.__init__

### Description
Initializes a CountEncoder instance. This encoder replaces each category with its training count (or frequency if normalize=True). It is unsupervised, so no target variable is used.

### Method
Constructor

### Signature
CountEncoder(cols="auto", normalize=False, laplace_alpha=0.0, handle_unknown="value", handle_missing="value", backend="auto", output="auto", numeric="ignore", cardinality_threshold=10, n_bins=10, binning="quantile", min_bin_size=None)

### Parameters
- **cols** (str or list) - Optional - Columns to encode. Default "auto".
- **normalize** (bool) - Optional - If True, encode by frequency instead of count. Default False.
- **laplace_alpha** (float) - Optional - Laplace add-alpha smoothing for frequencies only. Must be >= 0. Default 0.0.
- **handle_unknown** (str) - Optional - Strategy for unseen categories. Default "value".
- **handle_missing** (str) - Optional - Strategy for missing values. Default "value".
- **backend** (str) - Optional - Backend to use. Default "auto".
- **output** (str) - Optional - Output type. Default "auto".
- **numeric** (str) - Optional - How to handle numeric columns: "ignore", "auto", "direct", or "bin". Default "ignore".
- **cardinality_threshold** (int or float) - Optional - Threshold for direct counting vs binning. Default 10.
- **n_bins** (int) - Optional - Number of bins for binning. Default 10.
- **binning** (str or list or dict) - Optional - Binning strategy: "quantile", "uniform", explicit edges, or per-column dict. Default "quantile".
- **min_bin_size** (int or float) - Optional - Minimum bin size to merge sparse bins. Default None.

### Notes
- If laplace_alpha > 0 and normalize=False, a ValueError is raised.
- Unseen categories map to 0 (count) or 0.0 (frequency).
- With Laplace smoothing, unseen categories fall back to alpha / (n + alpha*K).
- Numeric columns are either counted directly or binned based on cardinality_threshold.
- Bin edges are derived from feature values only.
- Fitted attributes: numeric_cols_, numeric_strategy_, bin_edges_.
```

--------------------------------

### Internal Helper Methods

Source: https://matapanino.github.io/catstat

Internal methods for checking supervision status and resolving statistical specifications.

```python
def _is_supervised(self) -> bool:
    return True

def _resolve_stat_specs(self):
    return resolve_stats(self.stats)
```

--------------------------------

### FrequencyEncoder __init__ method

Source: https://matapanino.github.io/catstat

The constructor for the FrequencyEncoder class, which initializes parameters for frequency encoding, Laplace smoothing, and numeric binning.

```python
20    def __init__(
21        self,
22        cols="auto",
23        laplace_alpha=0.0,
24        handle_unknown="value",
25        handle_missing="value",
26        backend="auto",
27        output="auto",
28        numeric="ignore",
29        cardinality_threshold=10,
30        n_bins=10,
31        binning="quantile",
32        min_bin_size=None,
33    ):
34        super().__init__(
35            cols=cols,
36            normalize=True,
37            laplace_alpha=laplace_alpha,
38            handle_unknown=handle_unknown,
39            handle_missing=handle_missing,
40            backend=backend,
41            output=output,
42            numeric=numeric,
43            cardinality_threshold=cardinality_threshold,
44            n_bins=n_bins,
45            binning=binning,
46            min_bin_size=min_bin_size,
47        )
```

--------------------------------

### CountEncoder.__init__

Source: https://matapanino.github.io/catstat

Constructor for the CountEncoder class. Initializes the encoder with parameters controlling column selection, normalization, smoothing, handling of unknown/missing values, backend, output, and numeric column binning.

```APIDOC
## CountEncoder.__init__

### Description
Initializes a CountEncoder instance. Encodes each category by its training count (or frequency if normalize=True). Unsupervised: no y is used, so there is no target leakage and fit_transform equals fit().transform(). Unseen categories map to 0 (count) / 0.0 (frequency).

### Method
Constructor

### Signature
CountEncoder(cols='auto', normalize=False, laplace_alpha=0.0, handle_unknown='value', handle_missing='value', backend='auto', output='auto', numeric='ignore', cardinality_threshold=10, n_bins=10, binning='quantile', min_bin_size=None)

### Parameters
- **cols** (str or list) - Optional - Columns to encode. Default 'auto'.
- **normalize** (bool) - Optional - If True, encode by frequency (count / n). Default False.
- **laplace_alpha** (float) - Optional - Laplace add-alpha smoothing to frequencies only. Default 0.0 (off).
- **handle_unknown** (str) - Optional - Strategy for handling unknown categories. Default 'value'.
- **handle_missing** (str) - Optional - Strategy for handling missing values. Default 'value'.
- **backend** (str) - Optional - Backend to use. Default 'auto'.
- **output** (str) - Optional - Output format. Default 'auto'.
- **numeric** (str) - Optional - How to handle numeric columns: 'ignore', 'auto', 'direct', or 'bin'. Default 'ignore'.
- **cardinality_threshold** (int or float) - Optional - Threshold for cardinality-based routing. Accepts int (absolute unique count) or float in (0,1] (unique/n ratio). Default 10.
- **n_bins** (int) - Optional - Number of bins for binning. Default 10.
- **binning** (str or list or dict) - Optional - Binning strategy: 'quantile', 'uniform', explicit edge array, or per-column dict. Default 'quantile'.
- **min_bin_size** (int or float) - Optional - Minimum bin size to merge sparse bins. Accepts int count or float fraction of n. Default None.

### Notes
- laplace_alpha applies only to frequencies: freq = (count + alpha) / (n + alpha * K) over K learned categories; unseen categories fall back to alpha / (n + alpha * K). Counts stay exact; normalize=False with laplace_alpha > 0 raises.
- numeric='auto' routes each numeric column by cardinality: at most cardinality_threshold distinct values are counted directly, otherwise the column is binned into n_bins. 'direct'/'bin' force one strategy.
- binning also accepts an explicit edge array (e.g., [0, 18, 65, 120] -> 3 bins) or a per-column dict. Explicit edges set the bin count; n_bins is ignored for that column.
- min_bin_size merges adjacent sparse bins of computed quantile/uniform strategies; explicit edge arrays are left exact.
- Inspect fitted attributes: numeric_cols_, numeric_strategy_, bin_edges_.
```

--------------------------------

### CountEncoder Initialization

Source: https://matapanino.github.io/catstat

The constructor for CountEncoder defines parameters for encoding categories by count, including options for normalization, Laplace smoothing, and numeric column handling.

```python
41    def __init__(
42        self,
43        cols="auto",
44        normalize=False,
45        laplace_alpha=0.0,
46        handle_unknown="value",
47        handle_missing="value",
48        backend="auto",
49        output="auto",
50        numeric="ignore",
51        cardinality_threshold=10,
52        n_bins=10,
53        binning="quantile",
54        min_bin_size=None,
55    ):
56        self.cols = cols
57        self.normalize = normalize
58        self.laplace_alpha = laplace_alpha
59        self.handle_unknown = handle_unknown
60        self.handle_missing = handle_missing
61        self.backend = backend
62        self.output = output
63        self.numeric = numeric
64        self.cardinality_threshold = cardinality_threshold
65        self.n_bins = n_bins
66        self.binning = binning
67        self.min_bin_size = min_bin_size
```

--------------------------------

### catstat version

Source: https://matapanino.github.io/catstat

The current version string of the catstat library.

```python
__version__ = '0.5.3'
```

--------------------------------

### FrequencyEncoder.__init__

Source: https://matapanino.github.io/catstat

Constructor for the FrequencyEncoder class, a subclass of CountEncoder. Encodes each category by its training frequency (count / n). Unseen categories map to 0.0.

```APIDOC
## FrequencyEncoder.__init__

### Description
Initializes a FrequencyEncoder instance. Encodes each category by its training frequency (count / n). Unseen categories map to 0.0. Supports Laplace smoothing and numeric column binning as in CountEncoder.

### Method
Constructor

### Signature
FrequencyEncoder(cols='auto', laplace_alpha=0.0, handle_unknown='value', handle_missing='value', backend='auto', output='auto', numeric='ignore', cardinality_threshold=10, n_bins=10, binning='quantile', min_bin_size=None)

### Parameters
- **cols** (str or list) - Optional - Columns to encode. Default 'auto'.
- **laplace_alpha** (float) - Optional - Laplace add-alpha smoothing: freq = (count + alpha) / (n + alpha * K); unseen categories fall back to alpha / (n + alpha * K). Default 0.0 (off).
- **handle_unknown** (str) - Optional - Strategy for handling unknown categories. Default 'value'.
- **handle_missing** (str) - Optional - Strategy for handling missing values. Default 'value'.
- **backend** (str) - Optional - Backend to use. Default 'auto'.
- **output** (str) - Optional - Output format. Default 'auto'.
- **numeric** (str) - Optional - How to handle numeric columns: 'ignore', 'auto', 'direct', or 'bin'. Default 'ignore'.
- **cardinality_threshold** (int or float) - Optional - Threshold for cardinality-based routing. Default 10.
- **n_bins** (int) - Optional - Number of bins for binning. Default 10.
- **binning** (str or list or dict) - Optional - Binning strategy: 'quantile', 'uniform', explicit edge array, or per-column dict. Default 'quantile'.
- **min_bin_size** (int or float) - Optional - Minimum bin size to merge sparse bins. Default None.

### Notes
- This class inherits from CountEncoder and always sets normalize=True.
- Numeric columns are binned exactly as in CountEncoder; a binned numeric column takes each row's bin frequency (normalized histogram).
```

--------------------------------

### FrequencyEncoder Class Definition

Source: https://matapanino.github.io/catstat

The FrequencyEncoder class inherits from CountEncoder and defaults to frequency-based encoding. It supports Laplace smoothing and numeric binning configurations.

```python
 9class FrequencyEncoder(CountEncoder):
10    """Encode each category by its training frequency (count / n). Unseen categories map to 0.0.
11
12    ``laplace_alpha`` (default 0.0 = off) applies Laplace add-α smoothing:
13    ``freq = (count + α) / (n + α·K)``; unseen categories then fall back to ``α / (n + α·K)``.
14
15    ``numeric`` (and ``cardinality_threshold`` / ``n_bins`` / ``binning``) opt numeric columns into
16    binning exactly as on :class:`CountEncoder`; a binned numeric column then takes each row's
17    **bin frequency** -- a normalized histogram. See :class:`CountEncoder` for the full description.
18    """
19
20    def __init__(
21        self,
22        cols="auto",
23        laplace_alpha=0.0,
24        handle_unknown="value",
25        handle_missing="value",
26        backend="auto",
27        output="auto",
28        numeric="ignore",
29        cardinality_threshold=10,
30        n_bins=10,
31        binning="quantile",
32        min_bin_size=None,
33    ):
34        super().__init__(
35            cols=cols,
36            normalize=True,
37            laplace_alpha=laplace_alpha,
38            handle_unknown=handle_unknown,
39            handle_missing=handle_missing,
40            backend=backend,
41            output=output,
42            numeric=numeric,
43            cardinality_threshold=cardinality_threshold,
44            n_bins=n_bins,
45            binning=binning,
46            min_bin_size=min_bin_size,
47        )
```

--------------------------------

### TargetEncoder Class Definition

Source: https://matapanino.github.io/catstat

Defines the TargetEncoder class, which provides leakage-safe target encoding generalized over multiple statistics and schemes.

```python
 10class TargetEncoder(_BaseStatEncoder):
 11    """Leakage-safe target encoding, generalized over a set of statistics.
 12
 13    ``fit_transform`` is leakage-safe for the training set; ``fit().transform()`` learns full-data
 14    encodings and is the path for *new* data. ``stats`` accepts built-ins
 15    (``mean``/``count``/``frequency``/``var``/``std``/``median``/``min``/``max``/``skew``/``kurt``/
 16    ``woe``, the last binary-only: ``logit(smoothed p) - logit(prior)``, unknown -> 0.0) and
 17    custom ``(name, callable)`` aggregations. ``scheme`` selects how the *mean* is cross-fitted on
 18    the training set: ``"kfold"`` (default, out-of-fold), ``"loo"`` (leave-one-out), or
 19    ``"ordered"`` (CatBoost-style ordered target statistics). ``loo``/``ordered`` apply to the mean
 20    only (use with ``stats=["mean"]``, optionally plus count/frequency).
 21
 22    Prior contract (2026-09-05 WP1): LOO uses the global mean of all other eligible
 23    rows; ordered uses the global mean of preceding eligible rows in its permutation.
 24    Empty support uses the fixed value 0.0, including single-row LOO and the first
 25    ordered row. With ``handle_missing="return_nan"``, missing feature rows do not
 26    contribute to that feature's category statistics or prior. These guarantees are
 27    conditional on the fitted target schema (type, class labels and selected output
 28    columns); changing that schema, including ``max_classes`` selection, can change
 29    output meaning/width. Empty-history multiclass outputs are all zero, not a
 30    normalized probability vector. Later ``transform`` still uses full-fit maps and
 31    priors. LOO uses weight 0 for ``smooth="auto"``; ordered uses weight 1 for
 32    ``"auto"`` or non-positive smoothing, as before.
 33
 34    ``numeric`` opts numeric columns into encoding (default ``"ignore"`` keeps today's behavior:
 35    ``cols="auto"`` skips numerics). ``"auto"`` routes each numeric column by cardinality -- at most
 36    ``cardinality_threshold`` distinct values are encoded **directly** (each value a category),
 37    otherwise the column is **binned** into ``n_bins`` (``binning="quantile"`` equal-frequency, or
 38    ``"uniform"`` equal-width) and the bins are target-encoded; ``"direct"``/``"bin"`` force one
 39    strategy. ``binning`` also accepts an explicit **edge array** (``[0, 18, 65, 120]`` -> 3 bins,
 40    applied to every binned column) or a per-column ``{col: strategy-or-edges}`` **dict** (e.g.
 41    ``{"age": [0, 18, 65, 120], "income": "quantile"}``); explicit edges set the bin count, so
 42    ``n_bins`` is ignored for that column, and ``binning`` only controls *how* a column is binned --
```

--------------------------------

### CountEncoder Class Definition

Source: https://matapanino.github.io/catstat

The CountEncoder class implementation, including its constructor and internal configuration methods for handling categorical and numeric data.

```python
12class CountEncoder(_BaseStatEncoder):
13    """Encode each category by its training count (or frequency if ``normalize=True``).
14
15    Unsupervised: no ``y`` is used, so there is no target leakage and ``fit_transform`` equals
16    ``fit().transform()``. Unseen categories map to 0 (count) / 0.0 (frequency).
17
18    ``laplace_alpha`` (default 0.0 = off) applies **Laplace add-α smoothing to frequencies
19    only**: ``freq = (count + α) / (n + α·K)`` over the ``K`` learned categories, and an unseen
20    category falls back to ``α / (n + α·K)`` instead of 0.0. Counts stay exact (the smoothing
21    honesty rule) -- ``normalize=False`` with ``laplace_alpha > 0`` raises.
22
23    ``numeric`` opts numeric columns into encoding (default ``"ignore"`` keeps today's behavior:
24    ``cols="auto"`` skips numerics). ``"auto"`` routes each numeric column by cardinality -- at most
25    ``cardinality_threshold`` distinct values are counted **directly** (each value a category),
26    otherwise the column is **binned** into ``n_bins`` (``binning="quantile"`` equal-frequency, or
27    ``"uniform"`` equal-width) and each row takes its **bin's count** -- a histogram (a normalized
28    histogram when ``normalize=True``). ``"direct"``/``"bin"`` force one strategy. ``binning`` also
29    accepts an explicit **edge array** (``[0, 18, 65, 120]`` -> 3 bins, applied to every binned
30    column) or a per-column ``{col: strategy-or-edges}`` **dict**; explicit edges set the bin count
31    (``n_bins`` is then ignored for that column), and ``binning`` controls only *how* a column is
32    binned (*whether* stays with ``numeric`` + ``cardinality_threshold``). Bin edges come from
33    feature values only (there is no ``y``), so they are a plain function of the training column (or
34    of the user's explicit edges). ``min_bin_size`` (an int count, or a float fraction of ``n``)
35    merges adjacent sparse bins of the *computed* ``quantile``/``uniform`` strategies; explicit edge
36    arrays are left exact. ``cardinality_threshold`` accepts an int (absolute unique count) or a
37    float in (0, 1] (unique/n ratio). Inspect the fitted ``numeric_cols_`` / ``numeric_strategy_`` /
38    ``bin_edges_`` attrs.
39    """
40
41    def __init__(
42        self,
43        cols="auto",
44        normalize=False,
45        laplace_alpha=0.0,
46        handle_unknown="value",
47        handle_missing="value",
48        backend="auto",
49        output="auto",
50        numeric="ignore",
51        cardinality_threshold=10,
52        n_bins=10,
53        binning="quantile",
54        min_bin_size=None,
55    ):
56        self.cols = cols
57        self.normalize = normalize
58        self.laplace_alpha = laplace_alpha
59        self.handle_unknown = handle_unknown
60        self.handle_missing = handle_missing
61        self.backend = backend
62        self.output = output
63        self.numeric = numeric
64        self.cardinality_threshold = cardinality_threshold
65        self.n_bins = n_bins
66        self.binning = binning
67        self.min_bin_size = min_bin_size
68
69    def _is_supervised(self) -> bool:
70        return False
71
72    def _resolve_stat_specs(self):
73        alpha = self.laplace_alpha
74        alpha = 0.0 if alpha is None else float(alpha)
75        if alpha < 0 or not np.isfinite(alpha):
76            raise ValueError(f"laplace_alpha={self.laplace_alpha!r} must be a finite float >= 0.")
77        if alpha > 0 and not self.normalize:
78            raise ValueError(
79                "laplace_alpha smooths frequencies only; counts are exact (the smoothing "
80                "honesty rule). Use normalize=True / FrequencyEncoder, or laplace_alpha=0."
81            )
82        return resolve_stats(["frequency" if self.normalize else "count"])
```
Tokens:
Raw