From 51f612c5b0fa022bdf8725350e1321c287dca807 Mon Sep 17 00:00:00 2001 From: Unknown Date: Sat, 10 Mar 2018 14:45:30 +0100 Subject: [PATCH 1/5] DOC: improved the docstring of pandas.Series.clip_upper improved --- pandas/core/generic.py | 60 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 53 insertions(+), 7 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index a893b2ba1a189..f3293481054fe 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5635,24 +5635,67 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, def clip_upper(self, threshold, axis=None, inplace=False): """ - Return copy of input with values above given value(s) truncated. + Return copy of the input with values above given value(s) truncated. + + It truncates values above a certain threshold. Threshold can be a single + value or an array, in the latter case it performs the truncation + element-wise. Parameters ---------- threshold : float or array_like + Maximum value allowed. All values above threshold will be + set to this value. axis : int or string axis name, optional Align object with threshold along the given axis. inplace : boolean, default False - Whether to perform the operation in place on the data - .. versionadded:: 0.21.0 + Whether to perform the operation in place on the data. See Also -------- - clip + clip : Return copy of input with values below/above thresholds truncated. + clip_lower : Return copy of input with values below given thresholds. Returns ------- clipped : same type as input + + Examples + -------- + >>> s = pd.Series([1,2,3,4,5,6,7]) + >>> s + 0 1 + 1 2 + 2 3 + 3 4 + 4 5 + 5 6 + 6 7 + dtype: int64 + + >>> s.clip_upper(4) + 0 1 + 1 2 + 2 3 + 3 4 + 4 4 + 5 4 + 6 4 + dtype: int64 + + >>> t = [4,8,7,2,5,4,6] + >>> t + [4, 8, 7, 2, 5, 4, 6] + + >>> s.clip_upper(t) + 0 1 + 1 2 + 2 3 + 3 2 + 4 5 + 5 4 + 6 6 + dtype: int64 """ return self._clip_with_one_bound(threshold, method=self.le, axis=axis, inplace=inplace) @@ -5661,18 +5704,21 @@ def clip_lower(self, threshold, axis=None, inplace=False): """ Return copy of the input with values below given value(s) truncated. + + Parameters ---------- threshold : float or array_like + Minimun value allowed. All values below threshold will be + equaled to the threshold value. axis : int or string axis name, optional Align object with threshold along the given axis. inplace : boolean, default False - Whether to perform the operation in place on the data - .. versionadded:: 0.21.0 + Whether to perform the operation in place on the data. See Also -------- - clip + clip: Returns ------- From da2dac7736deb9eaf1243698d4daba39681dbe98 Mon Sep 17 00:00:00 2001 From: Unknown Date: Sat, 10 Mar 2018 14:52:40 +0100 Subject: [PATCH 2/5] DOC: improved the docstring of pandas.Series.clip_upper improved PEP8 corrections --- pandas/core/generic.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index f3293481054fe..286608799f59d 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5637,8 +5637,9 @@ def clip_upper(self, threshold, axis=None, inplace=False): """ Return copy of the input with values above given value(s) truncated. - It truncates values above a certain threshold. Threshold can be a single - value or an array, in the latter case it performs the truncation + It truncates values above a certain threshold. Threshold can be a + single value or an array, in the latter case it performs the + truncation element-wise. Parameters @@ -5653,8 +5654,8 @@ def clip_upper(self, threshold, axis=None, inplace=False): See Also -------- - clip : Return copy of input with values below/above thresholds truncated. - clip_lower : Return copy of input with values below given thresholds. + clip : Return input copy with values below/above thresholds truncated. + clip_lower : Return input copy input with values below given thresholds. Returns ------- From 86bc86ee83be19adbd245c805b05cfe2d9041b8f Mon Sep 17 00:00:00 2001 From: Unknown Date: Sat, 10 Mar 2018 16:17:06 +0100 Subject: [PATCH 3/5] DOC: improved the docstring of pandas.Series.clip_upper improved PEP-8 correctios --- pandas/core/generic.py | 35 +++++++++++++++-------------------- 1 file changed, 15 insertions(+), 20 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 286608799f59d..0c157f00923e1 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5638,19 +5638,19 @@ def clip_upper(self, threshold, axis=None, inplace=False): Return copy of the input with values above given value(s) truncated. It truncates values above a certain threshold. Threshold can be a - single value or an array, in the latter case it performs the - truncation + single value or an array, in the latter case it performs the truncation element-wise. Parameters ---------- - threshold : float or array_like - Maximum value allowed. All values above threshold will be - set to this value. + threshold : float or array-like + Maximum value allowed. All values above threshold will be set to + this value. axis : int or string axis name, optional Align object with threshold along the given axis. - inplace : boolean, default False + inplace : bool, default False Whether to perform the operation in place on the data. + .. versionadded:: 0.21.0. See Also -------- @@ -5663,39 +5663,33 @@ def clip_upper(self, threshold, axis=None, inplace=False): Examples -------- - >>> s = pd.Series([1,2,3,4,5,6,7]) + >>> s = pd.Series([1, 2, 3, 4, 5]) >>> s 0 1 1 2 2 3 3 4 4 5 - 5 6 - 6 7 dtype: int64 - >>> s.clip_upper(4) + >>> s.clip_upper(3) 0 1 1 2 2 3 - 3 4 - 4 4 - 5 4 - 6 4 + 3 3 + 4 3 dtype: int64 - >>> t = [4,8,7,2,5,4,6] + >>> t = [5, 4, 3, 2, 1] >>> t - [4, 8, 7, 2, 5, 4, 6] + [5, 4, 3, 2, 1] >>> s.clip_upper(t) 0 1 1 2 2 3 3 2 - 4 5 - 5 4 - 6 6 + 4 1 dtype: int64 """ return self._clip_with_one_bound(threshold, method=self.le, @@ -5719,7 +5713,7 @@ def clip_lower(self, threshold, axis=None, inplace=False): See Also -------- - clip: + clip : Return input copy with values below/above thresholds truncated. Returns ------- @@ -5903,6 +5897,7 @@ def at_time(self, time, asof=False): Parameters ---------- time : datetime.time or string + asof : Returns ------- From 930787d29b88c3a1277bfc7f72737269900c6905 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Sun, 8 Jul 2018 09:53:20 -0500 Subject: [PATCH 4/5] fixups --- pandas/core/generic.py | 65 ++++++++++++++++++++++++++---------------- 1 file changed, 40 insertions(+), 25 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index a7e099452f834..c34b8a7712170 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -6547,32 +6547,47 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, def clip_upper(self, threshold, axis=None, inplace=False): """ - Return copy of the input with values above given value(s) truncated. + Trim values above a given threshold. - It truncates values above a certain threshold. Threshold can be a - single value or an array, in the latter case it performs the truncation - element-wise. + 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. Parameters ---------- - threshold : float or array-like + threshold : numeric or array-like Maximum value allowed. All values above threshold will be set to this value. - axis : int or string axis name, optional - Align object with threshold along the given axis. + + * float : every value is compared to `threshold`. + * array-like : The shape of `threshold` should match the object + it's compared to. When `self` is a Series, `threshold` should be + the length. When `self` is a DataFrame, `threshold` should 2-D + and the same shape as `self` for ``axis=None``, or 1-D and the + same length as the axis being compared. + + axis : {0 or 'index', 1 or 'columns'}, default 0 + Align object with `threshold` along the given axis. + inplace : boolean, default False - Whether to perform the operation in place on the data + Whether to perform the operation in place on the data. .. versionadded:: 0.21.0 - See Also - -------- - clip : Return input copy with values below/above thresholds truncated. - clip_lower : Return input copy input with values below given thresholds. - Returns ------- - clipped : same type as input + clipped + 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) Examples -------- @@ -6613,7 +6628,8 @@ def clip_lower(self, threshold, axis=None, inplace=False): Trim values below a given threshold. Elements below the `threshold` will be changed to match the - `threshold` value(s). + `threshold` value(s). Threshold can be a single value or an array, + in the latter case it performs the truncation element-wise. Parameters ---------- @@ -6636,20 +6652,20 @@ def clip_lower(self, threshold, axis=None, inplace=False): .. versionadded:: 0.21.0 + Returns + ------- + clipped + Original data with values trimmed. + See Also -------- - DataFrame.clip : General purpose method to trim `DataFrame` values to + DataFrame.clip : General purpose method to trim DataFrame values to given threshold(s) - DataFrame.clip_upper : Trim `DataFrame` values above given + DataFrame.clip_upper : Trim DataFrame values above given threshold(s) - Series.clip : General purpose method to trim `Series` values to given + Series.clip : General purpose method to trim Series values to given threshold(s) - Series.clip_upper : Trim `Series` values above given threshold(s) - - Returns - ------- - clipped - Original data with values trimmed. + Series.clip_upper : Trim Series values above given threshold(s) Examples -------- @@ -6716,7 +6732,6 @@ def clip_lower(self, threshold, axis=None, inplace=False): 0 4 5 1 4 5 2 5 6 - """ return self._clip_with_one_bound(threshold, method=self.ge, axis=axis, inplace=inplace) From f4974a766439aa4da85504a90aec05dd69981828 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Sun, 8 Jul 2018 09:56:27 -0500 Subject: [PATCH 5/5] fixup --- pandas/core/generic.py | 1 - 1 file changed, 1 deletion(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index e03378ef24eba..48366a286ac05 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -6921,7 +6921,6 @@ def at_time(self, time, asof=False): Parameters ---------- time : datetime.time or string - asof : Returns -------