Next: Miscellaneous Techniques, Previous: Function Application, Up: Vectorization and Faster Code Execution [Contents][Index]

Whenever it’s possible to categorize according to indices the elements of an array when performing a computation, accumulation functions can be useful.

- :
**accumarray***(*¶`subs`,`vals`,`sz`,`func`,`fillval`,`issparse`) - :
**accumarray***(*¶`subs`,`vals`, …) -
Create an array by accumulating the elements of a vector into the positions defined by their subscripts.

The subscripts are defined by the rows of the matrix

`subs`and the values by`vals`. Each row of`subs`corresponds to one of the values in`vals`. If`vals`is a scalar, it will be used for each of the row of`subs`. If`subs`is a cell array of vectors, all vectors must be of the same length, and the subscripts in the`k`th vector must correspond to the`k`th dimension of the result.The size of the matrix will be determined by the subscripts themselves. However, if

`sz`is defined it determines the matrix size. The length of`sz`must correspond to the number of columns in`subs`. An exception is if`subs`has only one column, in which case`sz`may be the dimensions of a vector and the subscripts of`subs`are taken as the indices into it.The default action of

`accumarray`

is to sum the elements with the same subscripts. This behavior can be modified by defining the`func`function. This should be a function or function handle that accepts a column vector and returns a scalar. The result of the function should not depend on the order of the subscripts.The elements of the returned array that have no subscripts associated with them are set to zero. Defining

`fillval`to some other value allows these values to be defined. This behavior changes, however, for certain values of`func`. If`func`is`@min`

(respectively,`@max`

) then the result will be filled with the minimum (respectively, maximum) integer if`vals`is of integral type, logical false (respectively, logical true) if`vals`is of logical type, zero if`fillval`is zero and all values are non-positive (respectively, non-negative), and NaN otherwise.By default

`accumarray`

returns a full matrix. If`issparse`is logically true, then a sparse matrix is returned instead.The following

`accumarray`

example constructs a frequency table that in the first column counts how many occurrences each number in the second column has, taken from the vector`x`. Note the usage of`unique`

for assigning to all repeated elements of`x`the same index (see`unique`

).`x`= [91, 92, 90, 92, 90, 89, 91, 89, 90, 100, 100, 100]; [`u`, ~,`j`] = unique (`x`); [accumarray(`j`', 1),`u`'] ⇒ 2 89 3 90 2 91 2 92 3 100Another example, where the result is a multi-dimensional 3-D array and the default value (zero) appears in the output:

accumarray ([1, 1, 1; 2, 1, 2; 2, 3, 2; 2, 1, 2; 2, 3, 2], 101:105) ⇒ ans(:,:,1) = [101, 0, 0; 0, 0, 0] ⇒ ans(:,:,2) = [0, 0, 0; 206, 0, 208]

The sparse option can be used as an alternative to the

`sparse`

constructor (see`sparse`

). Thussparse (

`i`,`j`,`sv`)can be written with

`accumarray`

asaccumarray ([

`i`,`j`],`sv`', [], [], 0, true)For repeated indices,

`sparse`

adds the corresponding value. To take the minimum instead, use`min`

as an accumulator function:accumarray ([

`i`,`j`],`sv`', [], @min, 0, true)The complexity of accumarray in general for the non-sparse case is generally O(M+N), where N is the number of subscripts and M is the maximum subscript (linearized in multi-dimensional case). If

`func`is one of`@sum`

(default),`@max`

,`@min`

or`@(x) {x}`

, an optimized code path is used. Note that for general reduction function the interpreter overhead can play a major part and it may be more efficient to do multiple accumarray calls and compute the results in a vectorized manner.

- :
**accumdim***(*¶`subs`,`vals`,`dim`,`n`,`func`,`fillval`) Create an array by accumulating the slices of an array into the positions defined by their subscripts along a specified dimension.

The subscripts are defined by the index vector

`subs`. The dimension is specified by`dim`. If not given, it defaults to the first non-singleton dimension. The length of`subs`must be equal to`size (`

.`vals`,`dim`)The extent of the result matrix in the working dimension will be determined by the subscripts themselves. However, if

`n`is defined it determines this extent.The default action of

`accumdim`

is to sum the subarrays with the same subscripts. This behavior can be modified by defining the`func`function. This should be a function or function handle that accepts an array and a dimension, and reduces the array along this dimension. As a special exception, the built-in`min`

and`max`

functions can be used directly, and`accumdim`

accounts for the middle empty argument that is used in their calling.The slices of the returned array that have no subscripts associated with them are set to zero. Defining

`fillval`to some other value allows these values to be defined.An example of the use of

`accumdim`

is:accumdim ([1, 2, 1, 2, 1], [ 7, -10, 4; -5, -12, 8; -12, 2, 8; -10, 9, -3; -5, -3, -13]) ⇒ [-10,-11,-1;-15,-3,5]

**See also:**accumarray.