Skip to content

DOC: Improved the docstring of pandas.Series.clip #20178

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

Closed
wants to merge 6 commits into from
Closed

DOC: Improved the docstring of pandas.Series.clip #20178

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2b9b808
DOC: Improved the docstring of pandas.Series.clip
ReubenMarkham Mar 10, 2018
7bcc5be
DOC: Improved the docstring of pandas.Series.clip v2
ReubenMarkham Mar 10, 2018
2031c59
DOC: Improved the docstring of pandas.Series.clip v3
ReubenMarkham Mar 10, 2018
ed0cd1f
DOC: Improved the docstring of pandas.Series.clip v4
ReubenMarkham Mar 10, 2018
971182d
DOC: Improved the docstring of pandas.Series.clip v4
ReubenMarkham Mar 10, 2018
51966b0
Merge remote-tracking branch 'origin/sprint_madrid_series_clip' into …
ReubenMarkham Mar 10, 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
79 changes: 50 additions & 29 deletions pandas/core/generic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5548,53 +5548,74 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False,
"""
Trim values at input threshold(s).

Truncates values below and above specified thresholds.
Copy link
Contributor

Choose a reason for hiding this comment

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

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.

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
.. versionadded:: 0.21.0.
args : iterable, optional
Copy link
Contributor

Choose a reason for hiding this comment

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

args -> *args

Arguments to pass to the function.
kwargs : mapping, optional
Copy link
Contributor

Choose a reason for hiding this comment

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

kwargs -> **kwargs

Keyworded arguments to pass to the function.
Copy link
Contributor

Choose a reason for hiding this comment

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

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.


See Also
--------
clip_lower : Clips values below specified threshold(s).
clip_upper : Clips values above specified threshold(s).
Copy link
Contributor

Choose a reason for hiding this comment

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

Clips -> Clip


Returns
-------
clipped : Series
Copy link
Contributor

Choose a reason for hiding this comment

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

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


Examples
--------
>>> data = {'0': [9, -3, 0, -1, 5], '1': [-2, -7, 6, 8, -5]}
Copy link
Contributor

Choose a reason for hiding this comment

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

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

>>> df = pd.DataFrame(data)
>>> df
0 1
0 0.335232 -1.256177
1 -1.367855 0.746646
2 0.027753 -1.176076
3 0.230930 -0.679613
4 1.261967 0.570967

>>> df.clip(-1.0, 0.5)
0 1
0 0.335232 -1.000000
1 -1.000000 0.500000
2 0.027753 -1.000000
3 0.230930 -0.679613
4 0.500000 0.500000

0 1
0 9 -2
1 -3 -7
2 0 6
3 -1 8
4 5 -5
Copy link
Contributor

Choose a reason for hiding this comment

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

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


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

Choose a reason for hiding this comment

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

cfr. comment on alignment


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

>>> df.clip(t, t + 1, axis=0)
0 1
0 0.335232 -0.300000
1 -0.200000 0.746646
2 0.027753 -0.100000
3 0.230930 0.000000
4 1.100000 0.570967
>>> df.clip(t, t + 4, axis=0)
0 1
0 6 2
1 -3 -4
2 0 3
3 6 8
4 5 3
"""
if isinstance(self, ABCPanel):
raise NotImplementedError("clip is not supported yet for panels")
Expand Down