cumprod

Cumulative product

Description

example

B = cumprod(A) returns the cumulative product of A starting at the beginning of the first array dimension in A whose size does not equal 1.

• If A is a vector, then cumprod(A) returns a vector containing the cumulative product of the elements of A.

• If A is a matrix, then cumprod(A) returns a matrix containing the cumulative products for each column of A.

• If A is a multidimensional array, then cumprod(A) acts along the first nonsingleton dimension.

example

B = cumprod(A,dim) returns the cumulative product along dimension dim. For example, if A is a matrix, then cumprod(A,2) returns the cumulative product of each row.

example

B = cumprod(___,direction) optionally specifies the direction using any of the previous syntaxes. You must specify A, and optionally can specify dim. For instance, cumprod(A,2,'reverse') returns the cumulative product within the rows of A by working from end to beginning of the second dimension.

example

B = cumprod(___,nanflag) specifies whether to include or omit NaN values from the calculation for any of the previous syntaxes. cumprod(A,'includenan') includes NaN values in the calculation while cumprod(A,'omitnan') ignores them.

Examples

collapse all

Find the cumulative product of the integers from 1 to 5. The element B(2) is the product of A(1) and A(2), while B(5) is the product of elements A(1) through A(5).

A = 1:5;
B = cumprod(A)
B = 1×5

1     2     6    24   120

Define a 3-by-3 matrix whose elements correspond to their linear indices.

A = [1 4 7; 2 5 8; 3 6 9]
A = 3×3

1     4     7
2     5     8
3     6     9

Find the cumulative product of the columns of A. The element B(5) is the product of A(4) and A(5), while B(9) is the product of A(7) , A(8), and A(9).

B = cumprod(A)
B = 3×3

1     4     7
2    20    56
6   120   504

Define a 2-by-3 matrix whose elements correspond to their linear indices.

A = [1 3 5; 2 4 6]
A = 2×3

1     3     5
2     4     6

Find the cumulative product of the rows of A. The element B(3) is the product of A(1) and A(3), while B(5) is the product of A(1), A(3), and A(5).

B = cumprod(A,2)
B = 2×3

1     3    15
2     8    48

Create an array of logical values.

A = [true false true; true true false]
A = 2x3 logical array

1   0   1
1   1   0

Find the cumulative product of the rows of A.

B = cumprod(A,2)
B = 2×3

1     0     0
1     1     0

The output has type double.

class(B)
ans =
'double'

Create a 3-by-3 matrix of random integers between 1 and 10.

rng default;
A = randi([1,10],3)
A = 3×3

9    10     3
10     7     6
2     1    10

Calculate the cumulative product along the columns. Specify the 'reverse' option to work from bottom to top in each column. The result is the same size as A.

B = cumprod(A,'reverse')
B = 3×3

180    70   180
20     7    60
2     1    10

Create a vector containing NaN values and compute the cumulative products. By default, cumprod includes NaN values. When you include NaN values in the calculation, the cumulative product becomes NaN as soon as the first NaN value in A is encountered.

A = [1 3 NaN 2 4 NaN];
B = cumprod(A)
B = 1×6

1     3   NaN   NaN   NaN   NaN

Ignore NaN values in the cumulative product calculation using the 'omitnan' option.

B = cumprod(A,'omitnan')
B = 1×6

1     3     3     6    24    24

Input Arguments

collapse all

Input array, specified as a vector, matrix, or multidimensional array.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical
Complex Number Support: Yes

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

Consider a two-dimensional input array, A.

• cumprod(A,1) works on successive elements in the columns of A and returns the cumulative products of each column.

• cumprod(A,2) works on successive elements in the rows of A and returns the cumulative products of each row. cumprod returns A if dim is greater than ndims(A).

Direction of cumulation, specified as 'forward' (default) or 'reverse'.

• 'forward' works from 1 to end of the active dimension.

• 'reverse' works from end to 1 of the active dimension.

NaN condition, specified as one of these values:

• 'includenan' — Include NaN values from the input when computing each product, resulting in NaN values in the output.

• 'omitnan' — Ignore NaN values in the input. The product of elements containing NaN values is the product of all non-NaN elements. If all elements are NaN, then cumprod returns 1.

Output Arguments

collapse all

Cumulative product array, returned as a vector, matrix, or multidimensional array of the same size as the input array A.

The class of B is the same as the class of A except if A is logical, in which case B is double.

collapse all

First Nonsingleton Dimension

The first nonsingleton dimension is the first dimension of an array whose size is not equal to 1.

For example:

• If X is a 1-by-n row vector, then the second dimension is the first nonsingleton dimension of X.

• If X is a 1-by-0-by-n empty array, then the second dimension is the first nonsingleton dimension of X.

• If X is a 1-by-1-by-3 array, then the third dimension is the first nonsingleton dimension of X.

Tips

• Many cumulative functions in MATLAB® support the 'reverse' option. This option allows quick directional calculations without needing a flip or reflection of the input array.