# dask.dataframe.Index.diff

#### Index.diff(periods=1, axis=0)

First discrete difference of element.

This docstring was copied from pandas.DataFrame.diff.

Some inconsistencies with the Dask version may exist.

#### NOTE
Pandas currently uses an `object`-dtype column to represent
boolean data with missing values. This can cause issues for
boolean-specific operations, like `|`. To enable boolean-
specific operations, at the cost of metadata that doesn’t match
pandas, use `.astype(bool)` after the `shift`.

Calculates the difference of a DataFrame element compared with another
element in the DataFrame (default is element in previous row).

* **Parameters:**
  **periods**
  : Periods to shift for calculating difference, accepts negative
    values.

  **axis**
  : Take difference over rows (0) or columns (1).
* **Returns:**
  DataFrame
  : First differences of the Series.

#### 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`](dask.dataframe.Series.diff.html.md#dask.dataframe.Series.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

```pycon
>>> 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

```pycon
>>> df.diff(axis=1)
    a  b   c
0 NaN  0   0
1 NaN -1   3
2 NaN -1   7
3 NaN -1  13
4 NaN  0  20
5 NaN  2  28
```

Difference with 3rd previous row

```pycon
>>> 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

```pycon
>>> 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
```

Overflow in input dtype

```pycon
>>> df = pd.DataFrame({"a": [1, 0]}, dtype=np.uint8)
>>> df.diff()
       a
0    NaN
1  255.0
```

<!-- !! processed by numpydoc !! -->
