DOC: Improve the docstring of Series.take

[gmacario]

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.take) ########################
################################################################################

Return the elements in the given *positional* indices along an axis.

This means that we are not indexing according to actual values in
the index attribute of the object. We are indexing according to the
actual position of the element in the object.

Parameters
----------
indices : array-like
    An array of ints indicating which positions to take.
axis : int, default 0
    The axis on which to select elements. "0" means that we are
    selecting rows, "1" means that we are selecting columns, etc.
convert : bool, default True
    Whether to convert negative indices into positive ones.
    For example, ``-1`` would map to the ``len(axis) - 1``.
    The conversions are similar to the behavior of indexing a
    regular Python list.
    .. deprecated:: 0.21.0
       In the future, negative indices will always be converted.
is_copy : bool, default True
    Whether to return a copy of the original object or not.
kwargs : xxx, default xxx
    TODO MUST ADD A REASONABLE DESCRIPTION.

Returns
-------
taken : type of caller
    An array-like containing the elements taken from the object.

See Also
--------
numpy.ndarray.take : TODO
numpy.take : TODO

Examples
--------
>>> df = pd.DataFrame([('falcon', 'bird',    389.0),
...                    ('parrot', 'bird',     24.0),
...                    ('lion',   'mammal',   80.5),
...                    ('monkey', 'mammal', np.nan)],
...                    columns=('name', 'class', 'max_speed'),
...                    index=[0, 2, 3, 1])
>>> df
     name   class  max_speed
0  falcon    bird      389.0
2  parrot    bird       24.0
3    lion  mammal       80.5
1  monkey  mammal        NaN

Take elements at positions 0 and 3 along the axis 0 (default).

Note how the actual indices selected (0 and 1) do not correspond to
our selected indices 0 and 3. That's because we are selecting the 0th
and 3rd rows, not rows whose indices equal 0 and 3.

>>> df.take([0, 3])
     name   class  max_speed
0  falcon    bird      389.0
1  monkey  mammal        NaN

Take elements at indices 1 and 2 along the axis 1 (column selection).

>>> df.take([1, 2], axis=1)
    class  max_speed
0    bird      389.0
2    bird       24.0
3  mammal       80.5
1  mammal        NaN

We may take elements using negative integers for positive indices,
starting from the end of the object, just like with Python lists.

>>> df.take([-1, -2])
     name   class  max_speed
1  monkey  mammal        NaN
3    lion  mammal       80.5

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

Docstring for "pandas.Series.take" 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.

Signed-off-by: Gianpaolo Macario [email protected]

[kynan]

optional keyword arguments to ``:meth:pandas.compat.numpy.function.validate_take

[gmacario]

Fix in later commit

[kynan]

Take elements from an array along an axis

[gmacario]

Fix in later commit

[kynan]

Return an array formed from the elements at given indices

[gmacario]

Fix in later commit

[codecov]

Codecov Report

❗ No coverage uploaded for pull request base (master@d7bcb22). Click here to learn what that means.
The diff coverage is 100%.

@@            Coverage Diff            @@
##             master   #20179   +/-   ##
=========================================
  Coverage          ?   91.76%           
=========================================
  Files             ?      150           
  Lines             ?    49151           
  Branches          ?        0           
=========================================
  Hits              ?    45102           
  Misses            ?     4049           
  Partials          ?        0

Flag	Coverage Δ
#multiple	90.14% <100%> (?)
#single	41.9% <11.11%> (?)

Impacted Files	Coverage Δ
pandas/core/generic.py	95.85% <100%> (ø)

---

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 d7bcb22...85235a9. Read the comment docs.

[gmacario]

Hello @kynan

I believe I have addressed all your review feedbacks with my recent commits.
Would you mind giving it a look again?

Thanks!

[TomAugspurger]

Thanks @gmacario.