# accumarray

Construct array with accumulation

## Syntax

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

## 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 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}`
```ans = 5×1 5 6 7 8 9 ```

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`. 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` 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 bins.