Implement factorize for MultiIndex (#23139)

- Implements `MultiIndex._factorize` so `factorize` on a MultiIndex (and tuple data) returns codes and uniques across all levels, with first-appearance or lexicographic ordering per `sort`.
- Removes 5 now-passing entries from the pandas-testing plugin and documents the reason for one remaining inherent failure.
- Split out from #23138.

Authors:
  - GALI PREM SAGAR (https://github.com/galipremsagar)

Approvers:
  - Matthew Roeschke (https://github.com/mroeschke)

URL: #23139

Author: galipremsagar

python/cudf/cudf/core/multiindex.py

@@ -1793,6 +1793,55 @@ def unique(self, level: int | None = None) -> Self | Index:
         else:
             return self.get_level_values(level).unique()
 
+    def _factorize(
+        self, sort: bool, use_na_sentinel: bool
+    ) -> tuple[cp.ndarray, MultiIndex]:
+        if any(col.has_nulls() for col in self._columns):
+            raise NotImplementedError(
+                "factorize on a MultiIndex with missing values is not yet "
+                "supported"
+            )
+        if len(self) == 0:
+            return cp.empty(0, dtype=np.intp), self.copy()
+
+        level_labels = list(range(self.nlevels))
+        df = cudf.DataFrame._from_data(
+            dict(zip(level_labels, self._columns, strict=True))
+        )
+        pos_label = self.nlevels
+        df[pos_label] = range(len(df))
+
+        # the uniques are the distinct rows in order of first appearance
+        # (or sorted lexicographically when requested)
+        uniques = (
+            df.groupby(level_labels, sort=False)
+            .agg({pos_label: "min"})
+            .reset_index()
+        )
+        uniques = uniques.sort_values(
+            by=level_labels if sort else pos_label, ignore_index=True
+        )
+        uid_label = self.nlevels + 1
+        uniques[uid_label] = range(len(uniques))
+
+        # codes: map each row to its unique-row id, in the original order
+        merged = df.merge(
+            uniques[[*level_labels, uid_label]],
+            on=level_labels,
+            how="left",
+        )
+        codes = (
+            merged.sort_values(by=pos_label)[uid_label]
+            .astype(np.dtype(np.intp))
+            .values
+        )
+        # pandas does not propagate the level names to the uniques
+        uniques_mi = MultiIndex._from_data(
+            {label: uniques._data[label] for label in level_labels}
+        )
+        uniques_mi.names = [None] * self.nlevels
+        return codes, uniques_mi
+
     @_performance_tracking
     def nunique(self, dropna: bool = True) -> int:
         mi = self.dropna(how="all") if dropna else self

python/cudf/cudf/pandas/scripts/pandas-testing-plugin.py

@@ -4312,12 +4312,7 @@ def pytest_unconfigure(config):
     "tests/strings/test_split_partition.py::test_split_nan_expand[string=object]": "AssertionError: DataFrame.iloc[:, 0] (column name='0') are different",
     "tests/strings/test_strings.py::test_index_str_accessor_multiindex_raises": "TODO: Add a reason for failure",
     "tests/strings/test_strings.py::test_string_slice_out_of_bounds[string=object]": "AssertionError: Series are different",
-    "tests/test_algos.py::TestFactorize::test_factorize[multi-False]": "NotImplementedError: Fast implementation not available. Falling back to the slow implementation",
-    "tests/test_algos.py::TestFactorize::test_factorize[multi-True]": "NotImplementedError: Fast implementation not available. Falling back to the slow implementation",
-    "tests/test_algos.py::TestFactorize::test_factorize[tuples-False]": "AssertionError: Index are different",
-    "tests/test_algos.py::TestFactorize::test_factorize[tuples-True]": "AssertionError: Index are different",
-    "tests/test_algos.py::TestFactorize::test_int_factorize_use_na_sentinel_false[data0-expected_codes0-expected_uniques0]": "TODO: Add a reason for failure",
-    "tests/test_algos.py::TestUnique::test_factorize_multiindex_empty": "AssertionError: Index are different",
+    "tests/test_algos.py::TestFactorize::test_int_factorize_use_na_sentinel_false[data0-expected_codes0-expected_uniques0]": "cudf cannot represent an object column of Python ints with NaN; the uniques come back float64",
     "tests/test_algos.py::TestValueCounts::test_value_counts_dropna": "pandas keeps bool-with-None data as object dtype; cudf stores it as a masked bool column",
     "tests/test_algos.py::TestValueCounts::test_value_counts_stability": "asserts that kind='quicksort' produces an unstable order; cudf sorts are always stable",
     "tests/test_col.py::test_cached_property": "AssertionError: assert False",

python/cudf/cudf/tests/general_functions/test_factorize.py

@@ -1,9 +1,10 @@
-# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION.
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
 import cupy as cp
 import numpy as np
 import pandas as pd
+import pytest
 
 import cudf
 from cudf.testing import assert_eq
@@ -86,3 +87,30 @@ def test_factorize_rangeindex_preserves_class():
         assert isinstance(cats, cudf.RangeIndex)
         assert_eq(cats, p_cats, exact=True)
         np.testing.assert_array_equal(labels.get(), p_labels)
+
+
+@pytest.mark.parametrize("sort", [False, True])
+def test_factorize_multiindex(sort):
+    # The uniques are the distinct rows (without level names), matching
+    # pandas.
+    pmi = pd.MultiIndex.from_arrays(
+        [["bar", "baz", "foo", "bar"], [2, 3, 1, 2]], names=["a", "b"]
+    )
+    gmi = cudf.Index(pmi)
+
+    expected_codes, expected_uniques = pmi.factorize(sort=sort)
+    codes, uniques = gmi.factorize(sort=sort)
+
+    np.testing.assert_array_equal(codes.get(), expected_codes)
+    assert_eq(uniques, expected_uniques)
+
+
+def test_factorize_multiindex_empty():
+    pmi = pd.MultiIndex.from_arrays(
+        [pd.Index([], dtype=object), pd.Index([], dtype="f4")]
+    )
+    gmi = cudf.Index(pmi)
+
+    codes, uniques = gmi.factorize()
+    assert len(codes) == 0
+    assert_eq(uniques, gmi[:0])