From 23035a09d8036c6eb43dfc5d23103cb8aeb0bcfd Mon Sep 17 00:00:00 2001 From: Kaoboyandy Date: Thu, 22 Mar 2018 20:38:45 +0800 Subject: [PATCH 1/3] DOC: update the pandas.Series.map docstring --- pandas/core/series.py | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 3e3600898ba7f..592904f7605cf 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2831,12 +2831,15 @@ def unstack(self, level=-1, fill_value=None): def map(self, arg, na_action=None): """ - Map values of Series using input correspondence (a dict, Series, or - function). + Map values of Series according to input correspondence. + + Used for substituting each value in a Series with another value, + that may be derived from a function, a ``dict`` or + a :class:`pandas.Series`. Parameters ---------- - arg : function, dict, or Series + arg : function, dict, or Seriess Mapping correspondence. na_action : {None, 'ignore'} If 'ignore', propagate NA values, without passing them to the @@ -2850,7 +2853,7 @@ def map(self, arg, na_action=None): Examples -------- - Map inputs to outputs (both of type `Series`): + Map inputs to outputs (both of type :class:`pandas.Series`): >>> x = pd.Series([1,2,3], index=['one', 'two', 'three']) >>> x @@ -2864,14 +2867,24 @@ def map(self, arg, na_action=None): 1 foo 2 bar 3 baz + dtype: object >>> x.map(y) one foo two bar three baz + dtype: object + + Map a function to a :class:`pandas.Series`. - If `arg` is a dictionary, return a new Series with values converted - according to the dictionary's mapping: + >>> x.map(lambda x: x**2) + one 1 + two 4 + three 9 + dtype: int64 + + If ``arg`` is a dictionary, return a new :class:`pandas.Series` with + values converted according to the dictionary's mapping: >>> z = {1: 'A', 2: 'B', 3: 'C'} @@ -2879,20 +2892,21 @@ def map(self, arg, na_action=None): one A two B three C + dtype: object - Use na_action to control whether NA values are affected by the mapping - function. + Use ``na_action`` to control whether NA values are affected by the + mapping function. >>> s = pd.Series([1, 2, 3, np.nan]) - >>> s2 = s.map('this is a string {}'.format, na_action=None) + >>> s.map('this is a string {}'.format, na_action=None) 0 this is a string 1.0 1 this is a string 2.0 2 this is a string 3.0 3 this is a string nan dtype: object - >>> s3 = s.map('this is a string {}'.format, na_action='ignore') + >>> s.map('this is a string {}'.format, na_action='ignore') 0 this is a string 1.0 1 this is a string 2.0 2 this is a string 3.0 From 9d3b78d98a1327ec45fd6ef449aeb24d8d6686f7 Mon Sep 17 00:00:00 2001 From: Kaoboyandy Date: Thu, 22 Mar 2018 20:41:48 +0800 Subject: [PATCH 2/3] Minor change --- pandas/core/series.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 592904f7605cf..1285ff4d225fe 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2839,7 +2839,7 @@ def map(self, arg, na_action=None): Parameters ---------- - arg : function, dict, or Seriess + arg : function, dict, or Series Mapping correspondence. na_action : {None, 'ignore'} If 'ignore', propagate NA values, without passing them to the From fae8f19e800e3dcbb97372843e6b576560fd937c Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Sat, 18 Aug 2018 22:58:14 +0100 Subject: [PATCH 3/3] Minor changes, and more clear examples --- pandas/core/series.py | 122 ++++++++++++++++-------------------------- 1 file changed, 45 insertions(+), 77 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index c99dbf0482326..2e6270e8739ae 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2955,106 +2955,74 @@ def map(self, arg, na_action=None): Used for substituting each value in a Series with another value, that may be derived from a function, a ``dict`` or - a :class:`pandas.Series`. + a :class:`Series`. Parameters ---------- arg : function, dict, or Series Mapping correspondence. - na_action : {None, 'ignore'} - If 'ignore', propagate NA values, without passing them to the + na_action : {None, 'ignore'}, default None + If 'ignore', propagate NaN values, without passing them to the mapping correspondence. Returns ------- - y : Series + Series Same index as caller. - Examples + 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. - Map inputs to outputs (both of type :class:`pandas.Series`): - - >>> x = pd.Series([1,2,3], index=['one', 'two', 'three']) - >>> x - one 1 - two 2 - three 3 - dtype: int64 - - >>> y = pd.Series(['foo', 'bar', 'baz'], index=[1,2,3]) - >>> y - 1 foo - 2 bar - 3 baz - dtype: object + Notes + ----- + When ``arg`` is a dictionary, values in Series that are not in the + dictionary (as keys) are converted to ``NaN``. However, if the + dictionary is a ``dict`` subclass that defines ``__missing__`` (i.e. + provides a method for default values), then this default is used + rather than ``NaN``. - >>> x.map(y) - one foo - two bar - three baz + Examples + -------- + >>> s = pd.Series(['cat', 'dog', np.nan, 'rabbit']) + >>> s + 0 cat + 1 dog + 2 NaN + 3 rabbit dtype: object - Map a function to a :class:`pandas.Series`. + ``map`` accepts a ``dict`` or a ``Series``. Values that are not found + in the ``dict`` are converted to ``NaN``, unless the dict has a default + value (e.g. ``defaultdict``): - >>> x.map(lambda x: x**2) - one 1 - two 4 - three 9 - dtype: int64 - - If ``arg`` is a dictionary, return a new :class:`pandas.Series` with - values converted according to the dictionary's mapping: - - >>> z = {1: 'A', 2: 'B', 3: 'C'} - - >>> x.map(z) - one A - two B - three C + >>> s.map({'cat': 'kitten', 'dog': 'puppy'}) + 0 kitten + 1 puppy + 2 NaN + 3 NaN dtype: object - Use ``na_action`` to control whether NA values are affected by the - mapping function. - - >>> s = pd.Series([1, 2, 3, np.nan]) + It also accepts a function: - >>> s.map('this is a string {}'.format, na_action=None) - 0 this is a string 1.0 - 1 this is a string 2.0 - 2 this is a string 3.0 - 3 this is a string nan + >>> s.map('I am a {}'.format) + 0 I am a cat + 1 I am a dog + 2 I am a nan + 3 I am a rabbit dtype: object - >>> s.map('this is a string {}'.format, na_action='ignore') - 0 this is a string 1.0 - 1 this is a string 2.0 - 2 this is a string 3.0 - 3 NaN - dtype: object + To avoid applying the function to missing values (and keep them as + ``NaN``) ``na_action='ignore'`` can be used: - 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. - - Notes - ----- - When `arg` is a dictionary, values in Series that are not in the - dictionary (as keys) are converted to ``NaN``. However, if the - dictionary is a ``dict`` subclass that defines ``__missing__`` (i.e. - provides a method for default values), then this default is used - rather than ``NaN``: - - >>> from collections import Counter - >>> counter = Counter() - >>> counter['bar'] += 1 - >>> y.map(counter) - 1 0 - 2 1 - 3 0 - dtype: int64 + >>> s.map('I am a {}'.format, na_action='ignore') + 0 I am a cat + 1 I am a dog + 2 NaN + 3 I am a rabbit + dtype: object """ new_values = super(Series, self)._map_values( arg, na_action=na_action)