octave: Accumulation
19.4 Accumulation
=================
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 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
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
(
unique XREFunique.).
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 (sparse XREFsparse.). 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 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.
See also: accumdim XREFaccumdim, unique XREFunique,
sparse XREFsparse.
-- : 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 XREFaccumarray.
Info Catalog
octave: Function Application
octave: Vectorization and Faster Code Execution
octave: JIT Compiler