diff

diff(x: array, /, *, axis: int = -1, n: int = 1, prepend: array | None = None, append: array | None = None) → array

Calculates the n-th discrete forward difference along a specified axis.

Parameters:

  • x (array) – input array. Should have a numeric data type.

  • axis (int) – axis along which to compute differences. A valid axis must be an integer on the interval [-N, N), where N is the rank (number of dimensions) of x. If an axis is specified as a negative integer, the function must determine the axis along which to compute differences by counting backward from the last dimension (where -1 refers to the last dimension). If provided an invalid axis, the function must raise an exception. Default: -1.

  • n (int) – number of times to recursively compute differences. Default: 1.

  • prepend (Optional[array]) – values to prepend to a specified axis prior to computing differences. Must have the same shape as x, except for the axis specified by axis which may have any size. Should have the same data type as x. Default: None.

  • append (Optional[array]) – values to append to a specified axis prior to computing differences. Must have the same shape as x, except for the axis specified by axis which may have any size. Should have the same data type as x. Default: None.

Returns:

out (array) – an array containing the n-th differences. Should have the same data type as x. Must have the same shape as x, except for the axis specified by axis which must have a size determined as follows:

  • Let M be the number of elements along an axis specified by axis.

  • Let N1 be the number of prepended values along an axis specified by axis.

  • Let N2 be the number of appended values along an axis specified by axis.

  • The final size of the axis specified by axis must be M + N1 + N2 - n.

Notes

  • The first-order differences are given by out[i] = x[i+1] - x[i] along a specified axis. Higher-order differences must be calculated recursively (e.g., by calling diff(out, axis=axis, n=n-1)).

  • If a conforming implementation chooses to support prepend and append arrays which have a different data type than x, behavior is unspecified and thus implementation-defined. Implementations may choose to type promote (Type Promotion Rules), cast prepend and/or append to the same data type as x, or raise an exception.

New in version 2024.12.