Documentation

A = accumarray(subs,val) returns array A by accumulating elements of vector val using the subscripts subs. If subs is a column vector, then each element defines a corresponding subscript in the output, which is also a column vector. The accumarray function collects all elements of val that have identical subscripts in subs and stores their sum in the location of A corresponding to that subscript (for index i, A(i)=sum(val(subs(:)==i))). Elements of A whose subscripts do not appear in subs are equal to 0.

For an m-by-n matrix subs, each row represents an n-dimensional subscript into output A. The ith row of subs corresponds to the ith element in the vector val.

A = accumarray(subs,val,sz) returns an array, A, with size sz. Specify sz as a vector of positive integers to define the size of the output, or as [] to let the subscripts in subs determine the size of the output. Use sz when subs does not reference trailing rows, columns, or dimensions that you would like to be present in the output.

A = accumarray(subs,val,sz,fun) applies the function fun to each subset of elements in val that have identical subscripts in subs. Specify fun using the @ symbol (e.g., @mean), or as [] to use the default function, @sum.

A = accumarray(subs,val,sz,fun,fillval) fills all elements of A that are not referred to by any subscript in subs with the scalar value, fillval. The fillval input must have the same class as the values returned by fun. Specify fillval as [] to use the default value, 0.

A = accumarray(subs,val,sz,fun,fillval,issparse) returns an array, A, that is sparse if the scalar issparse is true or 1, and full if issparse is false or 0. The output, A, is full by default.

Examples

Find Bin Counts

Create a vector of subscripts, subs.

subs = [1; 2; 4; 2; 4]

Use accumarray with val = 1 to count the number of identical subscripts in subs.

A = accumarray(subs,1)

The result is a vector of bin counts. You can obtain the same answer with histcounts(subs,'BinMethod','integers'). However, accumarray also can compute bin counts over higher dimensional grids.

Accumulate Data

Create a vector of data, val, and a vector of subscript values with the same length, subs.

val = 101:105;
subs = [1; 3; 4; 3; 4]

Use accumarray to sum the values in val that have identical subscripts in subs.

A = accumarray(subs,val)

The result is a vector of accumulated values. Since the second and fourth elements of subs are equal to 3, A(3) is the sum of the second and fourth elements of val, that is, A(3) = 102 + 104 = 206. Also, A(2) = 0 because subs does not contain the value 2. Since subs is a vector, the output, A, is also a vector. The length of A is max(subs,[],1).

Specify Output Size

Create a vector of data, val, and a matrix of subscripts, subs.

val = 101:106;
subs = [1 1; 2 2; 3 2; 1 1; 2 2; 4 1]

The subscripts in subs define a 4-by-2 matrix for the output.

Use accumarray to sum the values in val that have identical subscripts in subs.

A = accumarray(subs,val)

The result is a 4-by-2 matrix of accumulated values.

Use the sz input of accumarray to return a 4-by-4 matrix. You can specify a size with each dimension equal to or greater than the default size, in this case 4-by-2, but not smaller.

A = accumarray(subs,val,[4 4])

A = 4×4

   205     0     0     0
     0   207     0     0
     0   103     0     0
   106     0     0     0

The result is a 4-by-4 matrix of accumulated values.

Use Custom Functions

Create a vector of data, val, and a matrix of subscripts, subs.

val = [100.1 101.2 103.4 102.8 100.9 101.5]';
subs = [1 1; 1 1; 2 2; 3 2; 2 2; 3 2]

The subscripts in subs define a 3-by-2 matrix for the output.

Use the fun input of accumarray to calculate the within-group variances of data in val that have identical subscripts in subs. Specify fun as @var.

A1 = accumarray(subs,val,[],@var)

A1 = 3×2

    0.6050         0
         0    3.1250
         0    0.8450

The result is a 3-by-2 matrix of variance values.

Alternatively, you can specify fun as an anonymous function so long as it accepts vector inputs and returns a scalar. A common situation where this is useful is when you want to pass additional parameters to a function. In this case, use the var function with a normalization parameter.

A2 = accumarray(subs,val,[],@(x) var(x,1))

A2 = 3×2

    0.3025         0
         0    1.5625
         0    0.4225

The result is a 3-by-2 matrix of normalized variance values.

Sum Values Natively

Create a vector of data, val, and a matrix of subscripts, subs.

val = int8(10:15);
subs = [1 1 1; 1 1 1; 1 1 2; 1 1 2; 2 3 1; 2 3 2]

subs = 6×3

     1     1     1
     1     1     1
     1     1     2
     1     1     2
     2     3     1
     2     3     2

The subscripts in subs define a 2-by-3-by-2 multidimensional array for the output.

Use accumarray to sum the data values in val that have identical subscripts in subs. You can use a function handle to sum the values in their native, int8, integer class by using the 'native' option of the sum function.

A = accumarray(subs,val,[],@(x) sum(x,'native'))

A = 2x3x2 int8 array
A(:,:,1) =

   21    0    0
    0    0   14


A(:,:,2) =

   25    0    0
    0    0   15

The result is a 2-by-3-by-2 multidimensional array of class int8.

Group Values in Cell Array

Create a vector of data val and a matrix of subscripts subs.

val = 1:10;
subs = [1 1;1 1;1 1;1 1;2 1;2 1;2 1;2 1;2 1;2 2]

subs = 10×2

     1     1
     1     1
     1     1
     1     1
     2     1
     2     1
     2     1
     2     1
     2     1
     2     2

The subscripts in subs define a 2-by-2 matrix for the output.

Use accumarray to group the elements of val into a cell array.

A = accumarray(subs,val,[],@(x) {x})

A=2×2 cell array
    {4x1 double}    {0x0 double}
    {5x1 double}    {[      10]}

The result is a 2-by-2 cell array.

Verify that the vector elements are in the same order as they appear in val.

A{2,1}

Fill Output with NaN Values

Create a vector of data, val, and a matrix of subscripts, subs.

val = 101:106';
subs = [1 1; 2 2; 3 3; 1 1; 2 2; 4 4]

The subscripts in subs define a 4-by-4 matrix for the output, but only reference 4 out of the 16 elements. By default, the other 12 elements are 0 in the output.

Use the fillval input of accumarray to fill in the extra output elements with NaN values.

A = accumarray(subs,val,[],[],NaN)

A = 4×4

   205   NaN   NaN   NaN
   NaN   207   NaN   NaN
   NaN   NaN   103   NaN
   NaN   NaN   NaN   106

The result is a 4-by-4 matrix padded with NaN values.

Change Output Sparsity

Create a vector of data, val, and a matrix of subscripts, subs.

val = [34 22 19 85 53 77 99 6];
subs = [1 1; 400 400; 80 80; 1 1; 400 400; 400 400; 80 80; 1 1]

The subscripts in subs define a 400-by-400 matrix for the output, but only reference 3 out of the 160,000 elements. When the result of an operation with accumarray leads to a large output array with low density of nonzero elements, you can save storage space by storing the output as a sparse matrix.

Use the issparse input of accumarray to return a sparse matrix.

A = accumarray(subs,val,[],[],[],true)

A = 
   (1,1)      125
  (80,80)     118
 (400,400)    152

The result is a sparse matrix. You can obtain the same answer with sparse(subs(:,1),subs(:,2),val).

Input Arguments

`subs` — Subscript matrix
vector of indices | matrix of indices | cell array of index vectors

Subscript matrix, specified as a vector of indices, matrix of indices, or cell array of index vectors. The indices must be positive integers:

The value in each row of the m-by-n matrix, subs, specifies an n-dimensional index into the output, A. For example, if subs is a 3-by-2 matrix, it contains three 2-D subscripts. subs also can be a column vector of indices, in which case the output, A, is also a column vector.
The ith row in subs corresponds to the ith data value in val.
If subs is empty with at least one column, then no data is accumulated. In this case, the output is also empty and the output type is dictated by fillval.

Thus, subs determines which data in val to group, as well as its final destination in the output. If subs is a cell array of index vectors, each vector must have the same length, and the function treats the vectors as columns of a subscript matrix.

`val` — Data
vector | scalar

Data, specified as a vector or scalar:

If val is a vector, it must have the same length as the number of rows in subs.
If val is a scalar, it is scalar expanded.

In both cases, a one-to-one pairing is present between the subscripts in each row of subs and the data values in val.

`sz` — Size of output array
`[]` (default) | vector of positive integers

Size of output array, specified as a vector of positive integers or [] (default). When you specify [] for the default size, the values in subs determine the size of the output array, A.

When you specify sz as a vector of positive integers, it must satisfy these properties:

If subs is an m-by-n matrix with n > 1 columns, then sz must have n elements and pass the logical test all(sz >= max(subs,[],1)).
If subs is a column vector, then sz must be [m 1] where m >= max(subs).

Example: sz = [3 3]

`fun` — Function
`[]` (default) | function handle

Function, specified as a function handle or [] (default). The default function is @sum. The fun function must accept a column vector and return a numeric, logical, or char scalar, or a scalar cell. For more information on function handles, see Create Function Handle.

Example: fun = @max

Data Types: function_handle

`fillval` — Fill value
`[]` (default) | scalar

Fill value, specified as a scalar or [] (default). The default value of fillval is 0. If subs does not reference each element in the output, accumarray fills in the output with the value specified by fillval. The class of fillval must be the same as the values returned by fun.

`issparse` — Output sparsity
`false` or `0` (default) | `true` or `1`

Output sparsity, specified as a numeric or logical 1 (true) or 0 (false). Specify true or 1 when you want the output array to be sparse. If issparse is true or 1:

fillval must be 0 or [].
The values in val and the output values of fun must both have type double.

Output Arguments

`A` — Output array
vector | matrix | multidimensional array

Output array, returned as a vector, matrix, or multidimensional array. A has the same class as the values returned by fun.

When sz is not specified, the size of A depends on the input subs:

If subs is a matrix with n > 1 columns, then A is an n-dimensional array of size max(subs,[],1).
If subs is a column vector, then A is a column vector of length max(subs,[],1).

More About