<html lang="en"> <head> <title>Accumulation - GNU Octave</title> <meta http-equiv="Content-Type" content="text/html"> <meta name="description" content="GNU Octave"> <meta name="generator" content="makeinfo 4.13"> <link title="Top" rel="start" href="index.html#Top"> <link rel="up" href="Vectorization-and-Faster-Code-Execution.html#Vectorization-and-Faster-Code-Execution" title="Vectorization and Faster Code Execution"> <link rel="prev" href="Function-Application.html#Function-Application" title="Function Application"> <link rel="next" href="Miscellaneous-Techniques.html#Miscellaneous-Techniques" title="Miscellaneous Techniques"> <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> <meta http-equiv="Content-Style-Type" content="text/css"> <style type="text/css"><!-- pre.display { font-family:inherit } pre.format { font-family:inherit } pre.smalldisplay { font-family:inherit; font-size:smaller } pre.smallformat { font-family:inherit; font-size:smaller } pre.smallexample { font-size:smaller } pre.smalllisp { font-size:smaller } span.sc { font-variant:small-caps } span.roman { font-family:serif; font-weight:normal; } span.sansserif { font-family:sans-serif; font-weight:normal; } --></style> </head> <body> <div class="node"> <a name="Accumulation"></a> <p> Next: <a rel="next" accesskey="n" href="Miscellaneous-Techniques.html#Miscellaneous-Techniques">Miscellaneous Techniques</a>, Previous: <a rel="previous" accesskey="p" href="Function-Application.html#Function-Application">Function Application</a>, Up: <a rel="up" accesskey="u" href="Vectorization-and-Faster-Code-Execution.html#Vectorization-and-Faster-Code-Execution">Vectorization and Faster Code Execution</a> <hr> </div> <h3 class="section">19.4 Accumulation</h3> <p>Whenever it's possible to categorize according to indices the elements of an array when performing a computation, accumulation functions can be useful. <!-- accumarray scripts/general/accumarray.m --> <p><a name="doc_002daccumarray"></a> <div class="defun"> — Function File: <b>accumarray</b> (<var>subs, vals, sz, func, fillval, issparse</var>)<var><a name="index-accumarray-2154"></a></var><br> — Function File: <b>accumarray</b> (<var>subs, vals, <small class="dots">...</small></var>)<var><a name="index-accumarray-2155"></a></var><br> <blockquote> <p>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 <var>subs</var> and the values by <var>vals</var>. Each row of <var>subs</var> corresponds to one of the values in <var>vals</var>. If <var>vals</var> is a scalar, it will be used for each of the row of <var>subs</var>. If <var>subs</var> is a cell array of vectors, all vectors must be of the same length, and the subscripts in the <var>k</var>th vector must correspond to the <var>k</var>th dimension of the result. <p>The size of the matrix will be determined by the subscripts themselves. However, if <var>sz</var> is defined it determines the matrix size. The length of <var>sz</var> must correspond to the number of columns in <var>subs</var>. An exception is if <var>subs</var> has only one column, in which case <var>sz</var> may be the dimensions of a vector and the subscripts of <var>subs</var> are taken as the indices into it. <p>The default action of <code>accumarray</code> is to sum the elements with the same subscripts. This behavior can be modified by defining the <var>func</var> 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. <p>The elements of the returned array that have no subscripts associated with them are set to zero. Defining <var>fillval</var> to some other value allows these values to be defined. This behavior changes, however, for certain values of <var>func</var>. If <var>func</var> is <code>min</code> (respectively, <code>max</code>) then the result will be filled with the minimum (respectively, maximum) integer if <var>vals</var> is of integral type, logical false (respectively, logical true) if <var>vals</var> is of logical type, zero if <var>fillval</var> is zero and all values are non-positive (respectively, non-negative), and NaN otherwise. <p>By default <code>accumarray</code> returns a full matrix. If <var>issparse</var> is logically true, then a sparse matrix is returned instead. <p>The following <code>accumarray</code> 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 <var>x</var>. Note the usage of <code>unique</code> for assigning to all repeated elements of <var>x</var> the same index (see <a href="doc_002dunique.html#doc_002dunique">doc-unique</a>). <pre class="example"> <var>x</var> = [91, 92, 90, 92, 90, 89, 91, 89, 90, 100, 100, 100]; [<var>u</var>, ~, <var>j</var>] = unique (<var>x</var>); [accumarray(<var>j</var>', 1), <var>u</var>'] ⇒ 2 89 3 90 2 91 2 92 3 100 </pre> <p>Another example, where the result is a multi-dimensional 3-D array and the default value (zero) appears in the output: <pre class="example"> 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] </pre> <p>The sparse option can be used as an alternative to the <code>sparse</code> constructor (see <a href="doc_002dsparse.html#doc_002dsparse">doc-sparse</a>). Thus <pre class="example"> sparse (<var>i</var>, <var>j</var>, <var>sv</var>) </pre> <p class="noindent">can be written with <code>accumarray</code> as <pre class="example"> accumarray ([<var>i</var>, <var>j</var>], <var>sv</var>', [], [], 0, true) </pre> <p class="noindent">For repeated indices, <code>sparse</code> adds the corresponding value. To take the minimum instead, use <code>min</code> as an accumulator function: <pre class="example"> accumarray ([<var>i</var>, <var>j</var>], <var>sv</var>', [], @min, 0, true) </pre> <p>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 <var>func</var> is one of <code>@sum</code> (default), <code>@max</code>, <code>@min</code> or <code>@(x) {x}</code>, 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. <!-- Texinfo @sp should work but in practice produces ugly results for HTML. --> <!-- A simple blank line produces the correct behavior. --> <!-- @sp 1 --> <p class="noindent"><strong>See also:</strong> <a href="doc_002daccumdim.html#doc_002daccumdim">accumdim</a>, <a href="doc_002dunique.html#doc_002dunique">unique</a>, <a href="doc_002dsparse.html#doc_002dsparse">sparse</a>. </p></blockquote></div> <!-- accumdim scripts/general/accumdim.m --> <p><a name="doc_002daccumdim"></a> <div class="defun"> — Function File: <b>accumdim</b> (<var>subs, vals, dim, n, func, fillval</var>)<var><a name="index-accumdim-2156"></a></var><br> <blockquote><p>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 <var>subs</var>. The dimension is specified by <var>dim</var>. If not given, it defaults to the first non-singleton dimension. The length of <var>subs</var> must be equal to <code>size (</code><var>vals</var><code>, </code><var>dim</var><code>)</code>. <p>The extent of the result matrix in the working dimension will be determined by the subscripts themselves. However, if <var>n</var> is defined it determines this extent. <p>The default action of <code>accumdim</code> is to sum the subarrays with the same subscripts. This behavior can be modified by defining the <var>func</var> 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 <code>min</code> and <code>max</code> functions can be used directly, and <code>accumdim</code> accounts for the middle empty argument that is used in their calling. <p>The slices of the returned array that have no subscripts associated with them are set to zero. Defining <var>fillval</var> to some other value allows these values to be defined. <p>An example of the use of <code>accumdim</code> is: <pre class="example"> 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] </pre> <!-- Texinfo @sp should work but in practice produces ugly results for HTML. --> <!-- A simple blank line produces the correct behavior. --> <!-- @sp 1 --> <p class="noindent"><strong>See also:</strong> <a href="doc_002daccumarray.html#doc_002daccumarray">accumarray</a>. </p></blockquote></div> </body></html>