cumprod

Cumulative product

Syntax

B = cumprod(A)

B = cumprod(A,dim)

B = cumprod(___,direction)

B = cumprod(___,nanflag)

Description

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 B is a vector of the same size containing the cumulative product of A.

• If A is a matrix, then B is a matrix of the same size containing the cumulative product in each column of A.

• If A is a multidimensional array, then B is an array of the same size containing the cumulative product along the first array dimension of A whose size does not equal 1.

• If A is a table or timetable, then M is a table or timetable of the same size containing the cumulative product in each variable of A. (since R2023a)

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

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

B = cumprod(___,direction) specifies the direction for any of the previous syntaxes. For example, cumprod(A,2,"reverse") returns the cumulative product within the rows of A by working from end to beginning of the second dimension.

B = cumprod(___,nanflag) specifies whether to include or omit NaN values in A. For example, cumprod(A,"omitnan") ignores NaN values when computing each product. By default, cumprod includes NaN values.

Examples

Cumulative Product of Vector

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

Cumulative Product in Matrix Columns

Create 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

Cumulative Product in Matrix Rows

Create 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

Logical Input with Double Output

Create an array of logical values.

A = [true false true; true true false]

A = 2×3 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'

Reverse Cumulative Product

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

Cumulative Product Excluding Missing Values

Create a matrix containing NaN values.

A = [3 5 NaN 4; 2 6 NaN 9; 1 3 0 NaN]

A = 3×4

     3     5   NaN     4
     2     6   NaN     9
     1     3     0   NaN

Compute the cumulative products of the matrix, excluding NaN values. For matrix columns that contain leading NaN values, the cumulative product is 1 until a non-NaN value is encountered.

B = cumprod(A,"omitnan")

B = 3×4

     3     5     1     4
     6    30     1    36
     6    90     0    36

Input Arguments

A — Input array

vector | matrix | multidimensional array | table | timetable

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

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

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 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 — Direction of cumulation

"forward" (default) | "reverse"

Direction of cumulation, specified as one of these values:

• "forward" — Work from 1 to end of the operating dimension.

• "reverse" — Work from end to 1 of the operating dimension.

nanflag — Missing value condition

"includemissing" (default) | "includenan" | "omitmissing" | "omitnan"

Missing value condition, specified as one of these values:

• "includemissing" or "includenan" — Include NaN values in A when computing the cumulative products. Elements in B are NaN as soon as the first NaN value in A is encountered. "includemissing" and "includenan" have the same behavior.

• "omitmissing" or "omitnan" — Ignore NaN values in A when computing the cumulative products. If A has consecutive leading NaN values, then the corresponding elements in B are 1. "omitmissing" and "omitnan" have the same behavior.

Tips

• The "reverse" option in many cumulative functions allows quick directional calculations without requiring a flip or reflection of the input array.

Extended Capabilities

Tall Arrays

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

This function supports tall arrays with the limitations:

The "reverse" direction is not supported.

For more information, see Tall Arrays.

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Logical inputs are not supported. Cast input to double first.

• Code generation does not support sparse matrix inputs for this function.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

• Logical inputs are not supported. Cast input to double first.

• 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 cumprod function supports GPU array input with these usage notes and limitations:

• The nanflag argument is not supported.

• The order of the products within the cumprod operation is not defined. Therefore, the cumprod operation on a gpuArray might not return exactly the same answer as the cumprod operation on the corresponding numeric array. The differences might be significant when A is a signed integer type.

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™.

Usage notes and limitations:

• The order of the products within the cumprod operation is not defined. Therefore, the cumprod operation on a distributed array might not return exactly the same answer as the cumprod operation on the corresponding numeric array. The differences might be significant when A is a signed integer type.

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a

R2023a: Specify missing value condition

Include or omit missing values in the input array when computing cumulative products by using the "includemissing" or "omitmissing" options. These options have the same behavior as the "includenan" and "omitnan" options, respectively.

R2023a: Perform calculations directly on tables and timetables

The cumprod 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.