Skip to main content
`Ctrl`+`K`

# pandas.Series.diff

Series.diff(periods=1)

  First discrete difference of Series elements.

  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

  Equivalent to `self - self.shift(periods)`, except that boolean dtypes use `operator.xor()` rather than `operator.sub()`; the result dtype follows from that operation.

  In particular, because the leading `periods` positions are filled with a missing value, NumPy integer dtypes are cast to floating and NumPy `bool` to `object`.

  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