# TargetEncoder

### *class* cuml.preprocessing.TargetEncoder(, n_folds=4, smooth=0, seed=42, split_method='interleaved', verbose=False, output_type=None, stat='mean', multi_feature_mode='combination')[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/preprocessing/_target_encoder.py#L35)

A cudf based implementation of target encoding [[1]](#r331d970812b4-1), which converts
one or multiple categorical variables, ‘Xs’, with the average of
corresponding values of the target variable, ‘Y’. The input data is
grouped by the columns `Xs` and the aggregated mean value of `Y` of
each group is calculated to replace each value of `Xs`. Several
optimizations are applied to prevent label leakage and parallelize
the execution.

* **Parameters:**
  **n_folds**
  : Default number of folds for fitting training data. To prevent
    label leakage in [`fit`](#cuml.preprocessing.TargetEncoder.fit), we split data into `n_folds` and
    encode one fold using the target variables of the remaining folds.

  **smooth**
  : Count of samples to smooth the encoding. 0 means no smoothing.

  **seed**
  : Random seed

  **split_method**
  : Method to split train data into `n_folds`.
    ‘random’: random split.
    ‘continuous’: consecutive samples are grouped into one folds.
    ‘interleaved’: samples are assign to each fold in a round robin way.
    ‘customize’: customize splitting by providing a `fold_ids` array
    in [`fit()`](#cuml.preprocessing.TargetEncoder.fit) or [`fit_transform()`](#cuml.preprocessing.TargetEncoder.fit_transform) functions.

  **verbose**
  : Sets logging level. It must be one of `cuml.common.logger.level_*`.
    See [Verbosity Levels](../../cuml/index.html.md#verbosity-levels) for more info.

  **output_type**
  : Return results and set estimator attributes to the indicated output
    type. If None, the output type set at the module level
    (`cuml.global_settings.output_type`) will be used. See
    [Output Data Type Configuration](../../cuml/index.html.md#output-data-type-configuration) for more info.

  **stat**
  : The statistic used in encoding, mean, variance or median of the
    target.

  **multi_feature_mode**
  : How to handle multiple input features:
    - `'combination'`: Encode all feature combinations together
      (cuML native behavior). Produces a single output column with
      encodings based on the joint distribution of all features.
    - `'independent'`: Encode each feature independently (sklearn
      behavior). Produces N output columns, one per input feature,
      each containing encodings based only on that feature’s
      relationship with the target.
    <br/>
    For single-feature input, both modes produce identical results.
* **Attributes:**
  **categories_**
  : The categories of each input feature determined during fitting.
    Each element is an array of unique category values for that feature,
    sorted in ascending order.

  **target_type_**
  : Type of target.

  **classes_**
  : The labels for each class if `target_type_` is ‘binary’, [`None`](https://docs.python.org/3/builtins/constants.html#None)
    otherwise.

  **n_features_in_**
  : Number of features seen during [`fit()`](#cuml.preprocessing.TargetEncoder.fit).

  **encode_all**
  : DataFrame containing the learned encodings for all category
    combinations, or a list of such dataframes if fit with
    `multi_feature_mode="independent"`. Used internally for transforming
    new data.

  **mean**
  : The overall mean of the target variable, computed during fitting.
    Used for smoothing and imputing unseen categories.

  **y_stat_val**
  : The statistic value (mean, variance, or median) of the target
    variable, depending on the `stat` parameter. Used to impute
    encodings for unseen categories.

  **train**
  : The training DataFrame used during fitting, containing the original
    features, target values, and fold assignments. Set to `None` if
    the encoder was loaded from a sklearn model via [`from_sklearn()`](#cuml.preprocessing.TargetEncoder.from_sklearn).

  **train_encode**
  : The encoded values for the training data, computed during
    [`fit()`](#cuml.preprocessing.TargetEncoder.fit) or [`fit_transform()`](#cuml.preprocessing.TargetEncoder.fit_transform). Set to `None` if the
    encoder was loaded from a sklearn model via [`from_sklearn()`](#cuml.preprocessing.TargetEncoder.from_sklearn).

### Methods

| [`fit`](#cuml.preprocessing.TargetEncoder.fit)(X, y, \*[, fold_ids])               | Fit a TargetEncoder instance to a set of categories   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------|
| [`fit_transform`](#cuml.preprocessing.TargetEncoder.fit_transform)(X, y, \*[, fold_ids])     | Simultaneously fit and transform an input             |
| [`get_feature_names_out`](#cuml.preprocessing.TargetEncoder.get_feature_names_out)([input_features]) | Get output feature names for transformation.          |
| [`transform`](#cuml.preprocessing.TargetEncoder.transform)(X)                            | Transform an input into its categorical keys.         |

### Notes

**sklearn Conversion Limitations**

When converting between cuML and sklearn via [`as_sklearn()`](#cuml.preprocessing.TargetEncoder.as_sklearn) and
[`from_sklearn()`](#cuml.preprocessing.TargetEncoder.from_sklearn), be aware of the following semantic differences:

- **Training data behavior**: cuML’s [`transform()`](#cuml.preprocessing.TargetEncoder.transform) returns
  cross-validated (regularized) encodings when called on training data
  to prevent data leakage. sklearn’s `transform` always returns global
  mean encodings regardless of whether the input is training or test data.
  After roundtrip conversion, the cuML model will return global encodings
  for all data since the training data reference is not preserved.
- **Multi-feature encoding**: cuML’s default `multi_feature_mode='combination'`
  encodes feature combinations jointly, while sklearn always encodes features
  independently. Multi-feature models fitted with `'combination'` mode
  cannot be converted to sklearn; use `multi_feature_mode='independent'`
  for sklearn compatibility.

**Cross-Validation Differences**

cuML and sklearn use different cross-validation fold assignment strategies
during `fit_transform`. Both are valid target encoding implementations,
but they produce different encoded values for the same input:

- **sklearn**: Uses `KFold`/`StratifiedKFold` with specific sample-to-fold
  assignments based on `random_state`.
- **cuML**: Uses configurable `split_method` (`'interleaved'`, `'random'`,
  `'continuous'`, or `'customize'`) with different fold assignment logic.

Because samples are assigned to different folds, the leave-fold-out encoding
for each sample is computed from different data subsets. For example:

```default
# Same data, same random_state, different encoded values:
# sklearn fit_transform: [0.52, 0.48, 0.51, 0.49, ...]
# cuML fit_transform:    [0.50, 0.51, 0.49, 0.52, ...]
```

This difference only affects `fit_transform` on training data. The
`transform` method on test data produces equivalent results since it
uses global statistics computed from all training samples.

### References

### Examples

Converting a categorical implementation to a numerical one

```pycon
>>> from cudf import DataFrame, Series
>>> from cuml.preprocessing import TargetEncoder
>>> train = DataFrame({'category': ['a', 'b', 'b', 'a'],
...                    'label': [1, 0, 1, 1]})
>>> test = DataFrame({'category': ['a', 'c', 'b', 'a']})
```

```pycon
>>> encoder = TargetEncoder(output_type='numpy')
>>> encoded = encoder.fit_transform(train[["category"]], train.label)
>>> encoded
array([[1.],
       [1.],
       [0.],
       [1.]])
```

<!-- !! processed by numpydoc !! -->

#### as_sklearn()[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/interop.py#L206)

Convert this estimator into an equivalent scikit-learn (or scikit-learn
extension) estimator.

* **Returns:**
  sklearn.base.BaseEstimator
  : A scikit-learn compatible estimator instance that mirrors the trained
    state of the current estimator.

<!-- !! processed by numpydoc !! -->

#### fit(X, y, , fold_ids=None)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/preprocessing/_target_encoder.py#L217)

Fit a TargetEncoder instance to a set of categories

* **Parameters:**
  **X**
  : categories to be encoded. It’s elements may or may
    not be unique

  **y**
  : Series containing the target variable.

  **fold_ids**
  : Series containing the indices of the customized
    folds. Its values should be integers in range
    `[0, N-1]` to split data into `N` folds. If None,
    fold_ids is generated based on `split_method`.
* **Returns:**
  **self**
  : A fitted instance of itself to allow method chaining

<!-- !! processed by numpydoc !! -->

#### fit_transform(X, y, , fold_ids=None)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/preprocessing/_target_encoder.py#L245)

Simultaneously fit and transform an input

This is functionally equivalent to (but faster than)
`TargetEncoder().fit(X, y).transform(X)`

* **Parameters:**
  **X**
  : categories to be encoded. It’s elements may or may
    not be unique

  **y**
  : Series containing the target variable.

  **fold_ids**
  : Series containing the indices of the customized
    folds. Its values should be integers in range
    `[0, N-1]` to split data into `N` folds. If None,
    fold_ids is generated based on `split_method`.
* **Returns:**
  **encoded**
  : The ordinally encoded input series

<!-- !! processed by numpydoc !! -->

#### *classmethod* from_sklearn(model)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/interop.py#L222)

Create a cuml estimator from a scikit-learn estimator.

* **Parameters:**
  **model**
  : A compatible scikit-learn (or scikit-learn extension) estimator.
* **Returns:**
  cls
  : A new instance of this cuml estimator class that mirrors the
    state of the input estimator.

### Notes

`output_type` of the estimator is set to “numpy” by default, as these
cannot be inferred from training arguments. If something different is
required, then please use cuml’s output_type configuration utilities.

<!-- !! processed by numpydoc !! -->

#### get_feature_names_out(input_features=None)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/preprocessing/_target_encoder.py#L275)

Get output feature names for transformation.

* **Parameters:**
  **input_features**
  : Input feature names.
* **Returns:**
  **feature_names_out**
  : Transformed feature names.

<!-- !! processed by numpydoc !! -->

#### get_params(deep=True)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/base.py#L191)

Returns a dict of all params owned by this class. If the child class
has appropriately overridden the `_get_param_names` method and does not
need anything other than what is there in this method, then it doesn’t
have to override this method

<!-- !! processed by numpydoc !! -->

#### set_params(\*\*params)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/base.py#L200)

Accepts a dict of params and updates the corresponding ones owned by
this class. If the child class has appropriately overridden the
`_get_param_names` method and does not need anything other than what is,
there in this method, then it doesn’t have to override this method

<!-- !! processed by numpydoc !! -->

#### transform(X)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/preprocessing/_target_encoder.py#L294)

Transform an input into its categorical keys.

This is intended for test data. For fitting and transforming
the training data, prefer [`fit_transform`](#cuml.preprocessing.TargetEncoder.fit_transform).

* **Parameters:**
  **X**
  : Input keys to be transformed. Its values doesn’t have to
    match the categories given to [`fit`](#cuml.preprocessing.TargetEncoder.fit)
* **Returns:**
  **encoded**
  : The ordinally encoded input series

<!-- !! processed by numpydoc !! -->