Whenever it’s possible to categorize according to indices the elements of an array when performing a computation, accumulation functions can be useful.
A = accumarray (subs, vals) ¶A = accumarray (subs, vals, sz) ¶A = accumarray (subs, vals, sz, fcn) ¶A = accumarray (subs, vals, sz, fcn, fillval) ¶A = accumarray (subs, vals, sz, fcn, fillval, issparse) ¶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 kth vector must correspond to the kth 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
fcn 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 fcn. If fcn 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 100
Another 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). Thus
sparse (i, j, sv)
can be written with accumarray as
accumarray ([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
fcn 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.
A = accumdim (subs, vals) ¶A = accumdim (subs, vals, dim) ¶A = accumdim (subs, vals, dim, n) ¶A = accumdim (subs, vals, dim, n, fcn) ¶A = accumdim (subs, vals, dim, n, fcn, 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
fcn 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.