DOC: CategoricalIndex doc string (#24852)

Author: topper-123

pandas/core/indexes/category.py

@@ -42,20 +42,35 @@
  typ='method', overwrite=True)
 class CategoricalIndex(Index, accessor.PandasDelegate):
  """
- Immutable Index implementing an ordered, sliceable set. CategoricalIndex
- represents a sparsely populated Index with an underlying Categorical.
+ Index based on an underlying :class:`Categorical`.
+
+ CategoricalIndex, like Categorical, can only take on a limited,
+ and usually fixed, number of possible values (`categories`). Also,
+ like Categorical, it might have an order, but numerical operations
+ (additions, divisions, ...) are not possible.
 
  Parameters
  ----------
- data : array-like or Categorical, (1-dimensional)
- categories : optional, array-like
- categories for the CategoricalIndex
- ordered : boolean,
- designating if the categories are ordered
- copy : bool
- Make a copy of input ndarray
- name : object
- Name to be stored in the index
+ data : array-like (1-dimensional)
+ The values of the categorical. If `categories` are given, values not in
+ `categories` will be replaced with NaN.
+ categories : index-like, optional
+ The categories for the categorical. Items need to be unique.
+ If the categories are not given here (and also not in `dtype`), they
+ will be inferred from the `data`.
+ ordered : bool, optional
+ Whether or not this categorical is treated as an ordered
+ categorical. If not given here or in `dtype`, the resulting
+ categorical will be unordered.
+ dtype : CategoricalDtype or the string "category", optional
+ If :class:`CategoricalDtype`, cannot be used together with
+ `categories` or `ordered`.
+
+ .. versionadded:: 0.21.0
+ copy : bool, default False
+ Make a copy of input ndarray.
+ name : object, optional
+ Name to be stored in the index.
 
  Attributes
  ----------
@@ -75,9 +90,45 @@ class CategoricalIndex(Index, accessor.PandasDelegate):
  as_unordered
  map
 
+ Raises
+ ------
+ ValueError
+ If the categories do not validate.
+ TypeError
+ If an explicit ``ordered=True`` is given but no `categories` and the
+ `values` are not sortable.
+
  See Also
  --------
- Categorical, Index
+ Index : The base pandas Index type.
+ Categorical : A categorical array.
+ CategoricalDtype : Type for categorical data.
+
+ Notes
+ -----
+ See the `user guide
+ <http://pandas.pydata.org/pandas-docs/stable/user_guide/advanced.html#categoricalindex>`_
+ for more.
+
+ Examples
+ --------
+ >>> pd.CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'])
+ CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'], categories=['a', 'b', 'c'], ordered=False, dtype='category') # noqa
+
+ ``CategoricalIndex`` can also be instantiated from a ``Categorical``:
+
+ >>> c = pd.Categorical(['a', 'b', 'c', 'a', 'b', 'c'])
+ >>> pd.CategoricalIndex(c)
+ CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'], categories=['a', 'b', 'c'], ordered=False, dtype='category') # noqa
+
+ Ordered ``CategoricalIndex`` can have a min and max value.
+
+ >>> ci = pd.CategoricalIndex(['a','b','c','a','b','c'], ordered=True,
+ ... categories=['c', 'b', 'a'])
+ >>> ci
+ CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'], categories=['c', 'b', 'a'], ordered=True, dtype='category') # noqa
+ >>> ci.min()
+ 'c'
  """
 
  _typ = 'categoricalindex'