pandas.Series.diff — pandas 3.0.0rc0+33.g1fd184de2a documentation (original) (raw)

Series.diff(periods=1)[source]#

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:

periodsint, default 1

Periods to shift for calculating difference, accepts negative values.

Returns:

Series

First differences of the Series.

Notes

For boolean dtypes, this uses operator.xor() rather thanoperator.sub(). The result is calculated according to current dtype in Series, however dtype of the result is always float64.

Examples

Difference with previous row

s = pd.Series([1, 1, 2, 3, 5, 8]) s.diff() 0 NaN 1 0.0 2 1.0 3 1.0 4 2.0 5 3.0 dtype: float64

Difference with 3rd previous row

s.diff(periods=3) 0 NaN 1 NaN 2 NaN 3 2.0 4 4.0 5 6.0 dtype: float64

Difference with following row

s.diff(periods=-1) 0 0.0 1 -1.0 2 -1.0 3 -2.0 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