From 7c7e9dc32648e8c229ccbd779b4d41ec2e38451f Mon Sep 17 00:00:00 2001 From: Fernando Margueirat Date: Sat, 10 Mar 2018 13:33:29 -0500 Subject: [PATCH 01/10] DOC: update the pandas.DataFrame.diff docstring --- pandas/core/frame.py | 69 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 67 insertions(+), 2 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index a66d00fff9714..a0fb3f7317b4c 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -4722,12 +4722,17 @@ def melt(self, id_vars=None, value_vars=None, var_name=None, def diff(self, periods=1, axis=0): """ - 1st discrete difference of object + First discrete difference of object. + + Calculates the difference of a DataFrame object compared with another + object in the DataFrame (default is object in same column of the + previous row). Parameters ---------- periods : int, default 1 - Periods to shift for forming difference + Periods to shift for calculating difference, accepts negative + values. axis : {0 or 'index', 1 or 'columns'}, default 0 Take difference over rows (0) or columns (1). @@ -4736,6 +4741,66 @@ def diff(self, periods=1, axis=0): Returns ------- diffed : DataFrame + + Examples + -------- + Difference with previous row + + >>> df = pd.DataFrame([[1, 1, 1], [2, 1, 4], [3, 2, 9], [4, 3, 16], + ... [5, 5, 25], [6, 8, 36]], columns=['Seq', 'Fib', 'Sqr']) + >>> df + Seq Fib Sqr + 0 NaN NaN NaN + 1 1.0 0.0 3.0 + 2 1.0 1.0 5.0 + 3 1.0 1.0 7.0 + 4 1.0 2.0 9.0 + 5 1.0 3.0 11.0 + >>> df.diff() + Seq Fib Sqr + 0 NaN NaN NaN + 1 1.0 0.0 3.0 + 2 1.0 1.0 5.0 + 3 1.0 1.0 7.0 + 4 1.0 2.0 9.0 + 5 1.0 3.0 11.0 + + Difference with previous column + + >>> df.diff(axis=1) + Seq Fib Sqr + 0 NaN 0.0 0.0 + 1 NaN -1.0 3.0 + 2 NaN -1.0 7.0 + 3 NaN -1.0 13.0 + 4 NaN 0.0 20.0 + 5 NaN 2.0 28.0 + + Difference with 3rd previous row + + >>> df.diff(periods=3) + Seq Fib Sqr + 0 NaN NaN NaN + 1 NaN NaN NaN + 2 NaN NaN NaN + 3 3.0 2.0 15.0 + 4 3.0 4.0 21.0 + 5 3.0 6.0 27.0 + + Difference with following row + + >>> df.diff(periods=-1) + Seq Fib Sqr + 0 -1.0 0.0 -3.0 + 1 -1.0 -1.0 -5.0 + 2 -1.0 -1.0 -7.0 + 3 -1.0 -2.0 -9.0 + 4 -1.0 -3.0 -11.0 + 5 NaN NaN NaN + + See Also + -------- + Series.diff """ bm_axis = self._get_block_manager_axis(axis) new_data = self._data.diff(n=periods, axis=bm_axis) From 2e84d6f5255cdbeb566e6cd8b7ca4bccec5b01f5 Mon Sep 17 00:00:00 2001 From: Fernando Margueirat Date: Sat, 10 Mar 2018 14:21:39 -0500 Subject: [PATCH 02/10] DOC: update the pandas.DataFrame.diff docstring --- pandas/core/frame.py | 53 ++++++++++++++++++++++---------------------- 1 file changed, 27 insertions(+), 26 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index a0fb3f7317b4c..bd4a3984db910 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -4722,10 +4722,10 @@ def melt(self, id_vars=None, value_vars=None, var_name=None, def diff(self, periods=1, axis=0): """ - First discrete difference of object. + First discrete difference of element. - Calculates the difference of a DataFrame object compared with another - object in the DataFrame (default is object in same column of the + Calculates the difference of a DataFrame element compared with another + element in the DataFrame (default is element in same column of the previous row). Parameters @@ -4742,22 +4742,27 @@ def diff(self, periods=1, axis=0): ------- diffed : DataFrame + See Also + -------- + Series.diff + Examples -------- Difference with previous row - >>> df = pd.DataFrame([[1, 1, 1], [2, 1, 4], [3, 2, 9], [4, 3, 16], - ... [5, 5, 25], [6, 8, 36]], columns=['Seq', 'Fib', 'Sqr']) + >>> df = pd.DataFrame({'a': [1, 2, 3, 4, 5, 6], + ... 'b': [1, 1, 2, 3, 5, 8], + ... 'c': [1, 4, 9, 16, 25, 36]}) >>> df - Seq Fib Sqr - 0 NaN NaN NaN - 1 1.0 0.0 3.0 - 2 1.0 1.0 5.0 - 3 1.0 1.0 7.0 - 4 1.0 2.0 9.0 - 5 1.0 3.0 11.0 + a b c + 0 1 1 1 + 1 2 1 4 + 2 3 2 9 + 3 4 3 16 + 4 5 5 25 + 5 6 8 36 >>> df.diff() - Seq Fib Sqr + a b c 0 NaN NaN NaN 1 1.0 0.0 3.0 2 1.0 1.0 5.0 @@ -4768,18 +4773,18 @@ def diff(self, periods=1, axis=0): Difference with previous column >>> df.diff(axis=1) - Seq Fib Sqr - 0 NaN 0.0 0.0 - 1 NaN -1.0 3.0 - 2 NaN -1.0 7.0 - 3 NaN -1.0 13.0 - 4 NaN 0.0 20.0 - 5 NaN 2.0 28.0 + a b c + 0 NaN 0.0 0.0 + 1 NaN -1.0 3.0 + 2 NaN -1.0 7.0 + 3 NaN -1.0 13.0 + 4 NaN 0.0 20.0 + 5 NaN 2.0 28.0 Difference with 3rd previous row >>> df.diff(periods=3) - Seq Fib Sqr + a b c 0 NaN NaN NaN 1 NaN NaN NaN 2 NaN NaN NaN @@ -4790,17 +4795,13 @@ def diff(self, periods=1, axis=0): Difference with following row >>> df.diff(periods=-1) - Seq Fib Sqr + a b c 0 -1.0 0.0 -3.0 1 -1.0 -1.0 -5.0 2 -1.0 -1.0 -7.0 3 -1.0 -2.0 -9.0 4 -1.0 -3.0 -11.0 5 NaN NaN NaN - - See Also - -------- - Series.diff """ bm_axis = self._get_block_manager_axis(axis) new_data = self._data.diff(n=periods, axis=bm_axis) From 785dae1030dbcb332bfc56242c266f85533431e2 Mon Sep 17 00:00:00 2001 From: Fernando Margueirat Date: Sat, 10 Mar 2018 14:54:51 -0500 Subject: [PATCH 03/10] DOC: update the pandas.DataFrame.diff docstring --- pandas/core/frame.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index bd4a3984db910..6560a2a2bab5b 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -4744,7 +4744,7 @@ def diff(self, periods=1, axis=0): See Also -------- - Series.diff + Series.diff: 1st discrete difference of object Examples -------- From 8019d85fb67080330e45222b06fc6c89781ebe2a Mon Sep 17 00:00:00 2001 From: Fernando Margueirat Date: Sat, 10 Mar 2018 15:11:59 -0500 Subject: [PATCH 04/10] DOC: update the pandas.DataFrame.diff docstring --- pandas/core/frame.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 6560a2a2bab5b..57be88542a639 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -4744,7 +4744,8 @@ def diff(self, periods=1, axis=0): See Also -------- - Series.diff: 1st discrete difference of object + DataFrame.pct_change: Percent change over given number of periods. + Series.diff: First discrete difference of object Examples -------- From 15bcb7d36783243637aad4ab70ce858e78276a28 Mon Sep 17 00:00:00 2001 From: Fernando Margueirat Date: Sat, 10 Mar 2018 15:23:41 -0500 Subject: [PATCH 05/10] DOC: update the pandas.DataFrame.diff docstring --- pandas/core/frame.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 57be88542a639..c8a111fb0db54 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -4736,7 +4736,7 @@ def diff(self, periods=1, axis=0): axis : {0 or 'index', 1 or 'columns'}, default 0 Take difference over rows (0) or columns (1). - .. versionadded:: 0.16.1 + .. versionadded:: 0.16.1. Returns ------- From 736310ee49405282f7467629f14f63c9d855d1f8 Mon Sep 17 00:00:00 2001 From: Fernando Margueirat Date: Sat, 10 Mar 2018 20:43:59 -0500 Subject: [PATCH 06/10] DOC: update the pandas.DataFrame.diff docstring --- pandas/core/frame.py | 1 + 1 file changed, 1 insertion(+) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index c8a111fb0db54..cc87f5cb3cd0a 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -4745,6 +4745,7 @@ def diff(self, periods=1, axis=0): See Also -------- DataFrame.pct_change: Percent change over given number of periods. + DataFrame.shift: Shift index by desired number of periods with an optional time freq Series.diff: First discrete difference of object Examples From 2d3242d4423bc02b70d6c49b3cd1ef96b07a33d6 Mon Sep 17 00:00:00 2001 From: Fernando Margueirat Date: Sat, 10 Mar 2018 20:51:47 -0500 Subject: [PATCH 07/10] DOC: update the pandas.DataFrame.diff docstring --- pandas/core/frame.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index cc87f5cb3cd0a..96823b27af732 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -4745,7 +4745,8 @@ def diff(self, periods=1, axis=0): See Also -------- DataFrame.pct_change: Percent change over given number of periods. - DataFrame.shift: Shift index by desired number of periods with an optional time freq + DataFrame.shift: Shift index by desired number of periods with an + optional time freq Series.diff: First discrete difference of object Examples From 51206f5b1ad73db8545723c269d589a93783841a Mon Sep 17 00:00:00 2001 From: Fernando Margueirat Date: Sat, 10 Mar 2018 20:58:08 -0500 Subject: [PATCH 08/10] DOC: update the pandas.DataFrame.diff docstring --- pandas/core/frame.py | 1 + 1 file changed, 1 insertion(+) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 96823b27af732..c52fc0593d593 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -4764,6 +4764,7 @@ def diff(self, periods=1, axis=0): 3 4 3 16 4 5 5 25 5 6 8 36 + >>> df.diff() a b c 0 NaN NaN NaN From 2802e1b79c60d4c78823dbe9a40a13f549a242e2 Mon Sep 17 00:00:00 2001 From: Fernando Margueirat Date: Sat, 10 Mar 2018 21:24:00 -0500 Subject: [PATCH 09/10] DOC: update the pandas.DataFrame.diff docstring --- pandas/core/frame.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index c52fc0593d593..2b2f068d67f24 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -4746,7 +4746,7 @@ def diff(self, periods=1, axis=0): -------- DataFrame.pct_change: Percent change over given number of periods. DataFrame.shift: Shift index by desired number of periods with an - optional time freq + optional time freq Series.diff: First discrete difference of object Examples From 3a07a0fc078d6cae620ecaad14847cfc8a8b9c10 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Sun, 11 Mar 2018 07:34:42 -0500 Subject: [PATCH 10/10] Cleanup --- pandas/core/frame.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 2b2f068d67f24..bf926e1bca147 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -4725,8 +4725,8 @@ def diff(self, periods=1, axis=0): First discrete difference of element. Calculates the difference of a DataFrame element compared with another - element in the DataFrame (default is element in same column of the - previous row). + element in the DataFrame (default is the element in the same column + of the previous row). Parameters ---------- @@ -4744,10 +4744,10 @@ def diff(self, periods=1, axis=0): See Also -------- + Series.diff: First discrete difference for a Series. DataFrame.pct_change: Percent change over given number of periods. DataFrame.shift: Shift index by desired number of periods with an - optional time freq - Series.diff: First discrete difference of object + optional time freq. Examples --------