Skip to main content
`Ctrl`+`K`

# pandas.CategoricalIndex

class pandas.CategoricalIndex(data=None, categories=None, ordered=None, dtype=None, copy=False, name=None)

  Index based on an underlying `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 (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 “category”, optional

      If `CategoricalDtype`, cannot be used together with categories or ordered.

    copy bool, default False

      Make a copy of input ndarray.

    name object, optional

      Name to be stored in the index.

  Attributes

  `codes` | The category codes of this categorical index.
  `categories` | The categories of this categorical.
  `ordered` | Whether the categories have an ordered relationship.

  Methods

  `rename_categories`(*args, **kwargs) | Rename categories.
  `reorder_categories`(*args, **kwargs) | Reorder categories as specified in new_categories.
  `add_categories`(*args, **kwargs) | Add new categories.
  `remove_categories`(*args, **kwargs) | Remove the specified categories.
  `remove_unused_categories`(*args, **kwargs) | Remove categories which are not used.
  `set_categories`(*args, **kwargs) | Set the categories to the specified new categories.
  `as_ordered`(*args, **kwargs) | Set the Categorical to be ordered.
  `as_unordered`(*args, **kwargs) | Set the Categorical to be unordered.
  `map`(mapper[, na_action]) | Map values using input an input mapping or function.

  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

  `Index`

    The base pandas Index type.

  `Categorical`

    A categorical array.

  `CategoricalDtype`

    Type for categorical data.

  Notes

  See the user guide 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')

  `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')

  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')
      >>> ci.min()
      'c'