DOC: update the pandas.Series.map docstring

[kaoboyandy]

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

• PR title is "DOC: update the docstring"
• The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
• The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
• The html version looks good: python doc/make.py --single <your-function-or-method>
• It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

################################################################################
######################## Docstring (pandas.Series.map)  ########################
################################################################################

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 Seriess
    Mapping correspondence.
na_action : {None, 'ignore'}
    If 'ignore', propagate NA values, without passing them to the
    mapping correspondence.

Returns
-------
y : Series
    Same index as caller.

Examples
--------

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

>>> x.map(y)
one   foo
two   bar
three baz
dtype: object

Map a function to a :class:`pandas.Series`.

>>> 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
dtype: object

Use ``na_action`` to control whether NA values are affected by the
mapping function.

>>> s = pd.Series([1, 2, 3, np.nan])

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

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

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

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.Series.map" correct. :)

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):

• closes #xxxx
• tests added / passed
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

[codecov]

Codecov Report

Merging #20450 into master will decrease coverage by 0.27%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #20450      +/-   ##
==========================================
- Coverage   92.05%   91.77%   -0.28%     
==========================================
  Files         169      152      -17     
  Lines       50713    49216    -1497     
==========================================
- Hits        46683    45170    -1513     
- Misses       4030     4046      +16

Flag	Coverage Δ
#multiple	90.16% <ø> (-0.3%)	⬇️
#single	41.84% <ø> (-0.41%)	⬇️

Impacted Files	Coverage Δ
pandas/core/series.py	93.84% <ø> (+0.11%)	⬆️
pandas/io/s3.py	72.72% <0%> (-13.64%)	⬇️
pandas/util/_doctools.py	0% <0%> (-12.88%)	⬇️
pandas/core/reshape/util.py	90.32% <0%> (-9.68%)	⬇️
pandas/util/_decorators.py	82.4% <0%> (-8.95%)	⬇️
pandas/core/arrays/base.py	80.64% <0%> (-7.22%)	⬇️
pandas/core/common.py	92.04% <0%> (-5.3%)	⬇️
pandas/io/formats/terminal.py	16.43% <0%> (-4.82%)	⬇️
pandas/io/formats/printing.py	89.38% <0%> (-3.71%)	⬇️
pandas/core/dtypes/missing.py	91.07% <0%> (-1.92%)	⬇️
... and 104 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 92dcf5f...fae8f19. Read the comment docs.

[datapythonista]

Missing spaces after comma for PEP-8.

[datapythonista]

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.

[datapythonista]

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

[datapythonista]

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?

[datapythonista]

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.

[TomAugspurger]

@kaoboyandy will you have time to update based on @datapythonista's comments?

[datapythonista]

@WillAyd do you mind taking a quick look (I made some last changes), and if you're happy merge it?

[WillAyd]

Thanks @kaoboyandy and @datapythonista !