API/FIX: wrap result cut/qut in Series and make it ordered

As per the discussion in pandas-dev#8077, the result of cut/qcut should be
wrapped into a Series, now that this is possible.

Also change the returned Categorical to "ordered=True", this was
overlooked when this was introduced in Categorical.

Closes: pandas-dev#8077

Author: jankatins

pandas/tests/test_categorical.py

@@ -1058,8 +1058,8 @@ def test_assignment_to_dataframe(self):
         labels = [ "{0} - {1}".format(i, i + 499) for i in range(0, 10000, 500) ]
 
         df = df.sort(columns=['value'], ascending=True)
-        d = pd.cut(df.value, range(0, 10500, 500), right=False, labels=labels)
-        s = Series(d)
+        s = pd.cut(df.value, range(0, 10500, 500), right=False, labels=labels)
+        d = s.values
         df['D'] = d
         str(df)
 
@@ -1081,7 +1081,7 @@ def test_assignment_to_dataframe(self):
 
         # sorting
         s.name = 'E'
-        self.assertTrue(result2.sort_index().equals(s))
+        self.assertTrue(result2.sort_index().equals(s.sort_index()))
 
         cat = pd.Categorical([1,2,3,10], levels=[1,2,3,4,10])
         df = pd.DataFrame(pd.Series(cat))

pandas/tests/test_groupby.py

@@ -3313,7 +3313,8 @@ def test_groupby_categorical_unequal_len(self):
         import pandas as pd
         #GH3011
         series = Series([np.nan, np.nan, 1, 1, 2, 2, 3, 3, 4, 4])
-        bins =  pd.cut(series.dropna(), 4)
+        # The raises only happens with categorical, not with series of types category
+        bins =  pd.cut(series.dropna().values, 4)
 
         # len(bins) != len(series) here
         self.assertRaises(ValueError,lambda : series.groupby(bins).mean())

pandas/tools/tests/test_tile.py

@@ -123,7 +123,7 @@ def test_inf_handling(self):
         ex_levels = ['(-inf, 2]', '(2, 4]', '(4, inf]']
 
         np.testing.assert_array_equal(result.levels, ex_levels)
-        np.testing.assert_array_equal(result_ser.levels, ex_levels)
+        np.testing.assert_array_equal(result_ser.cat.levels, ex_levels)
         self.assertEqual(result[5], '(4, inf]')
         self.assertEqual(result[0], '(-inf, 2]')
         self.assertEqual(result_ser[5], '(4, inf]')
@@ -230,6 +230,25 @@ def test_qcut_binning_issues(self):
             self.assertTrue(ep < en)
             self.assertTrue(ep <= sn)
 
+    def test_cut_return_categorical(self):
+        from pandas import Categorical
+        s = Series([0,1,2,3,4,5,6,7,8])
+        res = cut(s,3)
+        exp = Series(Categorical.from_codes([0,0,0,1,1,1,2,2,2],
+                                            ["(-0.008, 2.667]", "(2.667, 5.333]", "(5.333, 8]"],
+                                            ordered=True))
+        tm.assert_series_equal(res, exp)
+
+    def test_qcut_return_categorical(self):
+        from pandas import Categorical
+        s = Series([0,1,2,3,4,5,6,7,8])
+        res = qcut(s,[0,0.333,0.666,1])
+        exp = Series(Categorical.from_codes([0,0,0,1,1,1,2,2,2],
+                                            ["[0, 2.664]", "(2.664, 5.328]", "(5.328, 8]"],
+                                            ordered=True))
+        tm.assert_series_equal(res, exp)
+
+
 
 def curpath():
     pth, _ = os.path.split(os.path.abspath(__file__))

pandas/tools/tile.py

@@ -34,7 +34,7 @@ def cut(x, bins, right=True, labels=None, retbins=False, precision=3,
         right == True (the default), then the bins [1,2,3,4] indicate
         (1,2], (2,3], (3,4].
     labels : array or boolean, default None
-        Labels to use for bin edges, or False to return integer bin labels
+        Labels to use for bins, or False to return integer bin labels.
     retbins : bool, optional
         Whether to return the bins or not. Can be useful if bins is given
         as a scalar.
@@ -45,7 +45,9 @@ def cut(x, bins, right=True, labels=None, retbins=False, precision=3,
 
     Returns
     -------
-    out : Categorical or array of integers if labels is False
+    out : Categorical or Series or array of integers if labels is False
+        The return type (Categorical or Series) depends on the input: a Series of type category if
+        input is a Series else Categorical.
     bins : ndarray of floats
         Returned only if `retbins` is True.
 
@@ -102,9 +104,12 @@ def cut(x, bins, right=True, labels=None, retbins=False, precision=3,
         if (np.diff(bins) < 0).any():
             raise ValueError('bins must increase monotonically.')
 
-    return _bins_to_cuts(x, bins, right=right, labels=labels,
-                         retbins=retbins, precision=precision,
-                         include_lowest=include_lowest)
+    res = _bins_to_cuts(x, bins, right=right, labels=labels,retbins=retbins, precision=precision,
+                        include_lowest=include_lowest)
+    if isinstance(x, Series):
+        res = Series(res, index=x.index)
+    return res
+
 
 
 def qcut(x, q, labels=None, retbins=False, precision=3):
@@ -130,7 +135,8 @@ def qcut(x, q, labels=None, retbins=False, precision=3):
 
     Returns
     -------
-    cat : Categorical
+    cat : Categorical or Series
+        Returns a Series of type category if input is a Series else Categorical.
 
     Notes
     -----
@@ -144,8 +150,12 @@ def qcut(x, q, labels=None, retbins=False, precision=3):
     else:
         quantiles = q
     bins = algos.quantile(x, quantiles)
-    return _bins_to_cuts(x, bins, labels=labels, retbins=retbins,
-                         precision=precision, include_lowest=True)
+    res = _bins_to_cuts(x, bins, labels=labels, retbins=retbins,precision=precision,
+                        include_lowest=True)
+    if isinstance(x, Series):
+        res = Series(res, index=x.index)
+    return res
+
 
 
 def _bins_to_cuts(x, bins, right=True, labels=None, retbins=False,
@@ -189,7 +199,7 @@ def _bins_to_cuts(x, bins, right=True, labels=None, retbins=False,
 
         levels = np.asarray(levels, dtype=object)
         np.putmask(ids, na_mask, 0)
-        fac = Categorical(ids - 1, levels, name=name, fastpath=True)
+        fac = Categorical(ids - 1, levels, ordered=True, name=name, fastpath=True)
     else:
         fac = ids - 1
         if has_nas: