From 4c6d29e346891b4edcd57f77aee186d32e33803b Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Sat, 10 Mar 2018 14:15:34 +0100 Subject: [PATCH 01/18] Applied docstring convention. --- pandas/core/arrays/categorical.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index e23dc3b3e5b89..20f644ba0a9e3 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -1081,7 +1081,8 @@ def remove_unused_categories(self, inplace=False): return cat def map(self, mapper): - """Apply mapper function to its categories (not codes). + """ + Apply mapper function to its categories (not codes). Parameters ---------- From a2bf1c25ebcf25a9b52e3d9ee6387769ec4f6fcb Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Sat, 10 Mar 2018 15:18:30 +0100 Subject: [PATCH 02/18] Improve Series.map docstring plus conventions. --- pandas/core/series.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 069f0372ab6e1..22e06f980692e 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2242,25 +2242,26 @@ def unstack(self, level=-1, fill_value=None): def map(self, arg, na_action=None): """ - Map values of Series using input correspondence (which can be - a dict, Series, or function) + Map values of Series using input correspondence (a dict, Series, or + function). Parameters ---------- arg : function, dict, or Series + Mapping correspondence. na_action : {None, 'ignore'} If 'ignore', propagate NA values, without passing them to the - mapping function + mapping correspondence. Returns ------- y : Series - same index as caller + Same index as caller. Examples -------- - Map inputs to outputs (both of type `Series`) + Map inputs to outputs (both of type `Series`): >>> x = pd.Series([1,2,3], index=['one', 'two', 'three']) >>> x From bf0b870a252a442da0854d93ce5c397e2dda5d70 Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Sat, 10 Mar 2018 15:23:42 +0100 Subject: [PATCH 03/18] Improved Index.map docstring. --- pandas/core/indexes/base.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 7e6ae88a26e7c..0b80f916234ec 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -3063,14 +3063,16 @@ def groupby(self, values): return result def map(self, mapper, na_action=None): - """Map values of Series using input correspondence + """ + Map values using input correspondence (a dict, Series, or function). Parameters ---------- mapper : function, dict, or Series + Mapping correspondence. na_action : {None, 'ignore'} If 'ignore', propagate NA values, without passing them to the - mapping function + mapping correspondence. Returns ------- From dba4d1febc5e87ff572aa174858bb14b03dd8cb2 Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Sat, 10 Mar 2018 15:31:08 +0100 Subject: [PATCH 04/18] Docstring convention. --- pandas/core/series.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 22e06f980692e..e09ad2bb63245 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2312,9 +2312,9 @@ def map(self, arg, na_action=None): See Also -------- - Series.apply: For applying more complex functions on a Series - DataFrame.apply: Apply a function row-/column-wise - DataFrame.applymap: Apply a function elementwise on a whole DataFrame + Series.apply : For applying more complex functions on a Series + DataFrame.apply : Apply a function row-/column-wise + DataFrame.applymap : Apply a function elementwise on a whole DataFrame Notes ----- From d13f83c3661fc6e2463d6e5b36c7a1077dd1f4aa Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Sat, 10 Mar 2018 15:34:45 +0100 Subject: [PATCH 05/18] Docstring convention. --- pandas/core/series.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index e09ad2bb63245..9def0e8d07735 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2312,9 +2312,9 @@ def map(self, arg, na_action=None): See Also -------- - Series.apply : For applying more complex functions on a Series - DataFrame.apply : Apply a function row-/column-wise - DataFrame.applymap : Apply a function elementwise on a whole DataFrame + Series.apply : For applying more complex functions on a Series. + DataFrame.apply : Apply a function row-/column-wise. + DataFrame.applymap : Apply a function elementwise on a whole DataFrame. Notes ----- From 9366e39ae18f886431a47ef6993c0987f73561ce Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Sat, 10 Mar 2018 15:43:02 +0100 Subject: [PATCH 06/18] Improve the CategoricalIndex.map docstring. --- pandas/core/indexes/category.py | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index 218851b1713f2..c3d24d8913712 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -661,20 +661,33 @@ def is_dtype_equal(self, other): take_nd = take def map(self, mapper): - """Apply mapper function to its categories (not codes). + """ + Map categories (not codes) using input correspondence (a dict, + Series, or function). + + Maps the categories of the index to new categories. If the mapping + correspondence maps each original category to a different new category + the result is a CategoricalIndex which has the same order property as + the original, otherwise an Index is returned. + + If a dictionary or Series is used and any unmapped category is mapped + to NA. Note that if this happens an Index will be returned. Parameters ---------- mapper : callable - Function to be applied. When all categories are mapped - to different categories, the result will be a CategoricalIndex - which has the same order property as the original. Otherwise, - the result will be a Index. + Function to be applied. Returns ------- applied : CategoricalIndex or Index + See Also + -------- + Index.map : For applying a mapping correspondence on an Index. + Series.map : For applying a mapping correspondence on a Series. + Series.apply : For applying more complex functions on a Series. + """ return self._shallow_copy_with_infer(self.values.map(mapper)) From e42fd0c960742961e6f32886807aac2208a5dcc7 Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Sat, 10 Mar 2018 15:49:27 +0100 Subject: [PATCH 07/18] Docstring convention. --- pandas/core/indexes/category.py | 1 - 1 file changed, 1 deletion(-) diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index c3d24d8913712..6bfaa02ef3410 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -687,7 +687,6 @@ def map(self, mapper): Index.map : For applying a mapping correspondence on an Index. Series.map : For applying a mapping correspondence on a Series. Series.apply : For applying more complex functions on a Series. - """ return self._shallow_copy_with_infer(self.values.map(mapper)) From 8240278e4f930dace796098fe2e565d170440a24 Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Sat, 10 Mar 2018 15:50:07 +0100 Subject: [PATCH 08/18] Docstring convention. --- pandas/core/indexes/base.py | 1 - 1 file changed, 1 deletion(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 0b80f916234ec..8a8d94919c514 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -3080,7 +3080,6 @@ def map(self, mapper, na_action=None): The output of the mapping function applied to the index. If the function returns a tuple with more than one element a MultiIndex will be returned. - """ from .multi import MultiIndex From 90876777165460794ba98c5f47b6fbc91a66c7e9 Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Sat, 10 Mar 2018 16:00:17 +0100 Subject: [PATCH 09/18] Improve Categorical.map docstring. --- pandas/core/arrays/categorical.py | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index 20f644ba0a9e3..61b7bf84da308 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -1082,20 +1082,25 @@ def remove_unused_categories(self, inplace=False): def map(self, mapper): """ - Apply mapper function to its categories (not codes). + Map categories (not codes) using input correspondence (a dict, + Series, or function). + + Maps the categories to new categories. If the mapping + correspondence maps each original category to a different new category + the result is a Categorical which has the same order property as + the original, otherwise an np.ndarray is returned. + + If a dictionary or Series is used and any unmapped category is mapped + to NA. Note that if this happens an np.ndarray will be returned. Parameters ---------- mapper : callable - Function to be applied. When all categories are mapped - to different categories, the result will be Categorical which has - the same order property as the original. Otherwise, the result will - be np.ndarray. + Function to be applied. Returns ------- applied : Categorical or Index. - """ new_categories = self.categories.map(mapper) try: From da84d5fc3b2697a26b42b72e58a382fe0aad46aa Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Sat, 10 Mar 2018 16:03:32 +0100 Subject: [PATCH 10/18] Improve CategoricalIndex.map docstring. --- pandas/core/indexes/category.py | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index 6bfaa02ef3410..3f9b35ece05df 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -662,21 +662,22 @@ def is_dtype_equal(self, other): def map(self, mapper): """ - Map categories (not codes) using input correspondence (a dict, - Series, or function). + Map index values using input correspondence (a dict, Series, or + function). - Maps the categories of the index to new categories. If the mapping - correspondence maps each original category to a different new category - the result is a CategoricalIndex which has the same order property as - the original, otherwise an Index is returned. + Maps the values (their categories, not the codes) of the index to new + categories. If the mapping correspondence maps each original category + to a different new category the result is a CategoricalIndex which has + the same order property as the original, otherwise an Index is + returned. If a dictionary or Series is used and any unmapped category is mapped to NA. Note that if this happens an Index will be returned. Parameters ---------- - mapper : callable - Function to be applied. + mapper : function, dict, or Series + Mapping correspondence. Returns ------- From 848d960557cd194b63db5969ed909e5d08ccd673 Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Sat, 10 Mar 2018 16:42:23 +0100 Subject: [PATCH 11/18] Improved CategoricalIndex.map and Categorical.map docstrings. --- pandas/core/arrays/categorical.py | 4 ++-- pandas/core/indexes/category.py | 13 +++++++------ 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index 61b7bf84da308..597f61de78836 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -1090,8 +1090,8 @@ def map(self, mapper): the result is a Categorical which has the same order property as the original, otherwise an np.ndarray is returned. - If a dictionary or Series is used and any unmapped category is mapped - to NA. Note that if this happens an np.ndarray will be returned. + If a dictionary or Series is used any unmapped category is mapped to + NA. Note that if this happens an np.ndarray will be returned. Parameters ---------- diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index 3f9b35ece05df..3d1460c9d6aab 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -671,8 +671,8 @@ def map(self, mapper): the same order property as the original, otherwise an Index is returned. - If a dictionary or Series is used and any unmapped category is mapped - to NA. Note that if this happens an Index will be returned. + If a dictionary or Series is used any unmapped category is mapped to + NA. Note that if this happens an Index will be returned. Parameters ---------- @@ -681,13 +681,14 @@ def map(self, mapper): Returns ------- - applied : CategoricalIndex or Index + CategoricalIndex or Index + Mapped index. See Also -------- - Index.map : For applying a mapping correspondence on an Index. - Series.map : For applying a mapping correspondence on a Series. - Series.apply : For applying more complex functions on a Series. + Index.map : Apply a mapping correspondence on an Index. + Series.map : Apply a mapping correspondence on a Series. + Series.apply : Apply more complex functions on a Series. """ return self._shallow_copy_with_infer(self.values.map(mapper)) From 2af44df9f0cfbe5ce2459fe0ef3ce9beaccf916e Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Sat, 10 Mar 2018 17:06:02 +0100 Subject: [PATCH 12/18] Improved CategoricalIndex.map docstring. --- pandas/core/indexes/category.py | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index 3d1460c9d6aab..25c2723623c11 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -689,6 +689,26 @@ def map(self, mapper): Index.map : Apply a mapping correspondence on an Index. Series.map : Apply a mapping correspondence on a Series. Series.apply : Apply more complex functions on a Series. + + Examples + -------- + >>> idx = pd.CategoricalIndex(['a', 'b', 'c']) + >>> idx + CategoricalIndex(['a', 'b', 'c'], categories=['a', 'b', 'c'], + ordered=False, dtype='category') + >>> idx.map(lambda x: x.upper()) + CategoricalIndex(['A', 'B', 'C'], categories=['A', 'B', 'C'], + ordered=False, dtype='category') + >>> idx.map({'a': 'first', 'b': 'second', 'c': 'third'}) + CategoricalIndex(['first', 'second', 'third'], categories=['first', + 'second', 'third'], ordered=False, dtype='category') + + If a dictionary is used, if even a single category is not mapped by the + dictionary, the unmapped category is mapped to NA and the result is an + Index: + + >>> idx.map({'a': 'first', 'b': 'second'}) + Index(['first', 'second', nan], dtype='object') """ return self._shallow_copy_with_infer(self.values.map(mapper)) From 1ad38e9ed127611b277705ecf81f8773ea1428c6 Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Sat, 10 Mar 2018 17:22:31 +0100 Subject: [PATCH 13/18] Final version, pandas docstring convention compliant. --- pandas/core/indexes/category.py | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index 25c2723623c11..bbd8072ab1efc 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -703,9 +703,12 @@ def map(self, mapper): CategoricalIndex(['first', 'second', 'third'], categories=['first', 'second', 'third'], ordered=False, dtype='category') - If a dictionary is used, if even a single category is not mapped by the - dictionary, the unmapped category is mapped to NA and the result is an - Index: + If the mapping is not bijective an Index is returned: + >>> idx.map({'a': 'first', 'b': 'second', 'c': 'first'}) + Index(['first', 'second', 'first'], dtype='object') + + If a dictionary is used, all unmapped categories are mapped to NA and + the result is an Index: >>> idx.map({'a': 'first', 'b': 'second'}) Index(['first', 'second', nan], dtype='object') From 1a8040d6d2518e37b372144bfffa90ffde394921 Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Sun, 11 Mar 2018 16:38:30 +0100 Subject: [PATCH 14/18] Bug fix in docstring. --- pandas/core/indexes/category.py | 1 + 1 file changed, 1 insertion(+) diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index bbd8072ab1efc..37bbb1ce2d1d7 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -704,6 +704,7 @@ def map(self, mapper): 'second', 'third'], ordered=False, dtype='category') If the mapping is not bijective an Index is returned: + >>> idx.map({'a': 'first', 'b': 'second', 'c': 'first'}) Index(['first', 'second', 'first'], dtype='object') From 986e1ddea7743d731072d19e54cbdc5bf939a7d4 Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Sat, 17 Mar 2018 23:10:29 +0100 Subject: [PATCH 15/18] DOC: Improved CategoricalIndex.map and Categorical.map docstrings. --- pandas/core/arrays/categorical.py | 59 +++++++++++++++++++++++++------ pandas/core/indexes/category.py | 33 +++++++++-------- 2 files changed, 66 insertions(+), 26 deletions(-) diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index 597f61de78836..a65637c04818d 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -1082,25 +1082,62 @@ def remove_unused_categories(self, inplace=False): def map(self, mapper): """ - Map categories (not codes) using input correspondence (a dict, - Series, or function). + Map categories using input correspondence (dict, Series, or function). - Maps the categories to new categories. If the mapping - correspondence maps each original category to a different new category - the result is a Categorical which has the same order property as - the original, otherwise an np.ndarray is returned. + Maps the categories to new categories. If the mapping correspondence is + a bijection (maps each original category to a different new category) + the result is a :class:`~pandas.Categorical` which has the same order + property as the original, otherwise a :class:`~pandas.Index` is + returned. - If a dictionary or Series is used any unmapped category is mapped to - NA. Note that if this happens an np.ndarray will be returned. + If a `dict` or :class:`~pandas.Series` is used any unmapped category is + mapped to NaN. Note that if this happens an :class:`~pandas.Index` will + be returned. Parameters ---------- - mapper : callable - Function to be applied. + mapper : function, dict, or Series + Mapping correspondence. Returns ------- - applied : Categorical or Index. + pandas.Categorical or pandas.Index + Mapped categorical. + + See Also + -------- + CategoricalIndex.map : Apply a mapping correspondence on a + :class:`~pandas.CategoricalIndex`. + Index.map : Apply a mapping correspondence on an + :class:`~pandas.Index`. + Series.map : Apply a mapping correspondence on a + :class:`~pandas.Series`. + Series.apply : Apply more complex functions on a + :class:`~pandas.Series`. + + Examples + -------- + >>> cat = pd.Categorical(['a', 'b', 'c']) + >>> cat + [a, b, c] + Categories (3, object): [a, b, c] + >>> cat.map(lambda x: x.upper()) + [A, B, C] + Categories (3, object): [A, B, C] + >>> cat.map({'a': 'first', 'b': 'second', 'c': 'third'}) + [first, second, third] + Categories (3, object): [first, second, third] + + If the mapping is not bijective an :class:`~pandas.Index~ is returned: + + >>> cat.map({'a': 'first', 'b': 'second', 'c': 'first'}) + Index(['first', 'second', 'first'], dtype='object') + + If a `dict` is used, all unmapped categories are mapped to NA and + the result is an :class:`~pandas.Index`: + + >>> idx.map({'a': 'first', 'b': 'second'}) + Index(['first', 'second', nan], dtype='object') """ new_categories = self.categories.map(mapper) try: diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index f7072369c95b0..260e25f40714c 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -662,17 +662,17 @@ def is_dtype_equal(self, other): def map(self, mapper): """ - Map index values using input correspondence (a dict, Series, or - function). + Map values using input correspondence (a dict, Series, or function). Maps the values (their categories, not the codes) of the index to new - categories. If the mapping correspondence maps each original category - to a different new category the result is a CategoricalIndex which has - the same order property as the original, otherwise an Index is - returned. + categories. If the mapping correspondence is a bijection (maps each + original category to a different new category) the result is a + :class:`~pandas.CategoricalIndex` which has the same order property as + the original, otherwise an :class:`~pandas.Index` is returned. - If a dictionary or Series is used any unmapped category is mapped to - NA. Note that if this happens an Index will be returned. + If a `dict` or :class:`~pandas.Series` is used any unmapped category is + mapped to NaN. Note that if this happens an :class:`~pandas.Index` will + be returned. Parameters ---------- @@ -681,14 +681,17 @@ def map(self, mapper): Returns ------- - CategoricalIndex or Index + pandas.CategoricalIndex or pandas.Index Mapped index. See Also -------- - Index.map : Apply a mapping correspondence on an Index. - Series.map : Apply a mapping correspondence on a Series. - Series.apply : Apply more complex functions on a Series. + Index.map : Apply a mapping correspondence on an + :class:`~pandas.Index`. + Series.map : Apply a mapping correspondence on a + :class:`~pandas.Series`. + Series.apply : Apply more complex functions on a + :class:`~pandas.Series`. Examples -------- @@ -703,13 +706,13 @@ def map(self, mapper): CategoricalIndex(['first', 'second', 'third'], categories=['first', 'second', 'third'], ordered=False, dtype='category') - If the mapping is not bijective an Index is returned: + If the mapping is not bijective an :class:`~pandas.Index~ is returned: >>> idx.map({'a': 'first', 'b': 'second', 'c': 'first'}) Index(['first', 'second', 'first'], dtype='object') - If a dictionary is used, all unmapped categories are mapped to NA and - the result is an Index: + If a `dict` is used, all unmapped categories are mapped to NA and + the result is an :class:`~pandas.Index`: >>> idx.map({'a': 'first', 'b': 'second'}) Index(['first', 'second', nan], dtype='object') From 0fc2c480142a35dd2ae14a09ee2bff8d1091e7c4 Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Sat, 17 Mar 2018 23:21:55 +0100 Subject: [PATCH 16/18] DOC: Bugfix. --- pandas/core/arrays/categorical.py | 8 ++++---- pandas/core/indexes/category.py | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index a65637c04818d..52ad5734a10de 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -1107,7 +1107,7 @@ def map(self, mapper): See Also -------- CategoricalIndex.map : Apply a mapping correspondence on a - :class:`~pandas.CategoricalIndex`. + :class:`~pandas.CategoricalIndex`. Index.map : Apply a mapping correspondence on an :class:`~pandas.Index`. Series.map : Apply a mapping correspondence on a @@ -1128,15 +1128,15 @@ def map(self, mapper): [first, second, third] Categories (3, object): [first, second, third] - If the mapping is not bijective an :class:`~pandas.Index~ is returned: + If the mapping is not bijective an :class:`~pandas.Index` is returned: >>> cat.map({'a': 'first', 'b': 'second', 'c': 'first'}) Index(['first', 'second', 'first'], dtype='object') - If a `dict` is used, all unmapped categories are mapped to NA and + If a `dict` is used, all unmapped categories are mapped to NaN and the result is an :class:`~pandas.Index`: - >>> idx.map({'a': 'first', 'b': 'second'}) + >>> cat.map({'a': 'first', 'b': 'second'}) Index(['first', 'second', nan], dtype='object') """ new_categories = self.categories.map(mapper) diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index 260e25f40714c..3049762ffc26b 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -706,12 +706,12 @@ def map(self, mapper): CategoricalIndex(['first', 'second', 'third'], categories=['first', 'second', 'third'], ordered=False, dtype='category') - If the mapping is not bijective an :class:`~pandas.Index~ is returned: + If the mapping is not bijective an :class:`~pandas.Index` is returned: >>> idx.map({'a': 'first', 'b': 'second', 'c': 'first'}) Index(['first', 'second', 'first'], dtype='object') - If a `dict` is used, all unmapped categories are mapped to NA and + If a `dict` is used, all unmapped categories are mapped to NaN and the result is an :class:`~pandas.Index`: >>> idx.map({'a': 'first', 'b': 'second'}) From a76a4b52f47a22fef239aec2eda9c5841fe0dfee Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Tue, 20 Mar 2018 23:12:06 +0100 Subject: [PATCH 17/18] DOC: Added examples to Categorical.map and CategoricalIndex.map docs. --- pandas/core/arrays/categorical.py | 20 +++++++++++++++----- pandas/core/indexes/category.py | 16 +++++++++++++--- 2 files changed, 28 insertions(+), 8 deletions(-) diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index 19a53d4f3d61c..29cce442dfc08 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -1084,10 +1084,10 @@ def map(self, mapper): Map categories using input correspondence (dict, Series, or function). Maps the categories to new categories. If the mapping correspondence is - a bijection (maps each original category to a different new category) - the result is a :class:`~pandas.Categorical` which has the same order - property as the original, otherwise a :class:`~pandas.Index` is - returned. + a one-to-one mapping (maps each original category to a different new + category) the result is a :class:`~pandas.Categorical` which has the + same order property as the original, otherwise a :class:`~pandas.Index` + is returned. If a `dict` or :class:`~pandas.Series` is used any unmapped category is mapped to NaN. Note that if this happens an :class:`~pandas.Index` will @@ -1127,7 +1127,17 @@ def map(self, mapper): [first, second, third] Categories (3, object): [first, second, third] - If the mapping is not bijective an :class:`~pandas.Index` is returned: + The ordering of the categories is preserved by the map: + + >>> cat = pd.Categorical(['a', 'b', 'c'], ordered=True) + >>> cat + [a, b, c] + Categories (3, object): [a < b < c] + >>> cat.map({'a': 3, 'b': 2, 'c': 1}) + [3, 2, 1] + Categories (3, int64): [3 < 2 < 1] + + If the mapping is not one-to-one an :class:`~pandas.Index` is returned: >>> cat.map({'a': 'first', 'b': 'second', 'c': 'first'}) Index(['first', 'second', 'first'], dtype='object') diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index ea7bd07a9ffda..6950b5865ded5 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -664,8 +664,8 @@ def map(self, mapper): Map values using input correspondence (a dict, Series, or function). Maps the values (their categories, not the codes) of the index to new - categories. If the mapping correspondence is a bijection (maps each - original category to a different new category) the result is a + categories. If the mapping correspondence is a one-to-one mapping (maps + each original category to a different new category) the result is a :class:`~pandas.CategoricalIndex` which has the same order property as the original, otherwise an :class:`~pandas.Index` is returned. @@ -705,7 +705,17 @@ def map(self, mapper): CategoricalIndex(['first', 'second', 'third'], categories=['first', 'second', 'third'], ordered=False, dtype='category') - If the mapping is not bijective an :class:`~pandas.Index` is returned: + The ordering of the categories is preserved by the map: + + >>> idx = pd.CategoricalIndex(['a', 'b', 'c'], ordered=True) + >>> idx + CategoricalIndex(['a', 'b', 'c'], categories=['a', 'b', 'c'], + ordered=True, dtype='category') + >>> idx.map({'a': 3, 'b': 2, 'c': 1}) + CategoricalIndex([3, 2, 1], categories=[3, 2, 1], ordered=True, + dtype='category') + + If the mapping is not one-to-one an :class:`~pandas.Index` is returned: >>> idx.map({'a': 'first', 'b': 'second', 'c': 'first'}) Index(['first', 'second', 'first'], dtype='object') From ecbaca0dbdd2d2d743c10c523b72ea9935f6ad26 Mon Sep 17 00:00:00 2001 From: Lorenzo De Leo Date: Wed, 21 Mar 2018 22:25:01 +0100 Subject: [PATCH 18/18] DOC: Improved Categorical.map and CategoricalIndex.map. --- pandas/core/arrays/categorical.py | 12 ++++++------ pandas/core/indexes/category.py | 12 ++++++------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index 29cce442dfc08..afbf4baf0d002 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -1084,14 +1084,13 @@ def map(self, mapper): Map categories using input correspondence (dict, Series, or function). Maps the categories to new categories. If the mapping correspondence is - a one-to-one mapping (maps each original category to a different new - category) the result is a :class:`~pandas.Categorical` which has the + one-to-one the result is a :class:`~pandas.Categorical` which has the same order property as the original, otherwise a :class:`~pandas.Index` is returned. If a `dict` or :class:`~pandas.Series` is used any unmapped category is - mapped to NaN. Note that if this happens an :class:`~pandas.Index` will - be returned. + mapped to `NaN`. Note that if this happens an :class:`~pandas.Index` + will be returned. Parameters ---------- @@ -1127,7 +1126,8 @@ def map(self, mapper): [first, second, third] Categories (3, object): [first, second, third] - The ordering of the categories is preserved by the map: + If the mapping is one-to-one the ordering of the categories is + preserved: >>> cat = pd.Categorical(['a', 'b', 'c'], ordered=True) >>> cat @@ -1142,7 +1142,7 @@ def map(self, mapper): >>> cat.map({'a': 'first', 'b': 'second', 'c': 'first'}) Index(['first', 'second', 'first'], dtype='object') - If a `dict` is used, all unmapped categories are mapped to NaN and + If a `dict` is used, all unmapped categories are mapped to `NaN` and the result is an :class:`~pandas.Index`: >>> cat.map({'a': 'first', 'b': 'second'}) diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index 6950b5865ded5..71caa098c7a28 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -664,14 +664,13 @@ def map(self, mapper): Map values using input correspondence (a dict, Series, or function). Maps the values (their categories, not the codes) of the index to new - categories. If the mapping correspondence is a one-to-one mapping (maps - each original category to a different new category) the result is a + categories. If the mapping correspondence is one-to-one the result is a :class:`~pandas.CategoricalIndex` which has the same order property as the original, otherwise an :class:`~pandas.Index` is returned. If a `dict` or :class:`~pandas.Series` is used any unmapped category is - mapped to NaN. Note that if this happens an :class:`~pandas.Index` will - be returned. + mapped to `NaN`. Note that if this happens an :class:`~pandas.Index` + will be returned. Parameters ---------- @@ -705,7 +704,8 @@ def map(self, mapper): CategoricalIndex(['first', 'second', 'third'], categories=['first', 'second', 'third'], ordered=False, dtype='category') - The ordering of the categories is preserved by the map: + If the mapping is one-to-one the ordering of the categories is + preserved: >>> idx = pd.CategoricalIndex(['a', 'b', 'c'], ordered=True) >>> idx @@ -720,7 +720,7 @@ def map(self, mapper): >>> idx.map({'a': 'first', 'b': 'second', 'c': 'first'}) Index(['first', 'second', 'first'], dtype='object') - If a `dict` is used, all unmapped categories are mapped to NaN and + If a `dict` is used, all unmapped categories are mapped to `NaN` and the result is an :class:`~pandas.Index`: >>> idx.map({'a': 'first', 'b': 'second'})