[TOC]

`cummax`

Cumulative maximum

Usage

`m = cummax(A)`

A is a numeric or character array.
The output m contains the cumulative maxima and has the same size as A.
If A is complex, it first compares the magnitudes (i.e., moduli) of the complex numbers. If they have the same magnitudes, then it compares their phase angles.
A cumulative maximum is obtained by comparing elements in a vector along the first non-singleton dimension of A.

`m = cummax(A, dim)`

A is a numeric or character array.
dim should be a positive integer scalar, not equal to inf nor nan.
It obtains the cumulative maxima along the dim-th dimension of A.
If size(A, dim) == 1 or dim > ndims(A), then m is the same as A.

`m = cummax(A, option)`

A is a numeric or character array.
option should be either 'reverse', 'forward', 'includenan' or 'omitnan'.
Each of these options controls the operation direction or inclusion of NaN in the operation.
See the table below for available options.

`m = cummax(A, dim, option)`

Same as m = cummax(A, dim) above, except that an option can be specified for controlling the operation direction or inclusion of NaN in the operation.
See the table below for the available options.

`m = cummax(A, option1, option2)`

Same as m = cummax(A, option) above, except that two options can be specified at the same time.
option2 will override option1 if they contradict with each other.
See the table below for available options.

`m = cummax(A, dim, option1, option2)`

Same as m = cummax(A, dim, option) above, except that two options can be specified at the same time.
option2 will override option1 if they contradict with each other.
See the table below for available options.

Option	Meaning	Default
`'forward'`	The cumulative maxima are obtained in the forward direction.	Default for `cumsum`, `cumprod`, `cummin`, `cummax`
`'reverse'`	The cumulative maxima are obtained in the reverse direction.	Not default for `cumsum`, `cumprod`, `cummin` and `cummax`
`'includenan`'	Include `NaN` in the calculation	Default for `cumsum`, `cumprod`
`'omitnan`'	Omit `NaN` in the calculation	Default for `cummax`, `cummin`

Examples

In the following, the first non-singleton dimension of A is the first dimension. The maximum operation is performed along the vertical direction. For instance, m(:,1) contains cumulative maxima of elements of A(:,1).

Input

% Matrix of size [3,4]
A = reshape(1:12,3,4)
% Cumulative maxima
m = cummax(A)

Output

A =
 1.000   4.000   7.000   10.00
 2.000   5.000   8.000   11.00
 3.000   6.000   9.000   12.00

m =
 1.000   4.000   7.000   10.00
 2.000   5.000   8.000   11.00
 3.000   6.000   9.000   12.00

In the following, the maximum operation is performed along the horizontal direction (2nd dimension). For instance, m(1,:) contains cumulative maxima of elements of A(1,:).

Input

% Matrix of size [3,4]
A = reshape(1:12,3,4)
% Cumulative maxima along 2nd dimension
m = cummax(A,2)

Output

A =
 1.000   4.000   7.000   10.00
 2.000   5.000   8.000   11.00
 3.000   6.000   9.000   12.00

m =
 1.000   4.000   7.000   10.00
 2.000   5.000   8.000   11.00
 3.000   6.000   9.000   12.00

Cumulative maxima of the same vector but with different options. Note that cummax by default omits NaN, therefore the NaN in a is ignored in the first call of cummax. In the second call of cummax, NaN is included in the comparison. Therefore, NaN appears in the output since comparison with NaN returns NaN.

Input

a = [1:5 nan 6]

% Default options
disp('Omit nan, forward')
cummax(a)

% Include nan, forward direction
disp('Include nan, forward.')
cummax(a, 'includenan')

% Omit nan, forward direction
disp('Omit nan, forward')
cummax(a, 'omitnan')

% Omit nan, forward direction
disp('Omit nan, forward')
cummax(a, 'forward')

% Omit nan, reverse direction
disp('Omit nan, reverse')
cummax(a, 'reverse')

Output

a = 
 1.0000   2.0000   3.0000   4.0000   5.0000   NaN      6.0000

Omit nan, forward

ans = 
 1.0000   2.0000   3.0000   4.0000   5.0000   5.0000   6.0000

Include nan, forward.

ans = 
 1.0000   2.0000   3.0000   4.0000   5.0000   NaN      NaN   

Omit nan, forward

ans = 
 1.0000   2.0000   3.0000   4.0000   5.0000   5.0000   6.0000

Omit nan, forward

ans = 
 1.0000   2.0000   3.0000   4.0000   5.0000   5.0000   6.0000

Omit nan, reverse

ans = 
 6.0000   6.0000   6.0000   6.0000   6.0000   6.0000   6.0000