diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 2d181e826c2a9..483d7746b3e2d 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -7019,40 +7019,14 @@ def melt( # ---------------------------------------------------------------------- # Time series-related - def diff(self, periods: int = 1, axis: Axis = 0) -> "DataFrame": - """ - 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 calculating difference, accepts negative - values. - axis : {0 or 'index', 1 or 'columns'}, default 0 - Take difference over rows (0) or columns (1). - - Returns - ------- - 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. - - Notes - ----- - For boolean dtypes, this uses :meth:`operator.xor` rather than - :meth:`operator.sub`. - - Examples - -------- + @doc( + Series.diff, + klass="Dataframe", + extra_params="axis : {0 or 'index', 1 or 'columns'}, default 0\n " + "Take difference over rows (0) or columns (1).\n", + other_klass="Series", + examples=dedent( + """ Difference with previous row >>> df = pd.DataFrame({'a': [1, 2, 3, 4, 5, 6], @@ -7108,7 +7082,18 @@ def diff(self, periods: int = 1, axis: Axis = 0) -> "DataFrame": 3 -1.0 -2.0 -9.0 4 -1.0 -3.0 -11.0 5 NaN NaN NaN - """ + + Overflow in input dtype + + >>> df = pd.DataFrame({'a': [1, 0]}, dtype=np.uint8) + >>> df.diff() + a + 0 NaN + 1 255.0""" + ), + ) + def diff(self, periods: int = 1, axis: Axis = 0) -> "DataFrame": + bm_axis = self._get_block_manager_axis(axis) self._consolidate_inplace() diff --git a/pandas/core/series.py b/pandas/core/series.py index e107b66d33b1c..c9c63b8342657 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -2293,38 +2293,12 @@ def cov(self, other, min_periods=None) -> float: return np.nan return nanops.nancov(this.values, other.values, min_periods=min_periods) - def diff(self, periods: int = 1) -> "Series": - """ - First discrete difference of element. - - Calculates the difference of a Series element compared with another - element in the Series (default is element in previous row). - - Parameters - ---------- - periods : int, default 1 - Periods to shift for calculating difference, accepts negative - values. - - Returns - ------- - Series - First differences of the Series. - - See Also - -------- - Series.pct_change: Percent change over given number of periods. - Series.shift: Shift index by desired number of periods with an - optional time freq. - DataFrame.diff: First discrete difference of object. - - Notes - ----- - For boolean dtypes, this uses :meth:`operator.xor` rather than - :meth:`operator.sub`. - - Examples - -------- + @doc( + klass="Series", + extra_params="", + other_klass="DataFrame", + examples=dedent( + """ Difference with previous row >>> s = pd.Series([1, 1, 2, 3, 5, 8]) @@ -2358,6 +2332,51 @@ def diff(self, periods: int = 1) -> "Series": 4 -3.0 5 NaN dtype: float64 + + Overflow in input dtype + + >>> s = pd.Series([1, 0], dtype=np.uint8) + >>> s.diff() + 0 NaN + 1 255.0 + dtype: float64""" + ), + ) + def diff(self, periods: int = 1) -> "Series": + """ + First discrete difference of element. + + Calculates the difference of a {klass} element compared with another + element in the {klass} (default is element in previous row). + + Parameters + ---------- + periods : int, default 1 + Periods to shift for calculating difference, accepts negative + values. + {extra_params} + Returns + ------- + {klass} + First differences of the Series. + + See Also + -------- + {klass}.pct_change: Percent change over given number of periods. + {klass}.shift: Shift index by desired number of periods with an + optional time freq. + {other_klass}.diff: First discrete difference of object. + + Notes + ----- + For boolean dtypes, this uses :meth:`operator.xor` rather than + :meth:`operator.sub`. + The result is calculated according to current dtype in {klass}, + however dtype of the result is always float64. + + Examples + -------- + {examples} """ result = algorithms.diff(self.array, periods) return self._constructor(result, index=self.index).__finalize__(