fix docs as per review

.unique of Categorical/Series now returns Categorical

Author: jreback

doc/source/whatsnew/v0.20.0.txt

@@ -608,36 +608,36 @@ datatypes would yield different return types. These are now made consistent. (:i
  .. code-block:: ipython
 
  # Series
- In [5]: Series(pd.Index([pd.Timestamp('20160101', tz='US/Eastern'),
-  pd.Timestamp('20160101', tz='US/Eastern')])).unique()
+ In [5]: pd.Series([pd.Timestamp('20160101', tz='US/Eastern'),
+ pd.Timestamp('20160101', tz='US/Eastern')]).unique()
  Out[5]: array([Timestamp('2016-01-01 00:00:00-0500', tz='US/Eastern')], dtype=object)
 
- In [6]: pd.unique(Series(pd.Index([pd.Timestamp('20160101', tz='US/Eastern'),
-  pd.Timestamp('20160101', tz='US/Eastern')])))
+ In [6]: pd.unique(pd.Series([pd.Timestamp('20160101', tz='US/Eastern'),
+ pd.Timestamp('20160101', tz='US/Eastern')]))
  Out[6]: array(['2016-01-01T05:00:00.000000000'], dtype='datetime64[ns]')
 
  # Index
  In [7]: pd.Index([pd.Timestamp('20160101', tz='US/Eastern'),
  pd.Timestamp('20160101', tz='US/Eastern')]).unique()
  Out[7]: DatetimeIndex(['2016-01-01 00:00:00-05:00'], dtype='datetime64[ns, US/Eastern]', freq=None)
 
- In [8]: pd.unique(pd.Index([pd.Timestamp('20160101', tz='US/Eastern'),
- pd.Timestamp('20160101', tz='US/Eastern')]))
+ In [8]: pd.unique([pd.Timestamp('20160101', tz='US/Eastern'),
+  pd.Timestamp('20160101', tz='US/Eastern')])
  Out[8]: array(['2016-01-01T05:00:00.000000000'], dtype='datetime64[ns]')
 
  New Behavior:
 
  .. ipython:: python
 
  # Series, returns an array of Timestamp tz-aware
- Series(pd.Index([pd.Timestamp('20160101', tz='US/Eastern'),
-  pd.Timestamp('20160101', tz='US/Eastern')])).unique()
- pd.unique(Series(pd.Index([pd.Timestamp('20160101', tz='US/Eastern'),
-  pd.Timestamp('20160101', tz='US/Eastern')])))
+ pd.Series([pd.Timestamp('20160101', tz='US/Eastern'),
+ pd.Timestamp('20160101', tz='US/Eastern')]).unique()
+ pd.unique(pd.Series([pd.Timestamp('20160101', tz='US/Eastern'),
+ pd.Timestamp('20160101', tz='US/Eastern')]))
 
  # Index, returns a DatetimeIndex
  pd.Index([pd.Timestamp('20160101', tz='US/Eastern'),
- pd.Timestamp('20160101', tz='US/Eastern')])
+ pd.Timestamp('20160101', tz='US/Eastern')]).unique()
  pd.unique(pd.Index([pd.Timestamp('20160101', tz='US/Eastern'),
  pd.Timestamp('20160101', tz='US/Eastern')]))
 
@@ -647,21 +647,21 @@ datatypes would yield different return types. These are now made consistent. (:i
 
  .. code-block:: ipython
 
- In [1]: pd.Series(pd.Categorical(list('aabc'))).unique()
+ In [1]: pd.Series(pd.Categorical(list('baabc'))).unique()
  Out[1]:
- [a, b, c]
- Categories (3, object): [a, b, c]
+ [b, a, c]
+ Categories (3, object): [b, a, c]
 
- In [2]: pd.unique(pd.Series(pd.Categorical(list('aabc'))).unique())
- Out[2]: array(['a', 'b', 'c'], dtype=object)
+ In [2]: pd.unique(pd.Series(pd.Categorical(list('baabc'))))
+ Out[2]: array(['b', 'a', 'c'], dtype=object)
 
  New Behavior:
 
  .. ipython:: python
 
  # returns a Categorical
- pd.Series(pd.Categorical(list('aabc'))).unique()
- pd.unique(pd.Series(pd.Categorical(list('aabc'))).unique())
+ pd.Series(pd.Categorical(list('baabc'))).unique()
+ pd.unique(pd.Series(pd.Categorical(list('baabc'))).unique())
 
 .. _whatsnew_0200.api_breaking.s3:
 

pandas/core/algorithms.py

@@ -269,19 +269,21 @@ def match(to_match, values, na_sentinel=-1):
 
 def unique(values):
  """
- Hash table-based unique. uniques are returned in order
+ Hash table-based unique. Uniques are returned in order
  of appearance. This does NOT sort.
 
+ Significantly faster than numpy.unique. Includes NA values.
+
  Parameters
  ----------
  values : 1d array-like
 
  Returns
  -------
  unique values.
- - If the input is a Categorical dtype, the return is a Categorical
- - If the input is an Index, the return is an Index
- - If the input is a Series/ndarray, the return will be an ndarray
+  - If the input is an Index, the return is an Index
+  - If the input is a Categorical dtype, the return is a Categorical
+  - If the input is a Series/ndarray, the return will be an ndarray
 
  Examples
  --------
@@ -305,26 +307,43 @@ def unique(values):
  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(list('baabc'))
+ array(['b', 'a', 'c'], dtype=object)
+
+ An unordered Categorical will return categories in the
+ order of appearance.
+
+ >>> pd.unique(Series(pd.Categorical(list('baabc'))))
+ [b, a, c]
+ Categories (3, object): [b, a, c]
+
+ >>> pd.unique(Series(pd.Categorical(list('baabc'),
+ ... categories=list('abc'))))
+ [b, a, c]
+ Categories (3, object): [b, a, c]
 
- >>> pd.unique(Series(pd.Categorical(list('aabc'))))
- 0 a
- 1 b
- 2 c
- dtype: category
- Categories (3, object): [a, b, c]
+ An ordered Categorical preserves the category ordering.
+
+ >>> pd.unique(Series(pd.Categorical(list('baabc'),
+ ... categories=list('abc'),
+ ... ordered=True)))
+ [b, a, c]
+ Categories (3, object): [a < b < c]
+
+ See Also
+ --------
+ pd.Index.unique
+ pd.Series.unique
 
  """
 
  values = _ensure_arraylike(values)
 
  # categorical is a fast-path
+ # this will coerce Categorical, CategoricalIndex,
+ # and category dtypes Series to same return of Category
  if is_categorical_dtype(values):
-
- if isinstance(values, ABCSeries):
- from pandas import Series
- return Series(values.values.unique(), name=values.name)
+ values = getattr(values, '.values', values)
  return values.unique()
 
  original = values

pandas/core/base.py

@@ -855,13 +855,24 @@ def value_counts(self, normalize=False, sort=True, ascending=False,
 
  _shared_docs['unique'] = (
  """
- Return %(unique)s of unique values in the object.
- Significantly faster than numpy.unique. Includes NA values.
- The order of the original is preserved.
+ Hash table-based unique. Uniques are returned in order
+ of appearance. This does NOT sort.
+
+ Parameters
+ ----------
+ values : 1d array-like
 
  Returns
  -------
- uniques : %(unique)s
+ unique values.
+ - If the input is an Index, the return is an Index
+ - If the input is a Categorical dtype, the return is a Categorical
+ - If the input is a Series/ndarray, the return will be an ndarray
+
+ See Also
+ --------
+ pd.unique
+ pd.Categorical.unique
  """)
 
  @Appender(_shared_docs['unique'] % _indexops_doc_kwargs)

pandas/core/categorical.py

@@ -1895,6 +1895,33 @@ def unique(self):
  Returns
  -------
  unique values : ``Categorical``
+
+ Examples
+ --------
+ An unordered Categorical will return categories in the
+ order of appearance.
+
+ >>> pd.Categorical(list('baabc'))
+ [b, a, c]
+ Categories (3, object): [b, a, c]
+
+ >>> pd.Categorical(list('baabc'), categories=list('abc'))
+ [b, a, c]
+ Categories (3, object): [b, a, c]
+
+ An ordered Categorical preserves the category ordering.
+
+ >>> pd.Categorical(list('baabc'),
+ ... categories=list('abc'),
+ ... ordered=True)
+ [b, a, c]
+ Categories (3, object): [a < b < c]
+
+ See Also
+ --------
+ pd.unique
+ pd.CategoricalIndex.unique
+
  """
 
  # unlike np.unique, unique1d does not sort

pandas/tests/test_algos.py

@@ -386,23 +386,46 @@ def test_uint64_overflow(self):
  tm.assert_numpy_array_equal(algos.unique(s), exp)
 
  def test_categorical(self):
+
+ # we are expecting to return in the order
+ # of appearance
+ expected = pd.Categorical(list('bac'),
+ categories=list('bac'))
+
+ # we are expecting to return in the order
+ # of the categories
+ expected_o = pd.Categorical(list('bac'),
+ categories=list('abc'),
+ ordered=True)
+
  # GH 15939
- c = pd.Categorical(list('aabc'))
+ c = pd.Categorical(list('baabc'))
  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)
+ c = pd.Categorical(list('baabc'), ordered=True)
+ result = c.unique()
+ tm.assert_categorical_equal(result, expected_o)
+
+ result = algos.unique(c)
+ tm.assert_categorical_equal(result, expected_o)
 
- # CI
- ci = pd.CategoricalIndex(pd.Categorical(list('aabc')))
+ # Series of categorical dtype
+ s = Series(pd.Categorical(list('baabc')), name='foo')
+ result = s.unique()
+ tm.assert_categorical_equal(result, expected)
+
+ result = pd.unique(s)
+ tm.assert_categorical_equal(result, expected)
+
+ # CI -> return CI
+ ci = pd.CategoricalIndex(pd.Categorical(list('baabc'),
+ categories=list('bac')))
+ expected = pd.CategoricalIndex(expected)
  result = ci.unique()
- expected = pd.CategoricalIndex(pd.Categorical(list('abc')))
  tm.assert_index_equal(result, expected)
 
  result = pd.unique(ci)
@@ -468,8 +491,8 @@ def test_order_of_appearance(self):
  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)
+ expected = pd.Categorical(list('abc'))
+ tm.assert_categorical_equal(result, expected)
 
 
 class TestIsin(tm.TestCase):