/usr/share/doc/octave/octave.html/Accumulation.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Accumulation (GNU Octave)</title>

<meta name="description" content="Accumulation (GNU Octave)">
<meta name="keywords" content="Accumulation (GNU Octave)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Vectorization-and-Faster-Code-Execution.html#Vectorization-and-Faster-Code-Execution" rel="up" title="Vectorization and Faster Code Execution">
<link href="JIT-Compiler.html#JIT-Compiler" rel="next" title="JIT Compiler">
<link href="Function-Application.html#Function-Application" rel="prev" title="Function Application">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">


</head>

<body lang="en">
<a name="Accumulation"></a>
<div class="header">
<p>
Next: <a href="JIT-Compiler.html#JIT-Compiler" accesskey="n" rel="next">JIT Compiler</a>, Previous: <a href="Function-Application.html#Function-Application" accesskey="p" rel="prev">Function Application</a>, Up: <a href="Vectorization-and-Faster-Code-Execution.html#Vectorization-and-Faster-Code-Execution" accesskey="u" rel="up">Vectorization and Faster Code Execution</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Accumulation-1"></a>
<h3 class="section">19.4 Accumulation</h3>

<p>Whenever it&rsquo;s possible to categorize according to indices the elements
of an array when performing a computation, accumulation functions can be
useful.
</p>
<a name="XREFaccumarray"></a><dl>
<dt><a name="index-accumarray"></a>: <em></em> <strong>accumarray</strong> <em>(<var>subs</var>, <var>vals</var>, <var>sz</var>, <var>func</var>, <var>fillval</var>, <var>issparse</var>)</em></dt>
<dt><a name="index-accumarray-1"></a>: <em></em> <strong>accumarray</strong> <em>(<var>subs</var>, <var>vals</var>, &hellip;)</em></dt>
<dd>
<p>Create an array by accumulating the elements of a vector into the
positions defined by their subscripts.
</p>
<p>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>
<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>
<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>
<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>
<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>
<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="Sets.html#XREFunique">unique</a>).
</p>
<div class="example">
<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>']
  &rArr;  2    89
      3    90
      2    91
      2    92
      3   100
</pre></div>

<p>Another example, where the result is a multi-dimensional 3-D array and
the default value (zero) appears in the output:
</p>
<div class="example">
<pre class="example">accumarray ([1, 1, 1;
             2, 1, 2;
             2, 3, 2;
             2, 1, 2;
             2, 3, 2], 101:105)
&rArr; ans(:,:,1) = [101, 0, 0; 0, 0, 0]
&rArr; ans(:,:,2) = [0, 0, 0; 206, 0, 208]
</pre></div>

<p>The sparse option can be used as an alternative to the <code>sparse</code>
constructor (see <a href="Creating-Sparse-Matrices.html#XREFsparse">sparse</a>).  Thus
</p>
<div class="example">
<pre class="example">sparse (<var>i</var>, <var>j</var>, <var>sv</var>)
</pre></div>

<p>can be written with <code>accumarray</code> as
</p>
<div class="example">
<pre class="example">accumarray ([<var>i</var>, <var>j</var>], <var>sv</var>', [], [], 0, true)
</pre></div>

<p>For repeated indices, <code>sparse</code> adds the corresponding value.  To
take the minimum instead, use <code>min</code> as an accumulator function:
</p>
<div class="example">
<pre class="example">accumarray ([<var>i</var>, <var>j</var>], <var>sv</var>', [], @min, 0, true)
</pre></div>

<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.
</p>

<p><strong>See also:</strong> <a href="#XREFaccumdim">accumdim</a>, <a href="Sets.html#XREFunique">unique</a>, <a href="Creating-Sparse-Matrices.html#XREFsparse">sparse</a>.
</p></dd></dl>


<a name="XREFaccumdim"></a><dl>
<dt><a name="index-accumdim"></a>: <em></em> <strong>accumdim</strong> <em>(<var>subs</var>, <var>vals</var>, <var>dim</var>, <var>n</var>, <var>func</var>, <var>fillval</var>)</em></dt>
<dd><p>Create an array by accumulating the slices of an array into the
positions defined by their subscripts along a specified dimension.
</p>
<p>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 (<var>vals</var>, <var>dim</var>)</code>.
</p>
<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>
<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>
<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>
<p>An example of the use of <code>accumdim</code> is:
</p>
<div class="example">
<pre class="example">accumdim ([1, 2, 1, 2, 1], [ 7, -10,   4;
                            -5, -12,   8;
                           -12,   2,   8;
                           -10,   9,  -3;
                            -5,  -3, -13])
&rArr; [-10,-11,-1;-15,-3,5]
</pre></div>


<p><strong>See also:</strong> <a href="#XREFaccumarray">accumarray</a>.
</p></dd></dl>


<hr>
<div class="header">
<p>
Next: <a href="JIT-Compiler.html#JIT-Compiler" accesskey="n" rel="next">JIT Compiler</a>, Previous: <a href="Function-Application.html#Function-Application" accesskey="p" rel="prev">Function Application</a>, Up: <a href="Vectorization-and-Faster-Code-Execution.html#Vectorization-and-Faster-Code-Execution" accesskey="u" rel="up">Vectorization and Faster Code Execution</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
octave-doc 4.2.2-1ubuntu1 / usr / share / doc / octave / octave.html / Accumulation.html
