Skip to main content
`Ctrl`+`K`

# numpy.ma.diff

ma.diff(a, /, n=1, axis=-1, prepend=<no value>, append=<no value>)

  Calculate the n-th discrete difference along the given axis. The first difference is given by `out[i] = a[i+1] - a[i]` along the given axis, higher differences are calculated by using `diff` recursively. Preserves the input mask.

  Parameters:
    a array_like

      Input array

    n int, optional

      The number of times values are differenced. If zero, the input is returned as-is.

    axis int, optional

      The axis along which the difference is taken, default is the last axis.

    prepend, append array_like, optional

      Values to prepend or append to a along axis prior to performing the difference. Scalar values are expanded to arrays with length 1 in the direction of axis and the shape of the input array in along all other axes. Otherwise the dimension and shape must match a except along axis.

  Returns:
    diff MaskedArray

      The n-th differences. The shape of the output is the same as a except along axis where the dimension is smaller by n. The type of the output is the same as the type of the difference between any two elements of a. This is the same as the type of a in most cases. A notable exception is `datetime64`, which results in a `timedelta64` output array.

  See also

  `numpy.diff`

    Equivalent function in the top-level NumPy module.

  Notes

  Type is preserved for boolean arrays, so the result will contain False when consecutive elements are the same and True when they differ.

  For unsigned integer arrays, the results will also be unsigned. This should not be surprising, as the result is consistent with calculating the difference directly:

      >>> u8_arr = np.array([1, 0], dtype=np.uint8)
      >>> np.ma.diff(u8_arr)
      masked_array(data=[255],
                   mask=False,
             fill_value=np.uint64(999999),
                  dtype=uint8)
      >>> u8_arr[1,...] - u8_arr[0,...]
      np.uint8(255)

  If this is not desirable, then the array should be cast to a larger integer type first:

      >>> i16_arr = u8_arr.astype(np.int16)
      >>> np.ma.diff(i16_arr)
      masked_array(data=[-1],
                   mask=False,
             fill_value=np.int64(999999),
                  dtype=int16)

  Examples

      >>> import numpy as np
      >>> a = np.array([1, 2, 3, 4, 7, 0, 2, 3])
      >>> x = np.ma.masked_where(a < 2, a)
      >>> np.ma.diff(x)
      masked_array(data=[--, 1, 1, 3, --, --, 1],
              mask=[ True, False, False, False,  True,  True, False],
          fill_value=999999)

      >>> np.ma.diff(x, n=2)
      masked_array(data=[--, 0, 2, --, --, --],
                  mask=[ True, False, False,  True,  True,  True],
          fill_value=999999)

      >>> a = np.array([[1, 3, 1, 5, 10], [0, 1, 5, 6, 8]])
      >>> x = np.ma.masked_equal(a, value=1)
      >>> np.ma.diff(x)
      masked_array(
          data=[[--, --, --, 5],
                  [--, --, 1, 2]],
          mask=[[ True,  True,  True, False],
                  [ True,  True, False, False]],
          fill_value=1)

      >>> np.ma.diff(x, axis=0)
      masked_array(data=[[--, --, --, 1, -2]],
              mask=[[ True,  True,  True, False, False]],
          fill_value=1)