diff

Differences and approximate derivatives

Syntax

Y = diff(X)

Y = diff(X,n)

Y = diff(X,n,dim)

Description

Y = diff(X) calculates differences between adjacent elements of X. By default, diff operates along the first array dimension whose size does not equal 1.

If X is a vector of length m, then Y = diff(X) returns a vector of length m-1. The elements of Y are the differences between adjacent elements of X.
```
Y = [X(2)-X(1) X(3)-X(2) ... X(m)-X(m-1)]
```
If X is a nonempty, nonvector p-by-m matrix, then Y = diff(X) returns a matrix of size (p-1)-by-m, whose elements are the differences between the rows of X.
```
Y = [X(2,:)-X(1,:); X(3,:)-X(2,:); ... X(p,:)-X(p-1,:)]
```
If X is a 0-by-0 empty matrix, then Y = diff(X) returns a 0-by-0 empty matrix.
If X is a p-by-m table or timetable, then Y = diff(X) returns a table or timetable of size (p-1)-by-m, whose elements are the differences between the rows of X. If X is a 1-by-m table or timetable, then the size of Y is 0-by-m. (since R2023a)

example

Y = diff(X,n) calculates the nth difference by applying the diff(X) operator recursively n times. In practice, this means diff(X,2) is the same as diff(diff(X)).

example

Y = diff(X,n,dim) is the nth difference calculated along the dimension specified by dim. The dim input is a positive integer scalar.

example

Examples

collapse all

Differences Between Vector Elements

Open Live Script

Create a vector, then compute the differences between the elements.

X = [1 1 2 3 5 8 13 21];
Y = diff(X)

Y = 1×7

     0     1     1     2     3     5     8

Note that Y has one fewer element than X.

Differences Between Matrix Rows

Open Live Script

Create a 3-by-3 matrix, then compute the first difference between the rows.

X = [1 1 1; 5 5 5; 25 25 25];
Y = diff(X)

Y = 2×3

     4     4     4
    20    20    20

Y is a 2-by-3 matrix.

Multiple Differences

Open Live Script

Create a vector and compute the second-order difference between the elements.

X = [0 5 15 30 50 75 105];
Y = diff(X,2)

Y = 1×5

     5     5     5     5     5

Differences Between Matrix Columns

Open Live Script

Create a 3-by-3 matrix, then compute the first-order difference between the columns.

X = [1 3 5;7 11 13;17 19 23];
Y = diff(X,1,2)

Y is a 3-by-2 matrix.

Approximate Derivatives with diff

Open Live Script

Use the diff function to approximate partial derivatives with the syntax Y = diff(f)/h, where f is a vector of function values evaluated over some domain, X, and h is an appropriate step size.

For example, the first derivative of sin(x) with respect to x is cos(x), and the second derivative with respect to x is -sin(x). You can use diff to approximate these derivatives.

h = 0.001;       % step size
X = -pi:h:pi;    % domain
f = sin(X);      % range
Y = diff(f)/h;   % first derivative
Z = diff(Y)/h;   % second derivative
plot(X(:,1:length(Y)),Y,'r',X,f,'b', X(:,1:length(Z)),Z,'k')

Figure contains an axes object. The axes object contains 3 objects of type line.

In this plot the blue line corresponds to the original function, sin. The red line corresponds to the calculated first derivative, cos, and the black line corresponds to the calculated second derivative, -sin.

Differences Between Datetime Values

Open Live Script

Create a sequence of equally-spaced datetime values, and find the time differences between them.

t1 = datetime('now');
t2 = t1 + minutes(5);
t = t1:minutes(1.5):t2

t = 1x4 datetime
   05-Sep-2024 15:40:50   05-Sep-2024 15:42:20   05-Sep-2024 15:43:50   05-Sep-2024 15:45:20

dt = diff(t)

dt = 1x3 duration
   00:01:30   00:01:30   00:01:30

diff returns a duration array.

Input Arguments

collapse all

`X` — Input array
vector | matrix | multidimensional array | table | timetable

Input array, specified as a vector, matrix, multidimensional array, table, or timetable. X can be a numeric array, logical array, datetime array, or duration array, or a table or timetable whose variables have any of these data types.

Complex Number Support: Yes

`n` — Difference order
positive integer scalar | `[]`

Difference order, specified as a positive integer scalar or []. The default value of n is 1.

The behavior of diff when n is larger than the dimension being operated on depends on the syntax being used:

With diff(X,n), where n is larger than the first non-singleton dimension, diff reduces the size of that dimension to 1 and then continues taking differences along the next non-singleton dimension.
With diff(X,n,dim), where n >= size(X,dim), diff returns an empty array.

`dim` — Dimension to operate along
positive integer scalar

Dimension to operate along, specified as a positive integer scalar. If you do not specify the dimension, then the default is the first array dimension whose size does not equal 1.

Consider a two-dimensional p-by-m input array, A:

diff(A,1,1) works on successive elements in the columns of A and returns a (p-1)-by-m difference matrix.
diff(A,1,2) works on successive elements in the rows of A and returns a p-by-(m-1) difference matrix.

diff(A,1,1) column-wise computation and diff(A,1,2) row-wise computation

Output Arguments

collapse all

`Y` — Difference array
scalar | vector | matrix | multidimensional array | table | timetable

Difference array, returned as a scalar, vector, matrix, multidimensional array, table, or timetable. If X is a nonempty array, then the dimension of X acted on by diff is reduced in size by n in the output.

Extended Capabilities

Tall Arrays
Calculate with arrays that have more rows than fit in memory.

This function supports tall arrays with the limitations:

You must use the three-input syntax Y = diff(X,N,dim).

For more information, see Tall Arrays.

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

If supplied, the arguments representing the number of times to apply diff and the dimension along which to calculate the difference must be constants.
See Variable-Sizing Restrictions for Code Generation of Toolbox Functions (MATLAB Coder).
Code generation does not support sparse matrix inputs for this function.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The diff function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a

expand all

R2023a: Perform calculations directly on tables and timetables

The diff function can calculate on all variables within a table or timetable without indexing to access those variables. All variables must have data types that support the calculation. For more information, see Direct Calculations on Tables and Timetables.

R2022a: Improved performance with large number of elements

The diff function shows improved performance when operating on vectors with at least 10⁵ elements or when operating along the first or second dimension of matrices and multidimensional arrays with at least 5 x 10⁵ elements.

For example, this code constructs a double with 2.5 x 10⁷ elements and calculates differences between adjacent elements. The code is approximately 2.4x faster than in the previous release:

function timingDiff
rng default
N = 5000;
A = rand(N);

tic
for k = 1:40
   D = diff(A);
end
toc
end

The approximate execution times are:

R2021b: 2.43 s

R2022a: 1.00 s

The code was timed on a Windows^® 10, Intel^® Xeon^® CPU E5-1650 v4 @ 3.60 GHz test system by calling the timingDiff function.

diff

Syntax

Description

Examples

Differences Between Vector Elements

Differences Between Matrix Rows

Multiple Differences

Differences Between Matrix Columns

Approximate Derivatives with diff

Differences Between Datetime Values

Input Arguments

X — Input array vector | matrix | multidimensional array | table | timetable

n — Difference order positive integer scalar | []

dim — Dimension to operate along positive integer scalar

Output Arguments

Y — Difference array scalar | vector | matrix | multidimensional array | table | timetable

Extended Capabilities

Tall Arrays Calculate with arrays that have more rows than fit in memory.

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

Thread-Based Environment Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

GPU Arrays Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Distributed Arrays Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Version History

R2023a: Perform calculations directly on tables and timetables

R2022a: Improved performance with large number of elements

See Also

`X` — Input array
vector | matrix | multidimensional array | table | timetable

`n` — Difference order
positive integer scalar | `[]`

`dim` — Dimension to operate along
positive integer scalar

`Y` — Difference array
scalar | vector | matrix | multidimensional array | table | timetable

Tall Arrays
Calculate with arrays that have more rows than fit in memory.

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.