From 178040e5889771c156afe349943e9687d2d9aeb2 Mon Sep 17 00:00:00 2001 From: tp Date: Sun, 20 Jan 2019 23:18:50 +0000 Subject: [PATCH 1/4] DOC: CategoricalIndex doc string --- pandas/core/indexes/category.py | 75 ++++++++++++++++++++++++++++----- 1 file changed, 65 insertions(+), 10 deletions(-) diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index e43b64827d02a..541dbd88cb5c9 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -42,19 +42,36 @@ 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. + Immutable index implementing an ordered, sliceable set. CategoricalIndex + represents a sparsely populated index with 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 + data : list-like + 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, then they must be provided + in `dtype`. + 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 + name : object, optional Name to be stored in the index Attributes @@ -62,6 +79,7 @@ class CategoricalIndex(Index, accessor.PandasDelegate): codes categories ordered + dtype Methods ------- @@ -75,9 +93,46 @@ 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 variable in classic R / S-plus fashion + 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') # 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 be sorted according to the custom order + of the categories and 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' From 77de1da75ee2bbf306eecfe8c9896535bfc915cb Mon Sep 17 00:00:00 2001 From: tp Date: Mon, 21 Jan 2019 10:51:25 +0000 Subject: [PATCH 2/4] Some fixes to doc string --- pandas/core/indexes/category.py | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index 541dbd88cb5c9..af7dfefde6470 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -42,9 +42,7 @@ 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 - :class:`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, @@ -70,9 +68,9 @@ class CategoricalIndex(Index, accessor.PandasDelegate): .. versionadded:: 0.21.0 copy : bool, default False - Make a copy of input ndarray + Make a copy of input ndarray. name : object, optional - Name to be stored in the index + Name to be stored in the index. Attributes ---------- @@ -103,9 +101,9 @@ class CategoricalIndex(Index, accessor.PandasDelegate): See Also -------- - Index : The base pandas Index type - Categorical : A categorical variable in classic R / S-plus fashion - CategoricalDtype : Type for categorical data + Index : The base pandas Index type. + Categorical : A categorical variable in classic R / S-plus fashion. + CategoricalDtype : Type for categorical data. Notes ----- From db97ee2c1471b6ed8e7a1e102ea52a28bebbe125 Mon Sep 17 00:00:00 2001 From: tp Date: Mon, 21 Jan 2019 22:38:54 +0000 Subject: [PATCH 3/4] Some fixes to doc string II --- pandas/core/indexes/category.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index af7dfefde6470..80ee67ba0ab29 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -62,7 +62,7 @@ class CategoricalIndex(Index, accessor.PandasDelegate): 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 + dtype : CategoricalDtype or the str "category", optional If :class:`CategoricalDtype`, cannot be used together with `categories` or `ordered`. From c2be1505747e18371b29fe7ce0c15e398b8422f2 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Tue, 19 Feb 2019 09:40:05 +0100 Subject: [PATCH 4/4] fixups --- pandas/core/indexes/category.py | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index 80ee67ba0ab29..1c4446c0a183e 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -44,25 +44,25 @@ class CategoricalIndex(Index, accessor.PandasDelegate): """ Index based on an underlying :class:`Categorical`. - `CategoricalIndex`, like `Categorical` can only take on a limited, + 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 + like Categorical, it might have an order, but numerical operations (additions, divisions, ...) are not possible. Parameters ---------- - data : list-like - The values of the categorical. If categories are given, values not in - categories will be replaced with NaN. + 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, then they must be provided - in `dtype`. + 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 str "category", optional + dtype : CategoricalDtype or the string "category", optional If :class:`CategoricalDtype`, cannot be used together with `categories` or `ordered`. @@ -77,7 +77,6 @@ class CategoricalIndex(Index, accessor.PandasDelegate): codes categories ordered - dtype Methods ------- @@ -102,13 +101,13 @@ class CategoricalIndex(Index, accessor.PandasDelegate): See Also -------- Index : The base pandas Index type. - Categorical : A categorical variable in classic R / S-plus fashion. + Categorical : A categorical array. CategoricalDtype : Type for categorical data. Notes ----- See the `user guide - `_ + `_ for more. Examples @@ -122,8 +121,7 @@ class CategoricalIndex(Index, accessor.PandasDelegate): >>> pd.CategoricalIndex(c) CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'], categories=['a', 'b', 'c'], ordered=False, dtype='category') # noqa - Ordered `CategoricalIndex` can be sorted according to the custom order - of the categories and can have a min and max value. + Ordered ``CategoricalIndex`` can have a min and max value. >>> ci = pd.CategoricalIndex(['a','b','c','a','b','c'], ordered=True, ... categories=['c', 'b', 'a'])