cummax - Cumulative maximum - MATLAB (original) (raw)

Syntax

Description

`M` = cummax([A](#budq9jn-A)) returns the cumulative maximum elements of A.

If A is a vector, then M is a vector of the same size and type and contains the cumulative maxima ofA.
If A is a matrix, then M is a matrix of the same size and type and contains the cumulative maxima in each column of A.
If A is a multidimensional array, thenM is an array of the same size and type and contains the cumulative maxima along the first array dimension ofA whose size does not equal 1.
If A is a table or timetable, then cummax(A) returns a table or timetable containing the cumulative maxima of each variable. (since R2023a)

`M` = cummax([A](#budq9jn-A),[dim](#budq9jn-dim)) returns the cumulative maxima along dimension dim. For example, if A is a matrix, then cummax(A,2) returns the cumulative maxima along the rows of A.

example

`M` = cummax(___,[direction](#budq9jn-direction)) specifies the direction for any of the previous syntaxes. For example,cummax(A,2,"reverse") returns the cumulative maxima ofA by working from end to beginning of the second dimension ofA.

example

`M` = cummax(___,[nanflag](#budq9jn-nanflag)) specifies whether to omit or include NaN values inA. For example, cummax(A,"includenan") includes NaN values when computing each maximum. By default,cummax omits NaN values.

example

Examples

collapse all

Find the cumulative maxima of a 1-by-10 vector of random integers.

v = 1×10

 9    10     2    10     7     1     3     6    10    10

M = 1×10

 9    10    10    10    10    10    10    10    10    10

Find the cumulative maxima of the columns of a 3-by-3 matrix.

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

A = 3×3

 3     5     2
 1     6     3
 7     8     1

M = 3×3

 3     5     2
 3     6     3
 7     8     3

Find the cumulative maxima of the rows of a 3-by-3 matrix.

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

A = 3×3

 3     5     2
 1     6     3
 7     8     1

M = 3×3

 3     5     5
 1     6     6
 7     8     8

Calculate the cumulative maxima in the third dimension of a 2-by-2-by-3 array. Specify direction as "reverse" to work from the end of the third dimension to the beginning.

A = cat(3,[1 2; 3 4],[9 10; 11 12],[5 6; 7 8])

A = A(:,:,1) =

 1     2
 3     4

A(:,:,2) =

 9    10
11    12

A(:,:,3) =

 5     6
 7     8

M = cummax(A,3,"reverse")

M = M(:,:,1) =

 9    10
11    12

M(:,:,2) =

 9    10
11    12

M(:,:,3) =

 5     6
 7     8

Create a matrix containing NaN values.

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

A = 3×4

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

Compute the cumulative maxima of the matrix, including NaN values. For matrix columns that contain any NaN value, the cumulative maximum values are NaN as soon as the first NaN value is encountered.

M = cummax(A,"includenan")

M = 3×4

 3     5   NaN     4
 3     6   NaN     9
 3     6   NaN   NaN

Input Arguments

collapse all

Input array, specified as a vector, matrix, multidimensional array, table, or timetable. For complex elements, cummax compares the magnitude of the elements. If magnitudes are equal, cummax also compares the phase angles.

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:

cummax(A,1) works on successive elements in the columns of A and returns an array of the same size as A with the cumulative maxima in each column.
cummax(A,2) works on successive elements in the rows of A and returns an array of the same size as A with the cumulative maxima in each row.

cummax returns A if dim is greater than ndims(A).

Direction of cumulation, specified as one of these values:

"forward" — Work from1 to end of the operating dimension.
"reverse" — Works fromend to 1 of the operating dimension.

Missing value condition, specified as one of these values:

"omitmissing" or"omitnan" — IgnoreNaN values in A when computing the cumulative maxima. If A has consecutive leading NaN values, then the corresponding elements in M areNaN. "omitmissing" and"omitnan" have the same behavior.
"includemissing" or"includenan" — IncludeNaN values in A when computing the cumulative maxima. Elements inM are NaN as soon as the first NaN value in A is encountered. "includemissing" and"includenan" 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

expand all

This function supports tall arrays with the limitations:

The "reverse" direction is not supported.

For more information, see Tall Arrays.

The cummax function supports GPU array input with these usage notes and limitations:

The nanflag argument is not supported.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced in R2014b

expand all

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

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