docs

Author: jreback

.gitignore

@@ -55,7 +55,7 @@ dist
 ######################
 .directory
 .gdb_history
-.DS_Store?
+.DS_Store
 ehthumbs.db
 Icon?
 Thumbs.db

doc/source/advanced.rst

@@ -594,7 +594,76 @@ faster than fancy indexing.
    timeit ser.ix[indexer]
    timeit ser.take(indexer)
 
-.. _indexing.float64index:
+.. _indexing.categoricalindex:
+
+CategoricalIndex
+----------------
+
+.. versionadded:: 0.16.1
+
+We introduce a ``CategoricalIndex``, a new type of index object that is useful for supporting
+indexing with duplicates. This is a container around a ``Categorical`` (introduced in v0.15.0)
+and allows efficient indexing and storage of a index with a larger number of duplicated elements. Prior to 0.16.1,
+setting the index of a ``DataFrame/Series`` with a ``category`` dtype would convert this to regular object-based ``Index``.
+
+.. ipython:: python
+
+   df = DataFrame({'A' : np.arange(6),
+                   'B' : Series(list('aabbca')).astype('category',
+                                                       categories=list('cab'))
+                  })
+   df
+   df.dtypes
+   df.B.cat.categories
+
+Setting the index, will create create a ``CategoricalIndex``
+
+.. ipython:: python
+
+   df2 = df.set_index('B')
+   df2.index
+   df2.index.categories
+
+Indexing works similarly to an ``Index`` with duplicates
+
+.. ipython:: python
+
+   df2.loc['a']
+
+   # and preserves the CategoricalIndex
+   df2.loc['a'].index
+   df2.loc['a'].index.categories
+
+Sorting will order by the order of the categories
+
+.. ipython:: python
+
+   df2.sort_index()
+
+Groupby operations on the index will preserve the index nature as well
+
+.. ipython:: python
+
+   df2.groupby(level=0).sum()
+   df2.groupby(level=0).sum().index
+
+.. warning::
+
+   Reshaping and Comparision operations on a ``CategoricalIndex`` must have the same categories
+   or a ``TypeError`` will be raised.
+
+   .. code-block:: python
+
+      In [10]: df3 = DataFrame({'A' : np.arange(6),
+                                'B' : Series(list('aabbca')).astype('category',
+                                                                    categories=list('abc'))
+                               }).set_index('B')
+
+      In [11]: df3.index.categories
+      Out[11]: Index([u'a', u'b', u'c'], dtype='object')
+
+      In [12]: pd.concat([df2,df3]
+      TypeError: categories must match existing categories when appending
 
 Float64Index
 ------------
@@ -706,4 +775,3 @@ Of course if you need integer based selection, then use ``iloc``
 .. ipython:: python
 
    dfir.iloc[0:5]
-

doc/source/api.rst

@@ -1289,6 +1289,26 @@ Selecting
    Index.slice_indexer
    Index.slice_locs
 
+.. _api.categoricalindex:
+
+CategoricalIndex
+----------------
+
+.. autosummary::
+   :toctree: generated/
+
+   CategoricalIndex
+
+Categorical Components
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   CategoricalIndex.codes
+   CategoricalIndex.categories
+   CategoricalIndex.ordered
+
 .. _api.datetimeindex:
 
 DatetimeIndex

doc/source/whatsnew/v0.16.1.txt

@@ -7,6 +7,10 @@ This is a minor bug-fix release from 0.16.0 and includes a a large number of
 bug fixes along several new features, enhancements, and performance improvements.
 We recommend that all users upgrade to this version.
 
+Highlights include:
+
+- Support for a ``CategoricalIndex``, a category based index, see :ref:`here <whatsnew_0161`.enhancements.categoricalindex>`
+
 .. contents:: What's new in v0.16.1
     :local:
     :backlinks: none
@@ -17,10 +21,46 @@ We recommend that all users upgrade to this version.
 Enhancements
 ~~~~~~~~~~~~
 
+.. _whatsnew_0161.enhancements.categoricalindex:
+
+CategoricalIndex
+^^^^^^^^^^^^^^^^
+
+We introduce a ``CategoricalIndex``, a new type of index object that is useful for supporting
+indexing with duplicates. This is a container around a ``Categorical`` (introduced in v0.15.0)
+and allows efficient indexing and storage of a index with a larger number of duplicated elements. Prior to 0.16.1,
+setting the index of a ``DataFrame/Series`` with a ``category`` dtype would convert this to regular object-based ``Index``.
+
+.. ipython :: python
+
+   df = DataFrame({'A' : np.arange(6),
+                   'B' : Series(list('aabbca')).astype('category',
+                                                       categories=list('cab'))
+                  })
+   df
+   df.dtypes
+   df.B.cat.categories
+
+   # setting the index, will create create a CategoricalIndex
+   df2 = df.set_index('B')
+   df2.index
+   df2.index.categories
+
+   # indexing works similarly to an Index with duplicates
+   df2.loc['a']
 
+   # and preserves the CategoricalIndex
+   df2.loc['a'].index
+   df2.loc['a'].index.categories
 
+   # sorting will order by the order of the categories
+   df2.sort_index()
 
+   # groupby operations on the index will preserve the index nature as well
+   df2.groupby(level=0).sum()
+   df2.groupby(level=0).sum().index
 
+See the :ref:`documentation <advanced.categoricalindex>` for more. (:issue:`7629`)
 
 .. _whatsnew_0161.api: