From 2b9b80824f3107ace7498901ebccfee80c30031b Mon Sep 17 00:00:00 2001 From: enigma Date: Sat, 10 Mar 2018 16:22:51 +0100 Subject: [PATCH 1/5] DOC: Improved the docstring of pandas.Series.clip --- pandas/core/generic.py | 79 ++++++++++++++++++++++++++---------------- 1 file changed, 50 insertions(+), 29 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index a893b2ba1a189..2c8b784062b36 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5548,15 +5548,33 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, """ 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 + .. 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 ------- @@ -5564,37 +5582,40 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, Examples -------- + >>> data = {'0': [9, -3, 0, -1, 5], '1': [-2, -7, 6, 8, -5]} + >>> 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 + + >>> 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 -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") From 7bcc5be25c357850a56c4fafb47f644679cd2e4d Mon Sep 17 00:00:00 2001 From: enigma Date: Sat, 10 Mar 2018 16:38:57 +0100 Subject: [PATCH 2/5] DOC: Improved the docstring of pandas.Series.clip v2 --- pandas/core/generic.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 2c8b784062b36..4937747c2241c 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5548,8 +5548,8 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, """ Trim values at input threshold(s). - Truncates values below and above specified thresholds. - Thresholds can be singular values or array like, and in + 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. @@ -5559,7 +5559,7 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, 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 + 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. @@ -5573,8 +5573,8 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, 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. + clip_lower : Clips values below specified threshold(s). + clip_upper : Clips values above specified threshold(s). Returns ------- @@ -5585,7 +5585,7 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, >>> data = {'0': [9, -3, 0, -1, 5], '1': [-2, -7, 6, 8, -5]} >>> df = pd.DataFrame(data) >>> df - 0 1 + 0 1 0 9 -2 1 -3 -7 2 0 6 @@ -5610,7 +5610,7 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, dtype: int64 >>> df.clip(t, t + 4, axis=0) - 0 1 + 0 1 0 6 2 1 -3 -4 2 0 3 From 2031c594aadd4b6d9fde3becac6ddd564b81bfa9 Mon Sep 17 00:00:00 2001 From: enigma Date: Sat, 10 Mar 2018 16:53:31 +0100 Subject: [PATCH 3/5] DOC: Improved the docstring of pandas.Series.clip v3 --- pandas/core/generic.py | 40 +++++++++++++++++++++------------------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 4937747c2241c..e191b1c409317 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5582,23 +5582,24 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, Examples -------- - >>> data = {'0': [9, -3, 0, -1, 5], '1': [-2, -7, 6, 8, -5]} + >>> data = {'col_0': [9, -3, 0, -1, 5], 'col_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 + col_0 col_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 + col_0 col_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 @@ -5610,12 +5611,13 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, 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 + col_0 col_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") From ed0cd1f082ab57268e51b329e83ee2eef710b369 Mon Sep 17 00:00:00 2001 From: enigma Date: Sat, 10 Mar 2018 16:53:31 +0100 Subject: [PATCH 4/5] DOC: Improved the docstring of pandas.Series.clip v4 --- pandas/core/generic.py | 40 +++++++++++++++++++++------------------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 4937747c2241c..e191b1c409317 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5582,23 +5582,24 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, Examples -------- - >>> data = {'0': [9, -3, 0, -1, 5], '1': [-2, -7, 6, 8, -5]} + >>> data = {'col_0': [9, -3, 0, -1, 5], 'col_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 + col_0 col_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 + col_0 col_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 @@ -5610,12 +5611,13 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, 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 + col_0 col_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") From 971182ddceedf625aa98b0b340c93addf80bf0b1 Mon Sep 17 00:00:00 2001 From: Unknown Date: Sat, 10 Mar 2018 17:27:09 +0100 Subject: [PATCH 5/5] DOC: Improved the docstring of pandas.Series.clip v4 --- pandas/core/generic.py | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index e191b1c409317..4f7c3f71f5322 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5548,10 +5548,9 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, """ 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. + Assigns values outside boundary to boundary values. Thresholds + can be singular values or array like, and in the latter case + the clipping is performed element-wise in the specified axis. Parameters ---------- @@ -5566,19 +5565,19 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, 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. + *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). + clip_lower : Clip values below specified threshold(s). + clip_upper : Clip values above specified threshold(s). Returns ------- - clipped : Series + `pandas.Series` + Series with the values outside the clip boundaries replaced Examples --------