Skip to content

DEPR: Deprecating .clip_lower and .clip_upper #24203

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
Dec 10, 2018
Merged

DEPR: Deprecating .clip_lower and .clip_upper #24203

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b09a0ce
DEPR: Deprecating .clip_lower and .clip_upper
datapythonista Dec 10, 2018
5d0d01a
Updating PR issue
datapythonista Dec 10, 2018
66dde2f
Merging from master
datapythonista Dec 10, 2018
383f6d6
Removing line break
datapythonista Dec 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
2 changes: 2 additions & 0 deletions doc/source/whatsnew/v0.24.0.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1113,6 +1113,8 @@ Deprecations
- :func:`pandas.types.is_datetimetz` is deprecated in favor of `pandas.types.is_datetime64tz` (:issue:`23917`)
- Creating a :class:`TimedeltaIndex` or :class:`DatetimeIndex` by passing range arguments `start`, `end`, and `periods` is deprecated in favor of :func:`timedelta_range` and :func:`date_range` (:issue:`23919`)
- Passing a string alias like ``'datetime64[ns, UTC]'`` as the `unit` parameter to :class:`DatetimeTZDtype` is deprecated. Use :class:`DatetimeTZDtype.construct_from_string` instead (:issue:`23990`).
- :meth:`Series.clip_lower`, :meth:`Series.clip_upper`, :meth:`DataFrame.clip_lower` and :meth:`DataFrame.clip_upper` are deprecated and will be removed in a future version.
Use ``Series.clip(lower=threshold)``, ``Series.clip(upper=threshold)`` and the equivalent ``DataFrame`` methods (:issue:`24203`)
Copy link
Contributor

Choose a reason for hiding this comment

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

is this on another line?


.. _whatsnew_0240.deprecations.datetimelike_int_ops:

Expand Down
41 changes: 22 additions & 19 deletions pandas/core/generic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7204,11 +7204,6 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False,
Same type as calling object with the values outside the
clip boundaries replaced

See Also
--------
clip_lower : Clip values below specified threshold(s).
clip_upper : Clip values above specified threshold(s).

Examples
--------
>>> data = {'col_0': [9, -3, 0, -1, 5], 'col_1': [-2, -7, 6, 8, -5]}
Expand Down Expand Up @@ -7281,18 +7276,23 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False,

result = self
if lower is not None:
result = result.clip_lower(lower, axis, inplace=inplace)
result = result._clip_with_one_bound(lower, method=self.ge,
axis=axis, inplace=inplace)
if upper is not None:
if inplace:
result = self
result = result.clip_upper(upper, axis, inplace=inplace)
result = result._clip_with_one_bound(upper, method=self.le,
axis=axis, inplace=inplace)

return result

def clip_upper(self, threshold, axis=None, inplace=False):
"""
Trim values above a given threshold.

.. deprecated:: 0.24.0
Use clip(upper=threshold) instead.

Elements above the `threshold` will be changed to match the
`threshold` value(s). Threshold can be a single value or an array,
in the latter case it performs the truncation element-wise.
Expand All @@ -7319,18 +7319,15 @@ def clip_upper(self, threshold, axis=None, inplace=False):

Returns
-------
clipped
Series or DataFrame
Original data with values trimmed.

See Also
--------
DataFrame.clip : General purpose method to trim DataFrame values to
given threshold(s).
DataFrame.clip_lower : Trim DataFrame values below given
threshold(s).
Series.clip : General purpose method to trim Series values to given
threshold(s).
Series.clip_lower : Trim Series values below given threshold(s).
DataFrame.clip : General purpose method to trim DataFrame values to
given threshold(s).

Examples
--------
Expand Down Expand Up @@ -7363,13 +7360,19 @@ def clip_upper(self, threshold, axis=None, inplace=False):
4 1
dtype: int64
"""
warnings.warn('clip_upper(threshold) is deprecated, '
'use clip(upper=threshold) instead',
FutureWarning, stacklevel=2)
return self._clip_with_one_bound(threshold, method=self.le,
axis=axis, inplace=inplace)

def clip_lower(self, threshold, axis=None, inplace=False):
"""
Trim values below a given threshold.

.. deprecated:: 0.24.0
Use clip(lower=threshold) instead.

Elements below the `threshold` will be changed to match the
`threshold` value(s). Threshold can be a single value or an array,
in the latter case it performs the truncation element-wise.
Expand Down Expand Up @@ -7397,18 +7400,15 @@ def clip_lower(self, threshold, axis=None, inplace=False):

Returns
-------
clipped
Series or DataFrame
Original data with values trimmed.

See Also
--------
DataFrame.clip : General purpose method to trim DataFrame values to
given threshold(s).
DataFrame.clip_upper : Trim DataFrame values above given
threshold(s).
Series.clip : General purpose method to trim Series values to given
threshold(s).
Series.clip_upper : Trim Series values above given threshold(s).
DataFrame.clip : General purpose method to trim DataFrame values to
given threshold(s).

Examples
--------
Expand Down Expand Up @@ -7476,6 +7476,9 @@ def clip_lower(self, threshold, axis=None, inplace=False):
1 4 5
2 5 6
"""
warnings.warn('clip_lower(threshold) is deprecated, '
'use clip(lower=threshold) instead',
FutureWarning, stacklevel=2)
return self._clip_with_one_bound(threshold, method=self.ge,
axis=axis, inplace=inplace)

Expand Down
15 changes: 10 additions & 5 deletions pandas/tests/frame/test_analytics.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1841,10 +1841,12 @@ def test_clip(self, float_frame):
median = float_frame.median().median()
original = float_frame.copy()

capped = float_frame.clip_upper(median)
with tm.assert_produces_warning(FutureWarning):
capped = float_frame.clip_upper(median)
assert not (capped.values > median).any()

floored = float_frame.clip_lower(median)
with tm.assert_produces_warning(FutureWarning):
floored = float_frame.clip_lower(median)
assert not (floored.values < median).any()

double = float_frame.clip(upper=median, lower=median)
Expand All @@ -1858,11 +1860,13 @@ def test_inplace_clip(self, float_frame):
median = float_frame.median().median()
frame_copy = float_frame.copy()

frame_copy.clip_upper(median, inplace=True)
with tm.assert_produces_warning(FutureWarning):
frame_copy.clip_upper(median, inplace=True)
assert not (frame_copy.values > median).any()
frame_copy = float_frame.copy()

frame_copy.clip_lower(median, inplace=True)
with tm.assert_produces_warning(FutureWarning):
frame_copy.clip_lower(median, inplace=True)
assert not (frame_copy.values < median).any()
frame_copy = float_frame.copy()

Expand Down Expand Up @@ -2263,7 +2267,8 @@ def test_series_broadcasting(self):
s_nan = Series([np.nan, np.nan, 1])

with tm.assert_produces_warning(None):
df_nan.clip_lower(s, axis=0)
with tm.assert_produces_warning(FutureWarning):
df_nan.clip_lower(s, axis=0)
for op in ['lt', 'le', 'gt', 'ge', 'eq', 'ne']:
getattr(df, op)(s_nan, axis=0)

Expand Down
20 changes: 14 additions & 6 deletions pandas/tests/series/test_analytics.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -924,8 +924,10 @@ def test_matmul(self):
def test_clip(self, datetime_series):
val = datetime_series.median()

assert datetime_series.clip_lower(val).min() == val
assert datetime_series.clip_upper(val).max() == val
with tm.assert_produces_warning(FutureWarning):
assert datetime_series.clip_lower(val).min() == val
with tm.assert_produces_warning(FutureWarning):
assert datetime_series.clip_upper(val).max() == val

assert datetime_series.clip(lower=val).min() == val
assert datetime_series.clip(upper=val).max() == val
Expand All @@ -943,8 +945,10 @@ def test_clip_types_and_nulls(self):

for s in sers:
thresh = s[2]
lower = s.clip_lower(thresh)
upper = s.clip_upper(thresh)
with tm.assert_produces_warning(FutureWarning):
lower = s.clip_lower(thresh)
with tm.assert_produces_warning(FutureWarning):
upper = s.clip_upper(thresh)
assert lower[notna(lower)].min() == thresh
assert upper[notna(upper)].max() == thresh
assert list(isna(s)) == list(isna(lower))
Expand All @@ -971,8 +975,12 @@ def test_clip_against_series(self):
s = Series([1.0, 1.0, 4.0])
threshold = Series([1.0, 2.0, 3.0])

assert_series_equal(s.clip_lower(threshold), Series([1.0, 2.0, 4.0]))
assert_series_equal(s.clip_upper(threshold), Series([1.0, 1.0, 3.0]))
with tm.assert_produces_warning(FutureWarning):
assert_series_equal(s.clip_lower(threshold),
Series([1.0, 2.0, 4.0]))
with tm.assert_produces_warning(FutureWarning):
assert_series_equal(s.clip_upper(threshold),
Series([1.0, 1.0, 3.0]))

lower = Series([1.0, 2.0, 3.0])
upper = Series([1.5, 2.5, 3.5])
Expand Down