From d1bb286e6f7136e768770e089a5e1f1715079dc1 Mon Sep 17 00:00:00 2001 From: Fernando Margueirat Date: Sun, 11 Mar 2018 18:53:49 -0400 Subject: [PATCH 1/6] DOC: update the pandas.DataFrame.clip_lower docstring --- pandas/core/generic.py | 65 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 61 insertions(+), 4 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 397726181d2fb..93870f551db77 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5716,24 +5716,81 @@ def clip_upper(self, threshold, axis=None, inplace=False): def clip_lower(self, threshold, axis=None, inplace=False): """ - Return copy of the input with values below given value(s) truncated. + Return copy of the input with values below given value(s) trimmed. + + If an element value is below the threshold, the threshold value is + returned instead. Parameters ---------- threshold : float or array_like - axis : int or string axis name, optional + Lower value(s) to which the input value(s) will be trimmed. + axis : {0 or 'index', 1 or 'columns'} 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 + .. versionadded:: 0.21.0. See Also -------- - clip + DataFrame.clip: Trim values at input threshold(s). + DataFrame.clip_upper: Return copy of input with values above given + value(s) trimmed. + Series.clip_lower: Return copy of the input with values below given + value(s) trimmed. Returns ------- clipped : same type as input + + Examples + -------- + >>> df = pd.DataFrame({'a': [0.740518, 0.450228, 0.710404, -0.771225], + ... 'b': [0.040507, -0.45121, 0.760925, 0.010624]}) + + >>> df + a b + 0 0.740518 0.040507 + 1 0.450228 -0.451210 + 2 0.710404 0.760925 + 3 -0.771225 0.010624 + + Clip to a scalar value + + >>> df.clip_lower(0.2) + a b + 0 0.740518 0.200000 + 1 0.450228 0.200000 + 2 0.710404 0.760925 + 3 0.200000 0.200000 + + Clip to an array along the index axis + + >>> df.clip_lower([0.2, 0.4, 0.6, 0.8], axis=0) + a b + 0 0.740518 0.200000 + 1 0.450228 0.400000 + 2 0.710404 0.760925 + 3 0.800000 0.800000 + + Clip to an array column the index axis + + >>> df.clip_lower([0.5, 0.0], axis=1) + a b + 0 0.740518 0.040507 + 1 0.500000 0.000000 + 2 0.710404 0.760925 + 3 0.500000 0.010624 + + Clip in place + + >>> df.clip_lower(0.2, inplace=True) + >>> df + a b + 0 0.740518 0.200000 + 1 0.450228 0.200000 + 2 0.710404 0.760925 + 3 0.200000 0.200000 """ return self._clip_with_one_bound(threshold, method=self.ge, axis=axis, inplace=inplace) From 22a256f9c915ed1dd3cb14ce032cf9d0f7ab126e Mon Sep 17 00:00:00 2001 From: Fernando Margueirat Date: Sun, 11 Mar 2018 20:18:05 -0400 Subject: [PATCH 2/6] DOC: update the pandas.DataFrame.clip_lower docstring --- pandas/core/generic.py | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 93870f551db77..cef1412c8fb47 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5718,30 +5718,34 @@ def clip_lower(self, threshold, axis=None, inplace=False): """ Return copy of the input with values below given value(s) trimmed. - If an element value is below the threshold, the threshold value is - returned instead. + Elements below the `threshold` will be changed to `threshold`. Parameters ---------- - threshold : float or array_like + threshold : float or array-like Lower value(s) to which the input value(s) will be trimmed. - axis : {0 or 'index', 1 or 'columns'} + axis : {0 or ‘index’, 1 or ‘columns’, None}, default None 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. + + .. versionadded:: 0.21.0 See Also -------- - DataFrame.clip: Trim values at input threshold(s). - DataFrame.clip_upper: Return copy of input with values above given + DataFrame.clip : Trim values at input threshold(s). + DataFrame.clip_upper : Return copy of input with values above given + value(s) trimmed. + Series.clip : Trim values at input threshold(s). + Series.clip_lower : Return copy of the input with values below given value(s) trimmed. - Series.clip_lower: Return copy of the input with values below given + Series.clip_upper : Return copy of input with values above given value(s) trimmed. Returns ------- - clipped : same type as input + Series or DataFrame + Same type as caller. Examples -------- From 5312dd051f09559dd4dbf93158a9292cd66f684a Mon Sep 17 00:00:00 2001 From: Fernando Margueirat Date: Sun, 11 Mar 2018 23:24:28 -0400 Subject: [PATCH 3/6] DOC: update the pandas.DataFrame.clip_lower docstring --- pandas/core/generic.py | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index cef1412c8fb47..f5767b6f084ef 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5718,13 +5718,14 @@ def clip_lower(self, threshold, axis=None, inplace=False): """ Return copy of the input with values below given value(s) trimmed. - Elements below the `threshold` will be changed to `threshold`. + Elements below the `threshold` will be changed to match the + `threshold` value(s). Parameters ---------- threshold : float or array-like Lower value(s) to which the input value(s) will be trimmed. - axis : {0 or ‘index’, 1 or ‘columns’, None}, default None + axis : {0 or 'index', 1 or 'columns', None}, default None Align object with threshold along the given axis. inplace : boolean, default False Whether to perform the operation in place on the data. @@ -5733,14 +5734,14 @@ def clip_lower(self, threshold, axis=None, inplace=False): See Also -------- - DataFrame.clip : Trim values at input threshold(s). - DataFrame.clip_upper : Return copy of input with values above given - value(s) trimmed. - Series.clip : Trim values at input threshold(s). - Series.clip_lower : Return copy of the input with values below given - value(s) trimmed. - Series.clip_upper : Return copy of input with values above given - value(s) trimmed. + 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_lower : Trim `Series` values below given threshold(s) + Series.clip_upper : Trim `Series` values above given threshold(s) Returns ------- From ba4c36203b968c71d96174a6bce95e74d92af62c Mon Sep 17 00:00:00 2001 From: Fernando Margueirat Date: Tue, 13 Mar 2018 11:27:09 -0400 Subject: [PATCH 4/6] DOC: update the pandas.DataFrame.clip_lower docstring --- pandas/core/generic.py | 15 ++------------- 1 file changed, 2 insertions(+), 13 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index f5767b6f084ef..5c0e937ebdb24 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5716,7 +5716,7 @@ def clip_upper(self, threshold, axis=None, inplace=False): def clip_lower(self, threshold, axis=None, inplace=False): """ - Return copy of the input with values below given value(s) trimmed. + Trim the caller's values below a given `threshold`. Elements below the `threshold` will be changed to match the `threshold` value(s). @@ -5732,17 +5732,6 @@ def clip_lower(self, threshold, axis=None, inplace=False): .. versionadded:: 0.21.0 - 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_lower : Trim `Series` values below given threshold(s) - Series.clip_upper : Trim `Series` values above given threshold(s) - Returns ------- Series or DataFrame @@ -5778,7 +5767,7 @@ def clip_lower(self, threshold, axis=None, inplace=False): 2 0.710404 0.760925 3 0.800000 0.800000 - Clip to an array column the index axis + Clip to an array along the column axis >>> df.clip_lower([0.5, 0.0], axis=1) a b From 13c9d827c270ec3e5b488352d0768da458034978 Mon Sep 17 00:00:00 2001 From: Fernando Margueirat Date: Tue, 13 Mar 2018 12:40:04 -0400 Subject: [PATCH 5/6] DOC: update the pandas.DataFrame.clip_lower docstring --- pandas/core/generic.py | 72 +++++++++++++++++++++++------------------- 1 file changed, 39 insertions(+), 33 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 5c0e937ebdb24..3f8f6603b2394 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -5732,59 +5732,65 @@ def clip_lower(self, threshold, axis=None, inplace=False): .. versionadded:: 0.21.0 + 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) + Returns ------- - Series or DataFrame - Same type as caller. + type of caller + Original data with values trimmed. Examples -------- - >>> df = pd.DataFrame({'a': [0.740518, 0.450228, 0.710404, -0.771225], - ... 'b': [0.040507, -0.45121, 0.760925, 0.010624]}) + >>> df = pd.DataFrame({'a': [-1, -2, -100], + ... 'b': [1, 2, 100]}, + ... index = ['foo', 'bar', 'foobar']) >>> df - a b - 0 0.740518 0.040507 - 1 0.450228 -0.451210 - 2 0.710404 0.760925 - 3 -0.771225 0.010624 + a b + foo -1 1 + bar -2 2 + foobar -100 100 Clip to a scalar value - >>> df.clip_lower(0.2) - a b - 0 0.740518 0.200000 - 1 0.450228 0.200000 - 2 0.710404 0.760925 - 3 0.200000 0.200000 + >>> df.clip_lower(0) + a b + foo 0 1 + bar 0 2 + foobar 0 100 Clip to an array along the index axis - >>> df.clip_lower([0.2, 0.4, 0.6, 0.8], axis=0) - a b - 0 0.740518 0.200000 - 1 0.450228 0.400000 - 2 0.710404 0.760925 - 3 0.800000 0.800000 + >>> df.clip_lower([0, 5, 10], axis=0) + a b + foo 0 1 + bar 5 5 + foobar 10 100 Clip to an array along the column axis - >>> df.clip_lower([0.5, 0.0], axis=1) - a b - 0 0.740518 0.040507 - 1 0.500000 0.000000 - 2 0.710404 0.760925 - 3 0.500000 0.010624 + >>> df.clip_lower([-5, 10], axis=1) + a b + foo -1 10 + bar -2 10 + foobar -5 100 Clip in place - >>> df.clip_lower(0.2, inplace=True) + >>> df.clip_lower(0, inplace=True) >>> df - a b - 0 0.740518 0.200000 - 1 0.450228 0.200000 - 2 0.710404 0.760925 - 3 0.200000 0.200000 + a b + foo 0 1 + bar 0 2 + foobar 0 100 """ return self._clip_with_one_bound(threshold, method=self.ge, axis=axis, inplace=inplace) From e48d49b4451b094b7fecfad29622d883772d6510 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Sun, 8 Jul 2018 09:39:44 -0500 Subject: [PATCH 6/6] fixup --- pandas/core/generic.py | 1 + 1 file changed, 1 insertion(+) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 33f2835a85683..920b0f5ae7b51 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -6689,6 +6689,7 @@ def groupby(self, by=None, axis=0, level=None, as_index=True, sort=True, Group series using mapper (dict or key function, apply given function to group, return result as series) or by a series of columns. + Parameters ---------- by : mapping, function, label, or list of labels Used to determine the groups for the groupby.