### 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"]) ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.