Skip to content

DOC: update the pandas.Series.map docstring #20450

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Aug 18, 2018
Merged

DOC: update the pandas.Series.map docstring #20450

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
23035a0
DOC: update the pandas.Series.map docstring
kaoboyandy Mar 22, 2018
9d3b78d
Minor change
kaoboyandy Mar 22, 2018
2ad26ba
Merge remote-tracking branch 'upstream/master' into docstring_map
datapythonista Aug 18, 2018
fae8f19
Minor changes, and more clear examples
datapythonista Aug 18, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 23 additions & 9 deletions pandas/core/series.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2831,8 +2831,11 @@ 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
----------
Expand All @@ -2850,7 +2853,7 @@ def map(self, arg, na_action=None):
Examples
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add a See Also section? I think at least apply and applymap are related. May be the Python map built-in could be linked too?

--------

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'])
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing spaces after comma for PEP-8.

>>> x
Expand All @@ -2864,35 +2867,46 @@ def map(self, arg, na_action=None):
1 foo
2 bar
3 baz
dtype: object
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think these examples would be clearer if instead of foo, bar, one, two... we could find a more real-world example.

Also, I think it should be useful to show the behaviour of map with a dict or Series that doesn't have all the values in the Series.


>>> 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would start by the example using a function as a parameter, which I think it's a more common use than with a series.


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)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As z is not very descriptive, I'd use the dictionary directly as a parameter, and avoid saving it to a variable.

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
Expand Down