From 302fda452f1f67e4839b6d46a3eab2cf824b64ca Mon Sep 17 00:00:00 2001 From: adatasetaday <32177771+adatasetaday@users.noreply.github.com> Date: Sun, 11 Mar 2018 08:36:21 -0400 Subject: [PATCH] DOC: update the pandas.DataFrame.diff docstring (#20227) * DOC: update the pandas.DataFrame.diff docstring * DOC: update the pandas.DataFrame.diff docstring * DOC: update the pandas.DataFrame.diff docstring * DOC: update the pandas.DataFrame.diff docstring * DOC: update the pandas.DataFrame.diff docstring * DOC: update the pandas.DataFrame.diff docstring * DOC: update the pandas.DataFrame.diff docstring * DOC: update the pandas.DataFrame.diff docstring * DOC: update the pandas.DataFrame.diff docstring * Cleanup --- pandas/core/frame.py | 76 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 73 insertions(+), 3 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 0f94b75a37a74..e3164ca0262aa 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -4770,20 +4770,90 @@ 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 element. + + Calculates the difference of a DataFrame element compared with another + element in the DataFrame (default is the element in the 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). - .. versionadded:: 0.16.1 + .. versionadded:: 0.16.1. Returns ------- diffed : DataFrame + + 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. + + Examples + -------- + Difference with previous row + + >>> 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 + 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() + a b c + 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) + 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) + a b c + 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) + 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 """ bm_axis = self._get_block_manager_axis(axis) new_data = self._data.diff(n=periods, axis=bm_axis)