DOC/TST: add pd.unique doc-string & buggy return of Categorical

closes #9346

Author: jreback

doc/source/whatsnew/v0.20.0.txt

@@ -999,6 +999,7 @@ Conversion
 - Bug in ``DataFrame.fillna()`` where the argument ``downcast`` was ignored when fillna value was of type ``dict`` (:issue:`15277`)
 - Bug in ``.asfreq()``, where frequency was not set for empty ``Series`` (:issue:`14320`)
 - Bug in ``DataFrame`` construction with nulls and datetimes in a list-like (:issue:`15869`)
+- Bug in the return type of ``pd.unique`` on a ``Categorical``, which was returning an ndarray and not a ``Categorical`` (:issue:`15903`)
 
 Indexing
 ^^^^^^^^

pandas/core/algorithms.py

@@ -267,11 +267,58 @@ def match(to_match, values, na_sentinel=-1):
     return result
 
 
-def unique1d(values):
+def unique(values):
     """
-    Hash table-based unique
+    Hash table-based unique. uniques are returned in order
+    of appearance. This doe NOT sort.
+
+    Parameters
+    ----------
+    values : 1d array-like
+
+    Returns
+    -------
+    unique values. The returned type will be a pandas Index
+    if a pandas type is input, otherwise ndarray
+
+    Examples
+    --------
+    pd.unique(pd.Series([2, 1, 3, 3]))
+    array([2, 1, 3])
+
+    >>> pd.unique(pd.Series([2] + [1] * 5))
+    array([2, 1])
+
+    >>> pd.unique(Series([pd.Timestamp('20160101'),
+    ...                   pd.Timestamp('20160101')]))
+    array(['2016-01-01T00:00:00.000000000'], dtype='datetime64[ns]')
+
+    >>> pd.unique(pd.Index([pd.Timestamp('20160101', tz='US/Eastern'),
+    ...                     pd.Timestamp('20160101', tz='US/Eastern')]))
+    DatetimeIndex(['2016-01-01 00:00:00-05:00'],
+    ...           dtype='datetime64[ns, US/Eastern]', freq=None)
+
+    >>> pd.unique(list('aabc'))
+    array(['a', 'b', 'c'], dtype=object)
+
+    >>> pd.unique(Series(pd.Categorical(list('aabc'))))
+    0    a
+    1    b
+    2    c
+    dtype: category
+    Categories (3, object): [a, b, c]
+
     """
     values = _ensure_arraylike(values)
+
+    # categorical is a fast-path
+    if is_categorical_dtype(values):
+
+        if isinstance(values, ABCSeries):
+            from pandas import Series
+            return Series(values.values.unique(), name=values.name)
+        return values.unique()
+
     original = values
     htable, _, values, dtype, ndtype = _get_hashtable_algo(values)
 
@@ -282,7 +329,7 @@ def unique1d(values):
     return uniques
 
 
-unique = unique1d
+unique1d = unique
 
 
 def isin(comps, values):
@@ -651,7 +698,7 @@ def mode(values):
     if is_categorical_dtype(values):
 
         if isinstance(values, Series):
-            return Series(values.values.mode())
+            return Series(values.values.mode(), name=values.name)
         return values.mode()
 
     values, dtype, ndtype = _ensure_data(values)

pandas/tests/test_algos.py

@@ -384,6 +384,51 @@ def test_uint64_overflow(self):
         exp = np.array([1, 2, 2**63], dtype=np.uint64)
         tm.assert_numpy_array_equal(algos.unique(s), exp)
 
+    def test_categorical(self):
+        c = pd.Categorical(list('aabc'))
+        result = c.unique()
+        expected = pd.Categorical(list('abc'))
+        tm.assert_categorical_equal(result, expected)
+
+        result = algos.unique(c)
+        tm.assert_categorical_equal(result, expected)
+
+        result = algos.unique(Series(c, name='foo'))
+        expected = Series(expected, name='foo')
+        tm.assert_series_equal(result, expected)
+
+    def test_order_of_appearance(self):
+        # 9346
+        # light testing of guarantee of order of appearance
+        # these also are the doc-examples
+        result = pd.unique(pd.Series([2, 1, 3, 3]))
+        tm.assert_numpy_array_equal(result, np.array([2, 1, 3]))
+
+        result = pd.unique(pd.Series([2] + [1] * 5))
+        tm.assert_numpy_array_equal(result, np.array([2, 1]))
+
+        result = pd.unique(Series([pd.Timestamp('20160101'),
+                                   pd.Timestamp('20160101')]))
+        expected = np.array(['2016-01-01T00:00:00.000000000'],
+                            dtype='datetime64[ns]')
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = pd.unique(pd.Index(
+            [pd.Timestamp('20160101', tz='US/Eastern'),
+             pd.Timestamp('20160101', tz='US/Eastern')]))
+        expected = pd.DatetimeIndex(['2016-01-01 00:00:00'],
+                                    dtype='datetime64[ns, US/Eastern]',
+                                    freq=None)
+        tm.assert_index_equal(result, expected)
+
+        result = pd.unique(list('aabc'))
+        expected = np.array(['a', 'b', 'c'], dtype=object)
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = pd.unique(Series(pd.Categorical(list('aabc'))))
+        expected = Series(pd.Categorical(list('abc')))
+        tm.assert_series_equal(result, expected)
+
 
 class TestIsin(tm.TestCase):