Take elements from an array along an axis. When axis is not None, this function does the same thing as "fancy" indexing (indexing arrays using arrays); however, it can be easier to use if you need elements along a given axis. A call such as ``np.take(arr, indices, axis=3)`` is
(a, indices, axis=None, out=None, mode='raise')
| 94 | |
| 95 | @array_function_dispatch(_take_dispatcher) |
| 96 | def take(a, indices, axis=None, out=None, mode='raise'): |
| 97 | """ |
| 98 | Take elements from an array along an axis. |
| 99 | |
| 100 | When axis is not None, this function does the same thing as "fancy" |
| 101 | indexing (indexing arrays using arrays); however, it can be easier to use |
| 102 | if you need elements along a given axis. A call such as |
| 103 | ``np.take(arr, indices, axis=3)`` is equivalent to |
| 104 | ``arr[:,:,:,indices,...]``. |
| 105 | |
| 106 | Explained without fancy indexing, this is equivalent to the following use |
| 107 | of `ndindex`, which sets each of ``ii``, ``jj``, and ``kk`` to a tuple of |
| 108 | indices:: |
| 109 | |
| 110 | Ni, Nk = a.shape[:axis], a.shape[axis+1:] |
| 111 | Nj = indices.shape |
| 112 | for ii in ndindex(Ni): |
| 113 | for jj in ndindex(Nj): |
| 114 | for kk in ndindex(Nk): |
| 115 | out[ii + jj + kk] = a[ii + (indices[jj],) + kk] |
| 116 | |
| 117 | Parameters |
| 118 | ---------- |
| 119 | a : array_like (Ni..., M, Nk...) |
| 120 | The source array. |
| 121 | indices : array_like (Nj...) |
| 122 | The indices of the values to extract. |
| 123 | |
| 124 | .. versionadded:: 1.8.0 |
| 125 | |
| 126 | Also allow scalars for indices. |
| 127 | axis : int, optional |
| 128 | The axis over which to select values. By default, the flattened |
| 129 | input array is used. |
| 130 | out : ndarray, optional (Ni..., Nj..., Nk...) |
| 131 | If provided, the result will be placed in this array. It should |
| 132 | be of the appropriate shape and dtype. Note that `out` is always |
| 133 | buffered if `mode='raise'`; use other modes for better performance. |
| 134 | mode : {'raise', 'wrap', 'clip'}, optional |
| 135 | Specifies how out-of-bounds indices will behave. |
| 136 | |
| 137 | * 'raise' -- raise an error (default) |
| 138 | * 'wrap' -- wrap around |
| 139 | * 'clip' -- clip to the range |
| 140 | |
| 141 | 'clip' mode means that all indices that are too large are replaced |
| 142 | by the index that addresses the last element along that axis. Note |
| 143 | that this disables indexing with negative numbers. |
| 144 | |
| 145 | Returns |
| 146 | ------- |
| 147 | out : ndarray (Ni..., Nj..., Nk...) |
| 148 | The returned array has the same type as `a`. |
| 149 | |
| 150 | See Also |
| 151 | -------- |
| 152 | compress : Take elements using a boolean mask |
| 153 | ndarray.take : equivalent method |