accumarray

Accumulate vector elements

Description

example

B = accumarray(ind,data) sums groups of data by accumulating elements of a vector data according to the groups specified in ind. The sum is then computed over each group. The values in ind define both the group the data belongs to and the index into the output array B where each group sum is stored.

To return the group sums in order, specify ind as a vector. Then for the group with index i, accumarray returns its sum in B(i). For example, if ind = [1 1 2 2]' and data = [1 2 3 4]', then B = accumarray(ind,data) returns the column vector B = [3 7]'.

To return the group sums in another shape, specify ind as a matrix. For an m-by-n matrix ind, each row represents the group assignment and an n-dimensional index into the output B. For example, if ind contains two rows of the form [3 4], then the sum of the corresponding elements in data is stored in the (3,4) element of B.

Elements of B whose index does not appear in ind are filled with 0 by default.

example

B = accumarray(ind,data,sz) returns an array B padded to size sz. Specify sz as a vector of positive integers that match or exceed the dimension lengths in ind. Extra elements in the output are filled with 0. Specify sz as [] to let the indices in ind determine the size of the output.

example

B = accumarray(ind,data,sz,fun) applies the function fun to each group in data specified by ind. Specify fun using the @ symbol, such as @mean, or as [] to use the default @sum.

example

B = accumarray(ind,data,sz,fun,fillval) fills all elements of B that are not referred to by an index in ind with the scalar value fillval. Specify fillval as [] to use the default value 0.

example

B = accumarray(ind,data,sz,fun,fillval,issparse) returns an array B that is sparse when issparse is true or 1, and full if issparse is false or 0. The output B is full by default.

Examples

collapse all

Create a vector of data and a corresponding vector ind that defines groups.

data = (1:6)'
data = 6×1

1
2
3
4
5
6

ind = [1 3 4 2 4 1]'
ind = 6×1

1
3
4
2
4
1

Sum the values in data by the groups specified in ind.

B = accumarray(ind,data)
B = 4×1

7
4
2
8

Alternatively, use the groupsummary function, specifying 'sum' as the group computation.

B = groupsummary(data,ind,'sum')
B = 4×1

7
4
2
8

Create a vector of groups.

ind = [1 1 4 2 4 3]';

Apply scalar expansion to the number 1 to count the number of elements in each group defined in ind.

B = accumarray(ind,1)
B = 4×1

2
1
1
2

Alternatively, use the groupcounts function.

B = groupcounts(ind)
B = 4×1

2
1
1
2

Create a vector of data and a matrix of output indices ind that defines groups of data.

data = 1:6
data = 1×6

1     2     3     4     5     6

ind = [1 1; 2 2; 3 2; 1 1; 2 2; 4 1]
ind = 6×2

1     1
2     2
3     2
1     1
2     2
4     1

Sum the values in data for each group in ind. The indices in ind define a 4-by-2 matrix of locations for the output.

B1 = accumarray(ind,data)
B1 = 4×2

5     0
0     7
0     3
6     0

Pad the output to a 4-by-4 matrix by specifying the output size as [4 4].

B2 = accumarray(ind,data,[4 4])
B2 = 4×4

5     0     0     0
0     7     0     0
0     3     0     0
6     0     0     0

Calculate group variances rather than sums.

Create a vector of data and a matrix ind that defines groups of the data.

data = [100.1 101.2 103.4 102.8 100.9 101.5]'
data = 6×1

100.1000
101.2000
103.4000
102.8000
100.9000
101.5000

ind = [1 1; 1 1; 2 2; 3 2; 2 2; 3 2]
ind = 6×2

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

Compute the variance of each group by specifying the function handle @var as the method input. This syntax applies the var function to the groups instead of sum.

B1 = accumarray(ind,data,[],@var)
B1 = 3×2

0.6050         0
0    3.1250
0    0.8450

You can specify the group computation as an anonymous function that accepts vector inputs and returns a scalar. This is useful when you want to pass additional arguments to a function. For example, use the var function with the normalization argument value 1.

A2 = accumarray(ind,data,[],@(x) var(x,1))
A2 = 3×2

0.3025         0
0    1.5625
0    0.4225

Specify an additional argument to the sum function by using an anonymous function for the method input.

Create a vector of data and a matrix ind that defines groups of the data and 3-D indices into the output.

data = int8(10:15)
data = 1x6 int8 row vector

10   11   12   13   14   15

ind = [1 1 1; 1 1 1; 1 1 2; 1 1 2; 2 3 1; 2 3 2]
ind = 6×3

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

Sum the data by group in their native integer class int8 by using the 'native' option for the sum function. To do this, specify an anonymous function using @(x) sum(x,'native') for the method input. The result is a 2-by-3-by-2 multidimensional array of type int8.

B = accumarray(ind,data,[],@(x) sum(x,'native'))
B = 2x3x2 int8 array
B(:,:,1) =

21    0    0
0    0   14

B(:,:,2) =

25    0    0
0    0   15

Create a vector of data and a matrix ind that defines groups of the data.

data = 1:10
data = 1×10

1     2     3     4     5     6     7     8     9    10

ind = [1 1; 1 1; 1 1; 1 1; 2 1; 2 1; 2 1; 2 1; 2 1; 2 2]
ind = 10×2

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

Group the elements of data into a cell array.

B = accumarray(ind,data,[],@(x) {x})
B=2×2 cell array
{4x1 double}    {0x0 double}
{5x1 double}    {[      10]}

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

B{2,1}
ans = 5×1

5
6
7
8
9

Create a vector of data and a matrix ind that defines groups of the data.

data = (101:106)'
data = 6×1

101
102
103
104
105
106

ind = [1 1; 2 2; 3 3; 1 1; 2 2; 4 4]
ind = 6×2

1     1
2     2
3     3
1     1
2     2
4     4

The elements of ind 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. Fill in the extra output elements with NaN values instead of 0.

B = accumarray(ind,data,[],[],NaN)
B = 4×4

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

Create a vector of data and a matrix ind that defines groups of the data.

data = [34 22 19 85 53 77 99 6];
ind = [1 1; 400 400; 80 80; 1 1; 400 400; 400 400; 80 80; 1 1]
ind = 8×2

1     1
400   400
80    80
1     1
400   400
400   400
80    80
1     1

The elements of ind define a 400-by-400 matrix for the output, but only reference 3 out of the 160,000 elements. When the output of accumarray results in a large array with a low density of nonzero elements, you can save memory by specifying the issparse option as true, creating a sparse matrix instead of a full one.

B = accumarray(ind,data,[],[],[],true)
B =
(1,1)      125
(80,80)     118
(400,400)    152

Input Arguments

collapse all

Output indices, specified as a vector, matrix, or cell array of vectors.

• If ind is a vector, then each element specifies an index into the output and defines the groups accumulated by accumarray. All of the elements must be positive integers and the length of ind must match the length of the data vector.

• If ind is an m-by-n matrix, then each row specifies an n-dimensional index into the output. The ith row in ind corresponds to the ith value in the data and the number of rows in ind must match the length of the data vector. For example, if ind is a 3-by-2 matrix, it contains three 2-D indices. The first element of each row is the row index into the output and the second element is the column index.

• If ind is a cell array of index vectors, then each vector must have the same length and they are treated as columns.

Data to be accumulated, specified as a scalar or vector.

• If data is a scalar, then its value is scalar expanded.

• If data is a vector, then it must have the same length as the number of rows in the index array.

Size of the output array, specified as a vector of positive integers or as []. For example, sz = [5 7] produces an output array that is 5-by-7. When you specify [] for the size, the values in the index array determine the size of the output. The dimension lengths in sz must match or exceed the dimension lengths in the index array.

Group computation, specified as a function handle. accumarray accumulates the elements of the data vector by group, and then applies the function fun to the group elements. When you specify fun = [], the computation uses the default function sum. The specified 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

Fill value when an element of the output does not correspond to an index provided in the index array, specified as a scalar or as [], which uses the default value 0. The data type of fillval must match the data type of the computation function output.

Output sparsity, specified as a numeric or logical 1 (true) or 0 (false).

When issparse is true or 1, the fill value must be 0 or [], and the input data and output of the computation function must both have type double.

Output Arguments

collapse all

Output array, returned as a vector, matrix, or multidimensional array. B has the same data type as the values returned by the group computation function.

When the size of B is not specified, the output size depends on the index array ind.

• If ind is a column vector, then B is a column vector of length max(ind,[],1).

• If ind is a matrix with more than one column, then B is a multidimensional array of size max(ind,[],1).

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

Tips

• The behavior of accumarray is similar to the functions groupsummary and groupcounts for computing summary statistics by group and counting the number of elements in a group, respectively. For more grouping functionality in MATLAB®, see Preprocessing Data.

• The behavior of accumarray is also similar to that of the histcounts function.

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

• histcounts can only return bin counts and bin placement. accumarray can apply any function to the data.

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

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

• sparse groups data using 2-D indices, whereas accumarray groups data using n-dimensional indices.

• For elements with identical indices, sparse applies the sum function (for double values) or the any function (for logical values) and returns the scalar result in the output matrix. accumarray sums by default, but can apply any function to the data.