Basic implementation of OrdinalEncoder. (#5646)

- Implement `OrdinalEncoder`.
- Implement dask version.
- Fix dask transformers with DataFrame input by using `dask_cudf` to construct return df.

Some other scikit-learn features are not available yet, for instance, `encoded_missing_value`, `min_frequency`, and `max_categories`.

The implementation is mostly based on the existing one hot encoder and label encoder.

I'm a bit confused by the `output_type` parameter and not sure how strictly it's enforced. I looked around, it seems some estimators can ignore this parameter in their returns. Would be great if there's a guideline on how to handle this parameter, along with #5645 .

Close #4456 .

Authors:
  - Jiaming Yuan (https://github.com/trivialfis)
  - Simon Adorf (https://github.com/csadorf)

Approvers:
  - Simon Adorf (https://github.com/csadorf)

URL: #5646

python/cuml/common/doc_utils.py

@@ -94,6 +94,8 @@
     "    Ignored when return_sparse=False.\n"
     "    If True, values in the inverse transform below this parameter\n"
     "    are clipped to 0.",
+    None: "{name} : None\n"
+    "    Ignored. This parameter exists for compatibility only.",
 }
 
 _parameter_possible_values = [
@@ -222,7 +224,6 @@ def deco(func):
         if (
             "X" in params or "y" in params or parameters
         ) and not skip_parameters_heading:
-
             func.__doc__ += "\nParameters\n----------\n"
 
         # Check if we want to prepend the parameters

python/cuml/dask/common/base.py

@@ -36,6 +36,7 @@
 np = cpu_only_import("numpy")
 
 
+dask_cudf = gpu_only_import("dask_cudf")
 dcDataFrame = gpu_only_import_from("dask_cudf.core", "DataFrame")
 
 
@@ -343,7 +344,7 @@ def _run_parallel_func(
             if output_futures:
                 return self.client.compute(preds)
             else:
-                output = dask.dataframe.from_delayed(preds)
+                output = dask_cudf.from_delayed(preds)
                 return output if delayed else output.persist()
         else:
             raise ValueError(

python/cuml/dask/preprocessing/__init__.py

@@ -13,12 +13,13 @@
 # limitations under the License.
 #
 
+from cuml.dask.preprocessing.encoders import OneHotEncoder, OrdinalEncoder
 from cuml.dask.preprocessing.label import LabelBinarizer
-from cuml.dask.preprocessing.encoders import OneHotEncoder
 from cuml.dask.preprocessing.LabelEncoder import LabelEncoder
 
 __all__ = [
     "LabelBinarizer",
     "OneHotEncoder",
+    "OrdinalEncoder",
     "LabelEncoder",
 ]

python/cuml/dask/preprocessing/encoders.py

@@ -12,23 +12,46 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-from dask_cudf.core import Series as daskSeries
+from collections.abc import Sequence
+
 from cuml.common import with_cupy_rmm
+from cuml.dask.common.base import (
+    BaseEstimator,
+    DelayedInverseTransformMixin,
+    DelayedTransformMixin,
+)
+from cuml.internals.safe_imports import gpu_only_import_from, gpu_only_import
+from dask_cudf.core import Series as daskSeries
+from toolz import first
 
-from cuml.dask.common.base import BaseEstimator
-from cuml.dask.common.base import DelayedTransformMixin
-from cuml.dask.common.base import DelayedInverseTransformMixin
+dask_cudf = gpu_only_import("dask_cudf")
+dcDataFrame = gpu_only_import_from("dask_cudf.core", "DataFrame")
 
-from toolz import first
 
-from collections.abc import Sequence
-from cuml.internals.safe_imports import gpu_only_import_from
+class DelayedFitTransformMixin:
+    def fit_transform(self, X, delayed=True):
+        """Fit the encoder to X, then transform X. Equivalent to fit(X).transform(X).
 
-dcDataFrame = gpu_only_import_from("dask_cudf.core", "DataFrame")
+        Parameters
+        ----------
+        X : Dask cuDF DataFrame or CuPy backed Dask Array
+            The data to encode.
+        delayed : bool (default = True)
+            Whether to execute as a delayed task or eager.
+
+        Returns
+        -------
+        out : Dask cuDF DataFrame or CuPy backed Dask Array
+            Distributed object containing the transformed data
+        """
+        return self.fit(X).transform(X, delayed=delayed)
 
 
 class OneHotEncoder(
-    BaseEstimator, DelayedTransformMixin, DelayedInverseTransformMixin
+    BaseEstimator,
+    DelayedTransformMixin,
+    DelayedInverseTransformMixin,
+    DelayedFitTransformMixin,
 ):
     """
     Encode categorical features as a one-hot numeric array.
@@ -83,13 +106,9 @@ class OneHotEncoder(
         will be denoted as None.
     """
 
-    def __init__(self, *, client=None, verbose=False, **kwargs):
-        super().__init__(client=client, verbose=verbose, **kwargs)
-
     @with_cupy_rmm
     def fit(self, X):
-        """
-        Fit a multi-node multi-gpu OneHotEncoder to X.
+        """Fit a multi-node multi-gpu OneHotEncoder to X.
 
         Parameters
         ----------
@@ -111,10 +130,9 @@ def fit(self, X):
 
         return self
 
-    def fit_transform(self, X, delayed=True):
-        """
-        Fit OneHotEncoder to X, then transform X.
-        Equivalent to fit(X).transform(X).
+    @with_cupy_rmm
+    def transform(self, X, delayed=True):
+        """Transform X using one-hot encoding.
 
         Parameters
         ----------
@@ -126,52 +144,137 @@ def fit_transform(self, X, delayed=True):
         Returns
         -------
         out : Dask cuDF DataFrame or CuPy backed Dask Array
-            Distributed object containing the transformed data
+            Distributed object containing the transformed input.
         """
-        return self.fit(X).transform(X, delayed=delayed)
+        return self._transform(
+            X,
+            n_dims=2,
+            delayed=delayed,
+            output_dtype=self._get_internal_model().dtype,
+            output_collection_type="cupy",
+        )
 
     @with_cupy_rmm
-    def transform(self, X, delayed=True):
-        """
-        Transform X using one-hot encoding.
+    def inverse_transform(self, X, delayed=True):
+        """Convert the data back to the original representation. In case unknown
+        categories are encountered (all zeros in the one-hot encoding), ``None`` is used
+        to represent this category.
 
         Parameters
         ----------
-        X : Dask cuDF DataFrame or CuPy backed Dask Array
-            The data to encode.
+        X : CuPy backed Dask Array, shape [n_samples, n_encoded_features]
+            The transformed data.
         delayed : bool (default = True)
             Whether to execute as a delayed task or eager.
 
         Returns
         -------
-        out : Dask cuDF DataFrame or CuPy backed Dask Array
-            Distributed object containing the transformed input.
+        X_tr : Dask cuDF DataFrame or CuPy backed Dask Array
+            Distributed object containing the inverse transformed array.
+        """
+        dtype = self._get_internal_model().dtype
+        return self._inverse_transform(
+            X,
+            n_dims=2,
+            delayed=delayed,
+            output_dtype=dtype,
+            output_collection_type=self.datatype,
+        )
+
+
+class OrdinalEncoder(
+    BaseEstimator,
+    DelayedTransformMixin,
+    DelayedInverseTransformMixin,
+    DelayedFitTransformMixin,
+):
+    """Encode categorical features as an integer array.
+
+    The input to this transformer should be an :py:class:`dask_cudf.DataFrame` or a
+    :py:class:`dask.array.Array` backed by cupy, denoting the unique values taken on by
+    categorical (discrete) features. The features are converted to ordinal
+    integers. This results in a single column of integers (0 to n_categories - 1) per
+    feature.
+
+    Parameters
+    ----------
+    categories : :py:class:`cupy.ndarray` or :py:class`cudf.DataFrameq, default='auto'
+        Categories (unique values) per feature. All categories are expected to
+        fit on one GPU.
+        - 'auto' : Determine categories automatically from the training data.
+        - DataFrame/ndarray : ``categories[col]`` holds the categories expected
+          in the feature col.
+    handle_unknown : {'error', 'ignore'}, default='error'
+        Whether to raise an error or ignore if an unknown categorical feature is
+        present during transform (default is to raise). When this parameter is set
+        to 'ignore' and an unknown category is encountered during transform, the
+        resulting encoded value would be null when output type is cudf
+        dataframe.
+    verbose : int or boolean, default=False
+        Sets logging level. It must be one of `cuml.common.logger.level_*`.  See
+        :ref:`verbosity-levels` for more info.
+    """
+
+    @with_cupy_rmm
+    def fit(self, X):
+        """Fit Ordinal to X.
+
+        Parameters
+        ----------
+        X : :py:class:`dask_cudf.DataFrame` or a CuPy backed :py:class:`dask.array.Array`.
+            shape = (n_samples, n_features) The data to determine the categories of each
+            feature.
+
+        Returns
+        -------
+        self
+        """
+        from cuml.preprocessing.ordinalencoder_mg import OrdinalEncoderMG
+
+        el = first(X) if isinstance(X, Sequence) else X
+        self.datatype = (
+            "cudf" if isinstance(el, (dcDataFrame, daskSeries)) else "cupy"
+        )
+
+        self._set_internal_model(OrdinalEncoderMG(**self.kwargs).fit(X))
+
+        return self
+
+    @with_cupy_rmm
+    def transform(self, X, delayed=True):
+        """Transform X using ordinal encoding.
+
+        Parameters
+        ----------
+        X : :py:class:`dask_cudf.DataFrame` or cupy backed dask array.  The data to
+            encode.
+
+        Returns
+        -------
+        X_out :
+            Transformed input.
         """
         return self._transform(
             X,
             n_dims=2,
             delayed=delayed,
             output_dtype=self._get_internal_model().dtype,
-            output_collection_type="cupy",
+            output_collection_type=self.datatype,
         )
 
     @with_cupy_rmm
     def inverse_transform(self, X, delayed=True):
-        """
-        Convert the data back to the original representation.
-        In case unknown categories are encountered (all zeros in the
-        one-hot encoding), ``None`` is used to represent this category.
+        """Convert the data back to the original representation.
 
         Parameters
         ----------
-        X : CuPy backed Dask Array, shape [n_samples, n_encoded_features]
-            The transformed data.
+        X : :py:class:`dask_cudf.DataFrame` or cupy backed dask array.
         delayed : bool (default = True)
             Whether to execute as a delayed task or eager.
 
         Returns
         -------
-        X_tr : Dask cuDF DataFrame or CuPy backed Dask Array
+        X_tr :
             Distributed object containing the inverse transformed array.
         """
         dtype = self._get_internal_model().dtype

python/cuml/preprocessing/__init__.py

@@ -16,7 +16,7 @@
 from cuml.model_selection import train_test_split
 from cuml.preprocessing.LabelEncoder import LabelEncoder
 from cuml.preprocessing.label import LabelBinarizer, label_binarize
-from cuml.preprocessing.encoders import OneHotEncoder
+from cuml.preprocessing.encoders import OneHotEncoder, OrdinalEncoder
 from cuml.preprocessing.TargetEncoder import TargetEncoder
 from cuml.preprocessing import text
 
@@ -63,6 +63,7 @@
     "MissingIndicator",
     "Normalizer",
     "OneHotEncoder",
+    "OrdinalEncoder",
     "PolynomialFeatures",
     "PowerTransformer",
     "QuantileTransformer",