From 0f83cd5435651c641ce79943fc3ccbb1abfb6ec4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20Adri=C3=A1n=20Ca=C3=B1ones=20Castellano?= Date: Sat, 10 Mar 2018 23:20:53 +0100 Subject: [PATCH 1/5] DOC: Improved the docstring of pandas.Series.clip --- pandas/core/generic.py | 80 ++++++++++++++++++++++++++---------------- 1 file changed, 50 insertions(+), 30 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 397726181d2fb..5f5627a9363a2 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5605,53 +5605,73 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, """ Trim values at input threshold(s). + 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 ---------- 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 + Whether to perform the operation in place on the data. .. versionadded:: 0.21.0 + *args, **kwargs + Additional keywords have no effect but might be accepted + for compatibility with numpy. + + See Also + -------- + Series.clip_lower : Clip values below specified threshold(s). + Series.clip_upper : Clip values above specified threshold(s). Returns ------- - clipped : Series + `pandas.Series` + Series with the values outside the clip boundaries replaced Examples -------- + >>> data = {'col_0': [9, -3, 0, -1, 5], 'col_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 - + col_0 col_1 + 0 9 -2 + 1 -3 -7 + 2 0 6 + 3 -1 8 + 4 5 -5 + + >>> df.clip(-4, 6) + 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 - 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) + 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 a5947019396a5a1fe7388f90070c75550b529341 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20Adri=C3=A1n=20Ca=C3=B1ones=20Castellano?= Date: Sun, 11 Mar 2018 13:40:03 +0100 Subject: [PATCH 2/5] DOC: update the docstring of pandas.Series.clip Examples small improvements --- pandas/core/generic.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 5f5627a9363a2..8fb2d72e5fd3d 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5648,6 +5648,8 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, 3 -1 8 4 5 -5 + Clips per column using lower and upper thresholds: + >>> df.clip(-4, 6) col_0 col_1 0 6 -2 @@ -5656,6 +5658,8 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, 3 -1 6 4 5 -4 + Clips using specific lower and upper thresholds per column element: + >>> t = pd.Series([2, -4, -1, 6, 3]) >>> t 0 2 From d36d86c30347dcbd5dde150279b3faf0152bdd38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20Adri=C3=A1n=20Ca=C3=B1ones=20Castellano?= Date: Sun, 11 Mar 2018 14:02:55 +0100 Subject: [PATCH 3/5] DOC: update the docstring of pandas.Series.clip Fixed versionadded --- pandas/core/generic.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 8fb2d72e5fd3d..df97d2d52ffe9 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5621,7 +5621,8 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, 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, **kwargs Additional keywords have no effect but might be accepted for compatibility with numpy. From 9c1aa01a911eca8df59534b4e6b51a04325ed3b0 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 15 Mar 2018 15:32:24 +0100 Subject: [PATCH 4/5] Update generic.py --- pandas/core/generic.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index df97d2d52ffe9..2d414394cc997 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5634,8 +5634,9 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, Returns ------- - `pandas.Series` - Series with the values outside the clip boundaries replaced + Series or DataFrame + Same type as calling object with the values outside the + clip boundaries replaced Examples -------- From 8f10ecd018ed256e2b0e6170181fd1658d205042 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 15 Mar 2018 15:33:14 +0100 Subject: [PATCH 5/5] Update generic.py --- pandas/core/generic.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 2d414394cc997..3144cfc2fb4da 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5629,8 +5629,8 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False, See Also -------- - Series.clip_lower : Clip values below specified threshold(s). - Series.clip_upper : Clip values above specified threshold(s). + clip_lower : Clip values below specified threshold(s). + clip_upper : Clip values above specified threshold(s). Returns -------