Skip to content

cumsum

Cumulative sum

s = cumsum(A)

  • A is an array of any number of dimensions.
  • The output argument s contains the cumulative sums and has the same size as A.
  • The cumulative sums 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 sum operation is performed along the vertical direction. For instance, s(:,1) contains cumulative sums of elements of A(:,1).

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

s =
 1.000   4.000   7.000   10.00
 3.000   9.000   15.00   21.00
 6.000   15.00   24.00   33.00

s = cumsum(A, dim)

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

Example 2: In the following, The sum operation is performed along the horizontal direction (2nd dimension). For instance, s(1,:) contains cumulative sums of elements of A(1,:).

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

s =
 1.000   5.000   12.00   22.00
 2.000   7.000   15.00   26.00
 3.000   9.000   18.00   30.00

s = cumsum(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, cummin and cummax omit NaN, whereas cumsum and cumprod include NaN.

Example 3: Cumulative sums of the same vector but with different options.

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

ans =
 1.000   3.000   6.000   10.00   15.00    nan    nan

ans =
 1.000   3.000   6.000   10.00   15.00    nan    nan

ans =
 1.000   3.000   6.000   10.00   15.00   15.00   21.00

ans =
 1.000   3.000   6.000   10.00   15.00    nan    nan

ans =
 nan    nan    nan    nan    nan    nan   6.000

Table 1: Options for operation direction.

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

Table 2: Options for including or omitting NaN.

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

s = cumsum(A, dim, option)

  • Same as s = cumsum(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.

s = cumsum(A, option1, option2)

  • Same as s = cumsum(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.

s = cumsum(A, dim, option1, option2)

  • Same as s = cumsum(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.