<html lang="en">
<head>
<title>Advanced Indexing - 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="Index-Expressions.html#Index-Expressions" title="Index Expressions">
<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="Advanced-Indexing"></a>
<p>
Up: <a rel="up" accesskey="u" href="Index-Expressions.html#Index-Expressions">Index Expressions</a>
<hr>
</div>
<h4 class="subsection">8.1.1 Advanced Indexing</h4>
<p>An array with ‘<samp><span class="samp">n</span></samp>’ dimensions can be indexed using ‘<samp><span class="samp">m</span></samp>’
indices. More generally, the set of index tuples determining the
result is formed by the Cartesian product of the index vectors (or
ranges or scalars).
<p>For the ordinary and most common case, <code>m == n</code><!-- /@w -->, and each
index corresponds to its respective dimension. If <code>m < n</code><!-- /@w -->
and every index is less than the size of the array in the
i^th dimension, <code>m(i) < n(i)</code>, then the index expression
is padded with trailing singleton dimensions (<code>[ones (m-n, 1)]</code>).
If <code>m < n</code><!-- /@w --> but one of the indices <code>m(i)</code> is outside the
size of the current array, then the last <code>n-m+1</code><!-- /@w --> dimensions
are folded into a single dimension with an extent equal to the product
of extents of the original dimensions. This is easiest to understand
with an example.
<pre class="example"> a = reshape (1:8, 2, 2, 2) # Create 3-D array
a =
ans(:,:,1) =
1 3
2 4
ans(:,:,2) =
5 7
6 8
a(2,1,2); # Case (m == n): ans = 6
a(2,1); # Case (m < n), idx within array:
# equivalent to a(2,1,1), ans = 2
a(2,4); # Case (m < n), idx outside array:
# Dimension 2 & 3 folded into new dimension of size 2x2 = 4
# Select 2nd row, 4th element of [2, 4, 6, 8], ans = 8
</pre>
<p>One advanced use of indexing is to create arrays filled with a single
value. This can be done by using an index of ones on a scalar value.
The result is an object with the dimensions of the index expression
and every element equal to the original scalar. For example, the
following statements
<pre class="example"> a = 13;
a(ones (1, 4))
</pre>
<p class="noindent">produce a vector whose four elements are all equal to 13.
<p>Similarly, by indexing a scalar with two vectors of ones it is
possible to create a matrix. The following statements
<pre class="example"> a = 13;
a(ones (1, 2), ones (1, 3))
</pre>
<p class="noindent">create a 2x3 matrix with all elements equal to 13.
<p>The last example could also be written as
<pre class="example"> 13(ones (2, 3))
</pre>
<p>It is more efficient to use indexing rather than the code construction
<code>scalar * ones (N, M, ...)</code> because it avoids the unnecessary
multiplication operation. Moreover, multiplication may not be
defined for the object to be replicated whereas indexing an array is
always defined. The following code shows how to create a 2x3 cell
array from a base unit which is not itself a scalar.
<pre class="example"> {"Hello"}(ones (2, 3))
</pre>
<p>It should be, noted that <code>ones (1, n)</code> (a row vector of ones)
results in a range (with zero increment). A range is stored
internally as a starting value, increment, end value, and total number
of values; hence, it is more efficient for storage than a vector or
matrix of ones whenever the number of elements is greater than 4. In
particular, when ‘<samp><span class="samp">r</span></samp>’ is a row vector, the expressions
<pre class="example"> r(ones (1, n), :)
</pre>
<pre class="example"> r(ones (n, 1), :)
</pre>
<p class="noindent">will produce identical results, but the first one will be
significantly faster, at least for ‘<samp><span class="samp">r</span></samp>’ and ‘<samp><span class="samp">n</span></samp>’ large enough.
In the first case the index is held in compressed form as a range
which allows Octave to choose a more efficient algorithm to handle the
expression.
<p>A general recommendation, for a user unaware of these subtleties, is
to use the function <code>repmat</code> for replicating smaller arrays into
bigger ones.
<p>A second use of indexing is to speed up code. Indexing is a fast
operation and judicious use of it can reduce the requirement for
looping over individual array elements which is a slow operation.
<p>Consider the following example which creates a 10-element row vector
a containing the values
a(i) = sqrt(i).
<pre class="example"> for i = 1:10
a(i) = sqrt (i);
endfor
</pre>
<p class="noindent">It is quite inefficient to create a vector using a loop like this. In
this case, it would have been much more efficient to use the
expression
<pre class="example"> a = sqrt (1:10);
</pre>
<p class="noindent">which avoids the loop entirely.
<p>In cases where a loop cannot be avoided, or a number of values must be
combined to form a larger matrix, it is generally faster to set the
size of the matrix first (pre-allocate storage), and then insert
elements using indexing commands. For example, given a matrix
<code>a</code>,
<pre class="example"> [nr, nc] = size (a);
x = zeros (nr, n * nc);
for i = 1:n
x(:,(i-1)*nc+1:i*nc) = a;
endfor
</pre>
<p class="noindent">is considerably faster than
<pre class="example"> x = a;
for i = 1:n-1
x = [x, a];
endfor
</pre>
<p class="noindent">because Octave does not have to repeatedly resize the intermediate
result.
<!-- sub2ind src/DLD-FUNCTIONS/sub2ind.cc -->
<p><a name="doc_002dsub2ind"></a>
<div class="defun">
— Function File: <var>ind</var> = <b>sub2ind</b> (<var>dims, i, j</var>)<var><a name="index-sub2ind-518"></a></var><br>
— Function File: <var>ind</var> = <b>sub2ind</b> (<var>dims, s1, s2, <small class="dots">...</small>, sN</var>)<var><a name="index-sub2ind-519"></a></var><br>
<blockquote><p>Convert subscripts to a linear index.
<p>The following example shows how to convert the two-dimensional
index <code>(2,3)</code> of a 3-by-3 matrix to a linear index. The matrix
is linearly indexed moving from one column to next, filling up
all rows in each column.
<pre class="example"> linear_index = sub2ind ([3, 3], 2, 3)
⇒ 8
</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_002dind2sub.html#doc_002dind2sub">ind2sub</a>.
</p></blockquote></div>
<!-- ind2sub src/DLD-FUNCTIONS/sub2ind.cc -->
<p><a name="doc_002dind2sub"></a>
<div class="defun">
— Function File: [<var>s1</var>, <var>s2</var>, <small class="dots">...</small>, <var>sN</var>] = <b>ind2sub</b> (<var>dims, ind</var>)<var><a name="index-ind2sub-520"></a></var><br>
<blockquote><p>Convert a linear index to subscripts.
<p>The following example shows how to convert the linear index <code>8</code>
in a 3-by-3 matrix into a subscript. The matrix is linearly indexed
moving from one column to next, filling up all rows in each column.
<pre class="example"> [r, c] = ind2sub ([3, 3], 8)
⇒ r = 2
c = 3
</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_002dsub2ind.html#doc_002dsub2ind">sub2ind</a>.
</p></blockquote></div>
<!-- isindex src/utils.cc -->
<p><a name="doc_002disindex"></a>
<div class="defun">
— Built-in Function: <b>isindex</b> (<var>ind</var>)<var><a name="index-isindex-521"></a></var><br>
— Built-in Function: <b>isindex</b> (<var>ind, n</var>)<var><a name="index-isindex-522"></a></var><br>
<blockquote><p>Return true if <var>ind</var> is a valid index. Valid indices are
either positive integers (although possibly of real data type), or logical
arrays. If present, <var>n</var> specifies the maximum extent of the dimension
to be indexed. When possible the internal result is cached so that
subsequent indexing using <var>ind</var> will not perform the check again.
</p></blockquote></div>
<!-- allow_noninteger_range_as_index src/ov-range.cc -->
<p><a name="doc_002dallow_005fnoninteger_005frange_005fas_005findex"></a>
<div class="defun">
— Built-in Function: <var>val</var> = <b>allow_noninteger_range_as_index</b> ()<var><a name="index-allow_005fnoninteger_005frange_005fas_005findex-523"></a></var><br>
— Built-in Function: <var>old_val</var> = <b>allow_noninteger_range_as_index</b> (<var>new_val</var>)<var><a name="index-allow_005fnoninteger_005frange_005fas_005findex-524"></a></var><br>
— Built-in Function: <b>allow_noninteger_range_as_index</b> (<var>new_val, "local"</var>)<var><a name="index-allow_005fnoninteger_005frange_005fas_005findex-525"></a></var><br>
<blockquote><p>Query or set the internal variable that controls whether non-integer
ranges are allowed as indices. This might be useful for <span class="sc">matlab</span>
compatibility; however, it is still not entirely compatible because
<span class="sc">matlab</span> treats the range expression differently in different contexts.
<p>When called from inside a function with the "local" option, the variable is
changed locally for the function and any subroutines it calls. The original
variable value is restored when exiting the function.
</p></blockquote></div>
</body></html>
