DOC: Improved the docstring of pandas.Series.clip

[ReubenMarkham]

################################################################################
######################## Docstring (pandas.Series.clip) ########################
################################################################################

Trim values at input threshold(s).

    Truncates values below and above specified thresholds.
    Thresholds can be singular values or array like, and in
the latter case the truncation is performed element-wise
in the specified axis.

Parameters
----------
lower : float or array_like, default None
    Minimum threshold value. All values below this
    threshold will be set to it.
upper : float or array_like, default None
    Maximum threshold value. All values above this 
    threshold will be set to it.
axis : int or string axis name, optional
    Align object with lower and upper along the given axis.
inplace : boolean, default False
    Whether to perform the operation in place on the data
        .. versionadded:: 0.21.0.
args : iterable, optional
    Arguments to pass to the function.
kwargs : mapping, optional
    Keyworded arguments to pass to the function.

See Also
--------
clip_lower : Return copy of the input with values below given value(s) truncated.
clip_upper : Return copy of the input with values above given value(s) truncated.

Returns
-------
clipped : Series

Examples
--------
>>> data = {'0': [9, -3, 0, -1, 5], '1': [-2, -7, 6, 8, -5]}
>>> df = pd.DataFrame(data)
>>> df
        0       1
0       9       -2
1       -3      -7
2       0       6
3       -1      8
4       5       -5

>>> df.clip(-4, 6)
    0   1
0       6       -2
1       -3      -4
2       0       6
3       -1      6
4       5       -4

>>> t = pd.Series([2, -4, -1, 6, 3])
>>> t
0    2
1   -4
2   -1
3    6
4    3
dtype: int64

>>> df.clip(t, t + 4, axis=0)
        0       1
0       6       2
1       -3      -4
2       0       3
3       6       8
4       5       3

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

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

[pep8speaks]

Hello @ReubenMarkham! Thanks for updating the PR.

Cheers ! There are no PEP8 issues in this Pull Request. 🍻

Comment last updated on March 10, 2018 at 16:27 Hours UTC

[stijnvanhoey]

alignment of the printed output seems strange. Should align right for each individual column

[stijnvanhoey]

cfr. docstring guide, use actual names for the column names instead of 0, 1

[stijnvanhoey]

cfr. comment on alignment

[stijnvanhoey]

Truncates feels like you throw away the values outside the specified range. I would make it more descriptive by actually saying that values outside the boundaries are reset to the boundary values.

[stijnvanhoey]

Clips -> Clip

[stijnvanhoey]

kwargs -> **kwargs

[stijnvanhoey]

args -> *args

[stijnvanhoey]

See discussion on https://github.com/pandas-dev/pandas/pull/19985/files#diff-248241e14f081931cc805f9d0e137a5fR709

maybe change to:

*args, **kwargs 
    Additional keywords have no effect but might be accepted 
    for compatibility with numpy.

[stijnvanhoey]

Returns
----------
`pandas.Series`
    Series with the values outside the clip boundaries replaced

[dcanones]

Good!

[stijnvanhoey]

@ReubenMarkham why this branch is closed instead of merged?

[dcanones]

@stijnvanhoey Hi!, you can find the PR related to this method here: #20256

Reuben asked me to continue his job and all your suggestions should be already included in the new PR.

[stijnvanhoey]

Great! Would have been a pity to not include the work of Reuben. Nice work!