class pandas.core.categorical.Categorical(values, categories=None, ordered=None, name=None, fastpath=False, levels=None)

Represents a categorical variable in classic R / S-plus fashion

Categoricals can only take on only a limited, and usually fixed, number of possible values (categories). In contrast to statistical categorical variables, a Categorical might have an order, but numerical operations (additions, divisions, ...) are not possible.

All values of the Categorical are either in categories or np.nan. Assigning values outside of categories will raise a ValueError. Order is defined by the order of the categories, not lexical order of the values.

Parameters :

values : list-like

The values of the categorical. If categories are given, values not in categories will be replaced with NaN.

categories : Index-like (unique), optional

The unique categories for this categorical. If not given, the categories are assumed to be the unique values of values.

ordered : boolean, optional

Whether or not this categorical is treated as a ordered categorical. If not given, the resulting categorical will be ordered if values can be sorted.

name : str, optional

Name for the Categorical variable. If name is None, will attempt to infer from values.

Raises :


If the categories do not validate.


If an explicit ordered=True is given but no categories and the values are not sortable.


>>> from pandas import Categorical
>>> Categorical([1, 2, 3, 1, 2, 3])
[1, 2, 3, 1, 2, 3]
Categories (3, int64): [1 < 2 < 3]
>>> Categorical(['a', 'b', 'c', 'a', 'b', 'c'])
[a, b, c, a, b, c]
Categories (3, object): [a < b < c]
>>> a = Categorical(['a','b','c','a','b','c'], ['c', 'b', 'a'])
>>> a.min()


categories The categories of this categorical.
codes The category codes of this categorical.
ordered (boolean) Whether or not this Categorical is ordered.
name (string) The name of this Categorical.


add_categories(new_categories[, inplace]) Add new categories.
argsort([ascending]) Implements ndarray.argsort.
copy() Copy constructor.
describe() Describes this Categorical
equals(other) Returns True if categorical arrays are equal.
fillna([fill_value, method, limit]) Fill NA/NaN values using the specified method.
from_array(data, **kwargs) Make a Categorical type from a single array-like object.
from_codes(codes, categories[, ordered, name]) Make a Categorical type from codes and categories arrays.
get_values() Return the values.
isnull() Detect missing values
max([numeric_only]) The maximum value of the object.
min([numeric_only]) The minimum value of the object.
mode() Returns the mode(s) of the Categorical.
notnull() Reverse of isnull
order([inplace, ascending, na_position]) Sorts the Category by category value returning a new Categorical by default.
ravel([order]) Return a flattened (numpy) array.
remove_categories(removals[, inplace]) Removes the specified categories.
remove_unused_categories([inplace]) Removes categories which are not used.
rename_categories(new_categories[, inplace]) Renames categories.
reorder_categories(new_categories[, ...]) Reorders categories as specified in new_categories.
reshape(new_shape, **kwargs) compat with .reshape
searchsorted(v[, side, sorter]) Find indices where elements should be inserted to maintain order.
set_categories(new_categories[, ordered, ...]) Sets the categories to the specified new_categories.
sort([inplace, ascending, na_position]) Sorts the Category inplace by category value.
take(indexer[, allow_fill, fill_value]) Take the codes by the indexer, fill with the fill_value.
take_nd(indexer[, allow_fill, fill_value]) Take the codes by the indexer, fill with the fill_value.
to_dense() Return my ‘dense’ representation
unique() Return the unique values.
view() Return a view of myself.