PERF/API: Remove ordered requirement in Categorical.searchsorted

Author: tp

doc/source/whatsnew/v0.24.0.txt

@@ -220,7 +220,8 @@ Bug Fixes
 Categorical
 ^^^^^^^^^^^
 
--
+- :meth:`Categorical.searchsorted` and :meth:`CategoricalIndex.searchsorted`
+  now work on unordered categoricals also (:issue:`21667`)
 -
 -
 

pandas/core/arrays/categorical.py

@@ -1380,11 +1380,6 @@ def memory_usage(self, deep=False):
     @Appender(_shared_docs['searchsorted'])
     @deprecate_kwarg(old_arg_name='v', new_arg_name='value')
     def searchsorted(self, value, side='left', sorter=None):
-        if not self.ordered:
-            raise ValueError("Categorical not ordered\nyou can use "
-                             ".as_ordered() to change the Categorical to an "
-                             "ordered one")
-
         from pandas.core.series import Series
 
         values_as_codes = _get_codes_for_values(Series(value).values,

pandas/core/base.py

@@ -1163,6 +1163,16 @@ def factorize(self, sort=False, na_sentinel=-1):
         corresponding elements in `value` were inserted before the indices,
         the order of `self` would be preserved.
 
+        .. note::
+
+            The %(klass)s *must* be monotonically sorted, else wrong
+            index locations may be returned. Pandas does *not* check
+            this for you.
+
+            You can check sortedness by calling
+            ``is_monotonic_increasing/is_monotonic_decreasing`` on the
+            Series or Index.
+
         Parameters
         ----------
         value : array_like
@@ -1182,6 +1192,7 @@ def factorize(self, sort=False, na_sentinel=-1):
 
         See Also
         --------
+        sort_values
         numpy.searchsorted
 
         Notes
@@ -1199,7 +1210,7 @@ def factorize(self, sort=False, na_sentinel=-1):
         dtype: int64
 
         >>> x.searchsorted(4)
-        array([3])
+        array([3])  # Note: an array, not a scalar
 
         >>> x.searchsorted([0, 4])
         array([0, 3])
@@ -1216,10 +1227,17 @@ def factorize(self, sort=False, na_sentinel=-1):
         Categories (4, object): [apple < bread < cheese < milk]
 
         >>> x.searchsorted('bread')
-        array([1])     # Note: an array, not a scalar
+        array([1])
 
         >>> x.searchsorted(['bread'], side='right')
         array([3])
+
+        If the values are not monotonically sorted, wrong locations
+        may be returned:
+
+        >>> x = pd.Series([2, 1, 3])
+        >>> x.searchsorted(1)
+        array([0])  # wrong result, correct would be array([1])
         """)
 
     @Substitution(klass='IndexOpsMixin')

pandas/tests/categorical/test_analytics.py

@@ -70,58 +70,46 @@ def test_mode(self, values, categories, exp_mode):
         exp = Categorical(exp_mode, categories=categories, ordered=True)
         tm.assert_categorical_equal(res, exp)
 
-    def test_searchsorted(self):
+    @pytest.mark.parametrize("ordered", [True, False])
+    def test_searchsorted(self, ordered):
         # https://github.com/pandas-dev/pandas/issues/8420
         # https://github.com/pandas-dev/pandas/issues/14522
 
-        c1 = Categorical(['cheese', 'milk', 'apple', 'bread', 'bread'],
-                         categories=['cheese', 'milk', 'apple', 'bread'],
-                         ordered=True)
-        s1 = Series(c1)
-        c2 = Categorical(['cheese', 'milk', 'apple', 'bread', 'bread'],
-                         categories=['cheese', 'milk', 'apple', 'bread'],
-                         ordered=False)
-        s2 = Series(c2)
+        c = Categorical(['cheese', 'milk', 'apple', 'bread', 'bread'],
+                        categories=['cheese', 'milk', 'apple', 'bread'],
+                        ordered=ordered)
+        s = Series(c)
 
         # Searching for single item argument, side='left' (default)
-        res_cat = c1.searchsorted('apple')
-        res_ser = s1.searchsorted('apple')
+        res_cat = c.searchsorted('apple')
+        res_ser = s.searchsorted('apple')
         exp = np.array([2], dtype=np.intp)
         tm.assert_numpy_array_equal(res_cat, exp)
         tm.assert_numpy_array_equal(res_ser, exp)
 
         # Searching for single item array, side='left' (default)
-        res_cat = c1.searchsorted(['bread'])
-        res_ser = s1.searchsorted(['bread'])
+        res_cat = c.searchsorted(['bread'])
+        res_ser = s.searchsorted(['bread'])
         exp = np.array([3], dtype=np.intp)
         tm.assert_numpy_array_equal(res_cat, exp)
         tm.assert_numpy_array_equal(res_ser, exp)
 
         # Searching for several items array, side='right'
-        res_cat = c1.searchsorted(['apple', 'bread'], side='right')
-        res_ser = s1.searchsorted(['apple', 'bread'], side='right')
+        res_cat = c.searchsorted(['apple', 'bread'], side='right')
+        res_ser = s.searchsorted(['apple', 'bread'], side='right')
         exp = np.array([3, 5], dtype=np.intp)
         tm.assert_numpy_array_equal(res_cat, exp)
         tm.assert_numpy_array_equal(res_ser, exp)
 
         # Searching for a single value that is not from the Categorical
-        pytest.raises(ValueError, lambda: c1.searchsorted('cucumber'))
-        pytest.raises(ValueError, lambda: s1.searchsorted('cucumber'))
+        pytest.raises(ValueError, lambda: c.searchsorted('cucumber'))
+        pytest.raises(ValueError, lambda: s.searchsorted('cucumber'))
 
         # Searching for multiple values one of each is not from the Categorical
         pytest.raises(ValueError,
-                      lambda: c1.searchsorted(['bread', 'cucumber']))
+                      lambda: c.searchsorted(['bread', 'cucumber']))
         pytest.raises(ValueError,
-                      lambda: s1.searchsorted(['bread', 'cucumber']))
-
-        # searchsorted call for unordered Categorical
-        pytest.raises(ValueError, lambda: c2.searchsorted('apple'))
-        pytest.raises(ValueError, lambda: s2.searchsorted('apple'))
-
-        with tm.assert_produces_warning(FutureWarning):
-            res = c1.searchsorted(v=['bread'])
-            exp = np.array([3], dtype=np.intp)
-            tm.assert_numpy_array_equal(res, exp)
+                      lambda: s.searchsorted(['bread', 'cucumber']))
 
     def test_unique(self):
         # categories are reordered based on value when ordered=False