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