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