Documentation

accumarray

Construct array with accumulation

Description

example

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.

example

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.

example

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.

example

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.

example

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

collapse all

Create a vector of subscripts, subs.

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

1
2
4
2
4

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

A = accumarray(subs,1)
A = 4×1

1
2
0
2

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.

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]
subs = 5×1

1
3
4
3
4

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

A = accumarray(subs,val)
A = 4×1

101
0
206
208

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).

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]
subs = 6×2

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)
A = 4×2

205     0
0   207
0   103
106     0

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.

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]
subs = 6×2

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.

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.

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
{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}
ans = 5×1

5
6
7
8
9

Since the subscripts in subs are sorted, the elements of the numeric vectors in the cell array are in the same order as they appear in val.

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

val = 1:5;
subs = [1 2; 1 1; 1 2; 1 1; 2 3]
subs =

1     2
1     1
1     2
1     1
2     3

The subscripts in subs define a 2-by-3 matrix for the output, but are unsorted with respect to the linear indices in the output, A.

Group the values in val into a cell array by specifying fun = @(x) {x}.

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

2×3 cell array

[2×1 double]    [2×1 double]     []
[]              []    

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

Examine the vector in A{1,2}.

A{1,2}
ans =

3
1

The elements of the A{1,2} vector are in a different order than in val. The first element of the vector is 3 instead of 1. If the subscripts in subs are not sorted with respect to their linear indices, then accumarray might not always preserve the order of the data in val when it passes them to fun. In the unusual case that fun requires that its input values be in the same order as they appear in val, sort the indices in subs with respect to the linear indices of the output.

In this case, use the sortrows function with two inputs and two outputs to reorder subs and val concurrently with respect to the linear indices of the output.

[S,I] = sortrows(subs,[2,1]);
A = accumarray(S,val(I),[],@(x) {x});
A{1,2}
ans =

1
3

The elements of the A{1,2} vector are now in sorted order.

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]
subs = 6×2

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.

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]
subs = 8×2

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

collapse all

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, then the accumarray function errors.

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.

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.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char
Complex Number Support: Yes

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 a nonempty 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 nonempty column vector, then sz must be [m 1] where m >= max(subs).

Example: sz = [3 3]

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. If the subscripts in subs are not sorted with respect to their linear indices, fun should not depend on the order of the values in its input data. For more information on function handles, see Create Function Handle.

Example: fun = @max

Data Types: function_handle

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.

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

collapse all

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 nonempty matrix with n > 1 columns, then A is an n-dimensional array of size max(subs,[],1).

• If subs is an empty matrix with n > 1 columns, then A is an n-dimensional empty array with size 0-by-0-by-...-by-0.

• If subs is a nonempty column vector, then A is a column vector of length max(subs,[],1). The length of A is 0 when subs is empty.

collapse all

Accumulating Elements

The following graphic illustrates the behavior of accumarray on a vector of temperature data taken over a 12-month period. To find the maximum temperature reading for each month, accumarray applies the max function to each group of values in temperature that have identical subscripts in month. No values in month point to the 5, 6, 7, or 10 positions of the output. These elements are 0 in the output by default, but you can specify a value to fill in using fillval.

Tips

• The behavior of accumarray is similar to that of the histcounts function. Both functions group data into bins.

• histcounts groups continuous values into a 1-D range using bin edges. accumarray groups data using n-dimensional subscripts.

• histcounts returns the bin counts and/or bin placement. However, accumarray can apply any function to the binned data.

You can mimic the behavior of histcounts using accumarray with val = 1.

• The sparse function also has accumulation behavior similar to that of accumarray.

• sparse groups data into bins using 2-D subscripts, whereas accumarray groups data into bins using n-dimensional subscripts.

• For elements with identical subscripts, sparse assigns the sum of those elements to the output. accumarray does the same by default, but optionally can apply any function to the bins.