6
.. sectionauthor:: adapted from "Guide to Numpy" by Travis E. Oliphant
8
.. currentmodule:: numpy
10
.. index:: indexing, slicing
12
:class:`ndarrays <ndarray>` can be indexed using the standard Python
13
``x[obj]`` syntax, where *x* is the array and *obj* the selection.
14
There are three kinds of indexing available: record access, basic
15
slicing, advanced indexing. Which one occurs depends on *obj*.
19
In Python, ``x[(exp1, exp2, ..., expN)]`` is equivalent to
20
``x[exp1, exp2, ..., expN]``; the latter is just syntactic sugar
27
Basic slicing extends Python's basic concept of slicing to N
28
dimensions. Basic slicing occurs when *obj* is a :class:`slice` object
29
(constructed by ``start:stop:step`` notation inside of brackets), an
30
integer, or a tuple of slice objects and integers. :const:`Ellipsis`
31
and :const:`newaxis` objects can be interspersed with these as
32
well. In order to remain backward compatible with a common usage in
33
Numeric, basic slicing is also initiated if the selection object is
34
any sequence (such as a :class:`list`) containing :class:`slice`
35
objects, the :const:`Ellipsis` object, or the :const:`newaxis` object,
36
but no integer arrays or other embedded sequences.
39
triple: ndarray; special methods; getslice
40
triple: ndarray; special methods; setslice
44
The simplest case of indexing with *N* integers returns an :ref:`array
45
scalar <arrays.scalars>` representing the corresponding item. As in
46
Python, all indices are zero-based: for the *i*-th index :math:`n_i`,
47
the valid range is :math:`0 \le n_i < d_i` where :math:`d_i` is the
48
*i*-th element of the shape of the array. Negative indices are
49
interpreted as counting from the end of the array (*i.e.*, if *i < 0*,
50
it means :math:`n_i + i`).
53
All arrays generated by basic slicing are always :term:`views <view>`
54
of the original array.
56
The standard rules of sequence slicing apply to basic slicing on a
57
per-dimension basis (including using a step index). Some useful
58
concepts to remember include:
60
- The basic slice syntax is ``i:j:k`` where *i* is the starting index,
61
*j* is the stopping index, and *k* is the step (:math:`k\neq0`).
62
This selects the *m* elements (in the corresponding dimension) with
63
index values *i*, *i + k*, ..., *i + (m - 1) k* where
64
:math:`m = q + (r\neq0)` and *q* and *r* are the quotient and remainder
65
obtained by dividing *j - i* by *k*: *j - i = q k + r*, so that
68
.. admonition:: Example
70
>>> x = np.array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
74
- Negative *i* and *j* are interpreted as *n + i* and *n + j* where
75
*n* is the number of elements in the corresponding dimension.
76
Negative *k* makes stepping go towards smaller indices.
78
.. admonition:: Example
85
- Assume *n* is the number of elements in the dimension being
86
sliced. Then, if *i* is not given it defaults to 0 for *k > 0* and
87
*n* for *k < 0* . If *j* is not given it defaults to *n* for *k > 0*
88
and -1 for *k < 0* . If *k* is not given it defaults to 1. Note that
89
``::`` is the same as ``:`` and means select all indices along this
92
.. admonition:: Example
95
array([5, 6, 7, 8, 9])
97
- If the number of objects in the selection tuple is less than
98
*N* , then ``:`` is assumed for any subsequent dimensions.
100
.. admonition:: Example
102
>>> x = np.array([[[1],[2],[3]], [[4],[5],[6]]])
110
- :const:`Ellipsis` expand to the number of ``:`` objects needed to
111
make a selection tuple of the same length as ``x.ndim``. Only the
112
first ellipsis is expanded, any others are interpreted as ``:``.
114
.. admonition:: Example
120
- Each :const:`newaxis` object in the selection tuple serves to expand
121
the dimensions of the resulting selection by one unit-length
122
dimension. The added dimension is the position of the :const:`newaxis`
123
object in the selection tuple.
125
.. admonition:: Example
127
>>> x[:,np.newaxis,:,:].shape
130
- An integer, *i*, returns the same values as ``i:i+1``
131
**except** the dimensionality of the returned object is reduced by
132
1. In particular, a selection tuple with the *p*-th
133
element an integer (and all other entries ``:``) returns the
134
corresponding sub-array with dimension *N - 1*. If *N = 1*
135
then the returned object is an array scalar. These objects are
136
explained in :ref:`arrays.scalars`.
138
- If the selection tuple has all entries ``:`` except the
139
*p*-th entry which is a slice object ``i:j:k``,
140
then the returned array has dimension *N* formed by
141
concatenating the sub-arrays returned by integer indexing of
142
elements *i*, *i+k*, ..., *i + (m - 1) k < j*,
144
- Basic slicing with more than one non-``:`` entry in the slicing
145
tuple, acts like repeated application of slicing using a single
146
non-``:`` entry, where the non-``:`` entries are successively taken
147
(with all other non-``:`` entries replaced by ``:``). Thus,
148
``x[ind1,...,ind2,:]`` acts like ``x[ind1][...,ind2,:]`` under basic
151
.. warning:: The above is **not** true for advanced slicing.
153
- You may use slicing to set values in the array, but (unlike lists) you
154
can never grow the array. The size of the value to be set in
155
``x[obj] = value`` must be (broadcastable) to the same shape as
163
Remember that a slicing tuple can always be constructed as *obj*
164
and used in the ``x[obj]`` notation. Slice objects can be used in
165
the construction in place of the ``[start:stop:step]``
166
notation. For example, ``x[1:10:5,::-1]`` can also be implemented
167
as ``obj = (slice(1,10,5), slice(None,None,-1)); x[obj]`` . This
168
can be useful for constructing generic code that works on arrays
169
of arbitrary dimension.
173
The :const:`newaxis` object can be used in the basic slicing syntax
174
discussed above. :const:`None` can also be used instead of
181
Advanced indexing is triggered when the selection object, *obj*, is a
182
non-tuple sequence object, an :class:`ndarray` (of data type integer or bool),
183
or a tuple with at least one sequence object or ndarray (of data type
184
integer or bool). There are two types of advanced indexing: integer
187
Advanced indexing always returns a *copy* of the data (contrast with
188
basic slicing that returns a :term:`view`).
193
Integer indexing allows selection of arbitrary items in the array
194
based on their *N*-dimensional index. This kind of selection occurs
195
when advanced indexing is triggered and the selection object is not
196
an array of data type bool. For the discussion below, when the
197
selection object is not a tuple, it will be referred to as if it had
198
been promoted to a 1-tuple, which will be called the selection
199
tuple. The rules of advanced integer-style indexing are:
201
- If the length of the selection tuple is larger than *N* an error is raised.
203
- All sequences and scalars in the selection tuple are converted to
204
:class:`intp` indexing arrays.
206
- All selection tuple objects must be convertible to :class:`intp`
207
arrays, :class:`slice` objects, or the :const:`Ellipsis` object.
209
- The first :const:`Ellipsis` object will be expanded, and any other
210
:const:`Ellipsis` objects will be treated as full slice (``:``)
211
objects. The expanded :const:`Ellipsis` object is replaced with as
212
many full slice (``:``) objects as needed to make the length of the
213
selection tuple :math:`N`.
215
- If the selection tuple is smaller than *N*, then as many ``:``
216
objects as needed are added to the end of the selection tuple so
217
that the modified selection tuple has length *N*.
219
- All the integer indexing arrays must be :ref:`broadcastable
220
<arrays.broadcasting.broadcastable>` to the same shape.
222
- The shape of the output (or the needed shape of the object to be used
223
for setting) is the broadcasted shape.
225
- After expanding any ellipses and filling out any missing ``:``
226
objects in the selection tuple, then let :math:`N_t` be the number
227
of indexing arrays, and let :math:`N_s = N - N_t` be the number of
228
slice objects. Note that :math:`N_t > 0` (or we wouldn't be doing
229
advanced integer indexing).
231
- If :math:`N_s = 0` then the *M*-dimensional result is constructed by
232
varying the index tuple ``(i_1, ..., i_M)`` over the range
233
of the result shape and for each value of the index tuple
234
``(ind_1, ..., ind_M)``::
236
result[i_1, ..., i_M] == x[ind_1[i_1, ..., i_M], ind_2[i_1, ..., i_M],
237
..., ind_N[i_1, ..., i_M]]
239
.. admonition:: Example
241
Suppose the shape of the broadcasted indexing arrays is 3-dimensional
242
and *N* is 2. Then the result is found by letting *i, j, k* run over
243
the shape found by broadcasting ``ind_1`` and ``ind_2``, and each
246
result[i,j,k] = x[ind_1[i,j,k], ind_2[i,j,k]]
248
- If :math:`N_s > 0`, then partial indexing is done. This can be
249
somewhat mind-boggling to understand, but if you think in terms of
250
the shapes of the arrays involved, it can be easier to grasp what
251
happens. In simple cases (*i.e.* one indexing array and *N - 1* slice
252
objects) it does exactly what you would expect (concatenation of
253
repeated application of basic slicing). The rule for partial
254
indexing is that the shape of the result (or the interpreted shape
255
of the object to be used in setting) is the shape of *x* with the
256
indexed subspace replaced with the broadcasted indexing subspace. If
257
the index subspaces are right next to each other, then the
258
broadcasted indexing space directly replaces all of the indexed
259
subspaces in *x*. If the indexing subspaces are separated (by slice
260
objects), then the broadcasted indexing space is first, followed by
261
the sliced subspace of *x*.
263
.. admonition:: Example
265
Suppose ``x.shape`` is (10,20,30) and ``ind`` is a (2,3,4)-shaped
266
indexing :class:`intp` array, then ``result = x[...,ind,:]`` has
267
shape (10,2,3,4,30) because the (20,)-shaped subspace has been
268
replaced with a (2,3,4)-shaped broadcasted indexing subspace. If
269
we let *i, j, k* loop over the (2,3,4)-shaped subspace then
270
``result[...,i,j,k,:] = x[...,ind[i,j,k],:]``. This example
271
produces the same result as :meth:`x.take(ind, axis=-2) <ndarray.take>`.
273
.. admonition:: Example
275
Now let ``x.shape`` be (10,20,30,40,50) and suppose ``ind_1``
276
and ``ind_2`` are broadcastable to the shape (2,3,4). Then
277
``x[:,ind_1,ind_2]`` has shape (10,2,3,4,40,50) because the
278
(20,30)-shaped subspace from X has been replaced with the
279
(2,3,4) subspace from the indices. However,
280
``x[:,ind_1,:,ind_2]`` has shape (2,3,4,10,30,50) because there
281
is no unambiguous place to drop in the indexing subspace, thus
282
it is tacked-on to the beginning. It is always possible to use
283
:meth:`.transpose() <ndarray.transpose>` to move the subspace
284
anywhere desired. (Note that this example cannot be replicated
291
This advanced indexing occurs when obj is an array object of Boolean
292
type (such as may be returned from comparison operators). It is always
293
equivalent to (but faster than) ``x[obj.nonzero()]`` where, as
294
described above, :meth:`obj.nonzero() <ndarray.nonzero>` returns a
295
tuple (of length :attr:`obj.ndim <ndarray.ndim>`) of integer index
296
arrays showing the :const:`True` elements of *obj*.
298
The special case when ``obj.ndim == x.ndim`` is worth mentioning. In
299
this case ``x[obj]`` returns a 1-dimensional array filled with the
300
elements of *x* corresponding to the :const:`True` values of *obj*.
301
The search order will be C-style (last index varies the fastest). If
302
*obj* has :const:`True` values at entries that are outside of the
303
bounds of *x*, then an index error will be raised.
305
You can also use Boolean arrays as element of the selection tuple. In
306
such instances, they will always be interpreted as :meth:`nonzero(obj)
307
<ndarray.nonzero>` and the equivalent integer indexing will be
312
The definition of advanced indexing means that ``x[(1,2,3),]`` is
313
fundamentally different than ``x[(1,2,3)]``. The latter is
314
equivalent to ``x[1,2,3]`` which will trigger basic selection while
315
the former will trigger advanced indexing. Be sure to understand
318
Also recognize that ``x[[1,2,3]]`` will trigger advanced indexing,
319
whereas ``x[[1,2,slice(None)]]`` will trigger basic slicing.
323
XXX: this section may need some tuning...
324
Also the above warning needs explanation as the last part is at odds
325
with the definition of basic indexing.
328
.. _arrays.indexing.rec:
333
.. seealso:: :ref:`arrays.dtypes`, :ref:`arrays.scalars`
335
If the :class:`ndarray` object is a record array, *i.e.* its data type
336
is a :term:`record` data type, the :term:`fields <field>` of the array
337
can be accessed by indexing the array with strings, dictionary-like.
339
Indexing ``x['field-name']`` returns a new :term:`view` to the array,
340
which is of the same shape as *x* (except when the field is a
341
sub-array) but of data type ``x.dtype['field-name']`` and contains
342
only the part of the data in the specified field. Also record array
343
scalars can be "indexed" this way.
345
If the accessed field is a sub-array, the dimensions of the sub-array
346
are appended to the shape of the result.
348
.. admonition:: Example
350
>>> x = np.zeros((2,2), dtype=[('a', np.int32), ('b', np.float64, (3,3))])
361
Flat Iterator indexing
362
----------------------
364
:attr:`x.flat <ndarray.flat>` returns an iterator that will iterate
365
over the entire array (in C-contiguous style with the last index
366
varying the fastest). This iterator object can also be indexed using
367
basic slicing or advanced indexing as long as the selection object is
368
not a tuple. This should be clear from the fact that :attr:`x.flat
369
<ndarray.flat>` is a 1-dimensional view. It can be used for integer
370
indexing with 1-dimensional C-style-flat indices. The shape of any
371
returned array is therefore the shape of the integer indexing object.
added
removed
source/reference/arrays.indexing.rst
