Accelerating the pace of engineering and science

# Documentation Center

• Trial Software

# accumarray

Construct array with accumulation

## Syntax

• A = accumarray(subs,val) example
• A = accumarray(subs,val,sz) example
• A = accumarray(subs,val,sz,fun) example
• A = accumarray(subs,val,sz,fun,fillval) example
• A = accumarray(subs,val,sz,fun,fillval,issparse) example

## Description

example

A = accumarray(subs,val) returns an array, A, by accumulating elements of vector val using the subscripts in subs. The values in each row of the m-by-n matrix subs define an n-dimensional subscript into the output, A. If subs is a column vector, the value in each row defines a row subscript into the output, which is also a column vector.

The ith row of subs corresponds to the ith element in the vector, val. The function collects all elements of val that have identical subscripts in subs, applies the function @sum, and then stores the result in the location of A corresponding to the subscript. Elements of A that are not referred to by any row of subs contain the value 0.

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

expand all

### Find Bin Counts

Create a vector of subscripts, subs.

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

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

`A = accumarray(subs,1)`
```A =

1
2
0
2```

The result is a vector of bin counts. You can obtain the same answer with histc(subs,1:4). 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]
```
```subs =
1
3
4
3
4
```

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

```A = accumarray(subs,val)
```
```A =
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).

### 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]```
```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)
```
```A =

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 =

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]```
```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 =

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 =

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 =

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(:,:,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 =

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 =

[4x1 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
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.

### Using Functions That Depend on Data Order

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 =

[2x1 double]    [2x1 double]     []
[]              []    [5]```

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.

Use the two-output syntax of the sortrows function to reorder subs and val concurrently with respect to the linear indices of the output, A.

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

1
3```

The elements of the A{3} vector are now in sorted order.

### 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]```
```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 =

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]```
```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

expand all

### subs — Subscript matrixvector 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.

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 — Datavector | 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.

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

### 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 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]

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

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 sparsityfalse (default) | true | 1 | 0

Output sparsity, specified as true, 1, 0, or false (default). 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

expand all

### A — Output arrayvector | 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 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.

expand 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 histc function. Both functions group data into bins.

• histc groups continuous values into a 1-D range using bin edges.

• accumarray groups data using n-dimensional subscripts.

• histc returns the bin counts using @sum.

• accumarray can apply any function to the bins.

You can mimic the behavior of histc 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.

• sparse adds elements that have identical subscripts into the output. accumarray adds elements that have identical subscripts into the output by default, but can optionally apply any function to the bins.