Skip to content

cummax

Cumulative maximum

m = cummax(A)

  • A is an array of any number of dimensions.
  • The output argument m contains the cumulative maximums and has the same size as A.
  • The cumulative maximums are obtained from vectors along the first non-singleton dimension of A.

Example 1: 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 maximums of elements of A(:,1).

% Matrix of size [3,4]
A=reshape(1:12,3,4)
% Cumulative maximums
m=cummax(A)
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

m = cummax(A, dim)

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

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

% Matrix of size [3,4]
A=reshape(1:12,3,4)
% Cumulative maximums along 2nd dimension
m=cummax(A,2)
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

m = cummax(A, option)

  • option should be either 'reverse', 'forward', 'includenan' or 'omitnan'.
  • These options control the operation direction, or whether or not NaN should be included in the operation.
  • For details, see Tables 1 and 2 below.

Note

By default, cummax and cummax omit NaN, whereas cumsum and cumprod include NaN.

Example 3: Cumulative maximums of the same vector but with different options. Note that cummax by default omits NaN, therefore NaN elements in a is ignored when cummax is called for the first time below. In the second call of cummax, NaN is included in the comparison. Therefore, NaN appears in the output since comparison with NaN returns NaN.

a=[1:5 nan 6]
% Default options
cummax(a)
% Include nan, forward direction
cummax(a, 'includenan')
% Omit nan, forward direction
cummax(a, 'omitnan')
% Forward direction, include nan
cummax(a, 'forward')
% Reverse direction, include nan
cummax(a, 'reverse')
a =
 1.000   2.000   3.000   4.000   5.000    nan   6.000

ans =
 1.000   2.000   3.000   4.000   5.000   5.000   6.000

ans =
 1.000   2.000   3.000   4.000   5.000    nan    nan

ans =
 1.000   2.000   3.000   4.000   5.000   5.000   6.000

ans =
 1.000   2.000   3.000   4.000   5.000   5.000   6.000

ans =
 6.000   6.000   6.000   6.000   6.000   6.000   6.000

Table 1: Options for operation direction.

Option value Meaning Default
'forward' The cumulative maximums are obtained in the forward direction. YES
'reverse' The cumulative maximums are obtained in the reverse direction. NO

Table 2: Options for including or omitting NaN.

Option value Meaning Default
'omitnan' Omit NaN in the opeartion YES
'includenan' Include NaN in the operation NO

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 whether or not NaN should be included.
  • See Tables 1 and 2 above for 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 overwrite option1 if they contradict each other.
  • See Tables 1 and 2 above 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 overwrite option1 if they contradict each other.
  • See Tables 1 and 2 above for available options.