# accumarray

Accumulate vector elements

## Syntax

``B = accumarray(ind,data)``
``B = accumarray(ind,data,sz)``
``B = accumarray(ind,data,sz,fun)``
``B = accumarray(ind,data,sz,fun,fillval)``
``B = accumarray(ind,data,sz,fun,fillval,issparse)``

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

## Version History

Introduced before R2006a