fromnumeric.pyc
1 o 2 [��c 3 � � @ s2 d Z ddlZddlZddlZddlZddlmZ ddlm Z ddlm 4 Z ddlm Z ddlmZmZmZmZ dd lmZ e jZg d 5 �ZejZeZeje jd d �Zd d� Z dd� Z dd� Z d�dd�Z ee �d�dd��Z d�dd�Z!ee!�d�dd ��Z"d�d d �Z#ee#�d�d d ��Z$d�d!d"�Z%ee%�d�d#d$��Z&d�d%d&�Z'ee'�d�d'd(��Z(d)d*� Z)ee)�d+d,� �Z*d�d-d.�Z+ee+�d�d/d0��Z,d�d1d2�Z-ee-�d�d5d6��Z.d�d7d8�Z/ee/�d�d9d:��Z0d�d;d<�Z1ee1�d�d=d>��Z2d�d?d@�Z3ee3�d�dAdB��Z4d�ej5dC�dDdE�Z6ee6�d�ej5dC�dFdG��Z7d�ej5dC�dHdI�Z8ee8�d�ej5dC�dJdK��Z9d�dLdM�Z:ee:�d�dOdP��Z;dQdR� Z<ee<�dSdT� �Z=d�dUdV�Z>ee>�d�dWdX��Z?d�dYdZ�Z@ee@�d�d[d\��ZA d�d]d^�ZBeeB�d�d_d`��ZCd�dadb�ZDeeD�d�dcdd��ZEdedf� ZFeeF�dgdh� �ZGdidj� ZHeeH�dkdl� �ZId�dmdn�ZJeeJ�d�dodp��ZKd�dqdr�ZLeeL�d�dsdt��ZM d�dudv�ZNeeN�dddej5ej5ej5fdwdx��Zd�ej5dy�dzd{�ZOeeO�ddej5fej5dy�d|d}��ZPd�ddy�d~d�ZQeeQ�ddej5fej5dy�d�d���ZRd�d�d��ZSeeS�d�d�d���ZTd�d�d��ZUeeU�ddej5fd�d���ZV d�d�d��ZWeeW�ddej5ej5ej5fd�d���ZX d�d�d��ZYeeY�ddej5ej5ej5fd�d���ZZ d�d�d��Z[ee[�dddej5ej5ej5fd�d���Z\d�d�d��Z]ee]�d�d�d���Z^d�d�� Z_ee_�d�d�� �Z`d�d�d��Zaeea�d�d�d���Zbd�d�d��Zceec�d�d�d���Zdd�ddy�d�d��Zeeee�dddej5fej5dy�d�d���Zf d�ddy�d�d��Zgeeg�ddddej5fej5dy�d�d���Zh d�ddy�d�d��Zieei�ddddej5fej5dy�d�d���Zjeec�d�d�d���Zkee[d�d��d�d�� �Zlee]d�d��d�d�� �ZmeeOd�d��d�d�� �ZneeQd�d��d�d�� �ZodS )�zCModule containing non-deprecated functions borrowed from Numeric. 6 7 � N� )� 8 multiarray)� overrides)�umath)� numerictypes)�asarray�array� 9 asanyarray� concatenate)�_methods)+�all�alltrue�amax�amin�any�argmax�argmin� argpartition�argsort�around�choose�clip�compress�cumprod� 10 cumproduct�cumsum�diagonal�mean�ndim�nonzero� partition�prod�product�ptp�put�ravel�repeat�reshape�resize�round_� searchsorted�shape�size�sometrue�sort�squeeze�std�sum�swapaxes�take�trace� transpose�var�numpy)�modulec O s^ z| j }W n ty d }Y nw tt| �|�|i |��}|r-t|tj�s)t|�}||�}|S �N)�__array_wrap__�AttributeError�getattrr � 11 isinstance�mu�ndarray)�obj�method�args�kwds�wrap�result� rF ��C:\Users\Jacks.GUTTSPC\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.10_qbz5n2kfra8p0\LocalCache\local-packages\Python310\site-packages\numpy\core\fromnumeric.py�_wrapit& s 12 � rH c O sh t | |d �}|d u rt| |g|�R i |��S z||i |��W S ty3 t| |g|�R i |�� Y S w r9 )r< rH � TypeError)r@ rA rB rC �boundrF rF rG � _wrapfunc3 s �rK c K s� dd� |� � D �}t| �tjur:zt| |�}W n ty Y nw |d ur0|d|||d�|��S |d||d�|��S |j| |||fi |��S )Nc S s i | ] \}}|t jur||�qS rF )�np�_NoValue)�.0�k�vrF rF rG � 13 <dictcomp>F s 14 �z"_wrapreduction.<locals>.<dictcomp>��axis�dtype�out�rS rU rF )�items�typer> r? r< r; �reduce) r@ �ufuncrA rS rT rU �kwargsZ 15 passkwargs� reductionrF rF rG �_wrapreductionE s �r] c C � | |fS r9 rF ��a�indicesrS rU �moderF rF rG �_take_dispatcherY � rc �raisec C � t | d||||d�S )ac 16 Take elements from an array along an axis. 17 18 When axis is not None, this function does the same thing as "fancy" 19 indexing (indexing arrays using arrays); however, it can be easier to use 20 if you need elements along a given axis. A call such as 21 ``np.take(arr, indices, axis=3)`` is equivalent to 22 ``arr[:,:,:,indices,...]``. 23 24 Explained without fancy indexing, this is equivalent to the following use 25 of `ndindex`, which sets each of ``ii``, ``jj``, and ``kk`` to a tuple of 26 indices:: 27 28 Ni, Nk = a.shape[:axis], a.shape[axis+1:] 29 Nj = indices.shape 30 for ii in ndindex(Ni): 31 for jj in ndindex(Nj): 32 for kk in ndindex(Nk): 33 out[ii + jj + kk] = a[ii + (indices[jj],) + kk] 34 35 Parameters 36 ---------- 37 a : array_like (Ni..., M, Nk...) 38 The source array. 39 indices : array_like (Nj...) 40 The indices of the values to extract. 41 42 .. versionadded:: 1.8.0 43 44 Also allow scalars for indices. 45 axis : int, optional 46 The axis over which to select values. By default, the flattened 47 input array is used. 48 out : ndarray, optional (Ni..., Nj..., Nk...) 49 If provided, the result will be placed in this array. It should 50 be of the appropriate shape and dtype. Note that `out` is always 51 buffered if `mode='raise'`; use other modes for better performance. 52 mode : {'raise', 'wrap', 'clip'}, optional 53 Specifies how out-of-bounds indices will behave. 54 55 * 'raise' -- raise an error (default) 56 * 'wrap' -- wrap around 57 * 'clip' -- clip to the range 58 59 'clip' mode means that all indices that are too large are replaced 60 by the index that addresses the last element along that axis. Note 61 that this disables indexing with negative numbers. 62 63 Returns 64 ------- 65 out : ndarray (Ni..., Nj..., Nk...) 66 The returned array has the same type as `a`. 67 68 See Also 69 -------- 70 compress : Take elements using a boolean mask 71 ndarray.take : equivalent method 72 take_along_axis : Take elements by matching the array and the index arrays 73 74 Notes 75 ----- 76 77 By eliminating the inner loop in the description above, and using `s_` to 78 build simple slice objects, `take` can be expressed in terms of applying 79 fancy indexing to each 1-d slice:: 80 81 Ni, Nk = a.shape[:axis], a.shape[axis+1:] 82 for ii in ndindex(Ni): 83 for kk in ndindex(Nj): 84 out[ii + s_[...,] + kk] = a[ii + s_[:,] + kk][indices] 85 86 For this reason, it is equivalent to (but faster than) the following use 87 of `apply_along_axis`:: 88 89 out = np.apply_along_axis(lambda a_1d: a_1d[indices], axis, a) 90 91 Examples 92 -------- 93 >>> a = [4, 3, 5, 7, 6, 8] 94 >>> indices = [0, 1, 4] 95 >>> np.take(a, indices) 96 array([4, 3, 6]) 97 98 In this example if `a` is an ndarray, "fancy" indexing can be used. 99 100 >>> a = np.array(a) 101 >>> a[indices] 102 array([4, 3, 6]) 103 104 If `indices` is not one dimensional, the output also has these dimensions. 105 106 >>> np.take(a, [[0, 1], [2, 3]]) 107 array([[4, 3], 108 [5, 7]]) 109 r3 )rS rU rb �rK r_ rF rF rG r3 ] s ar3 c C � | fS r9 rF �r` �newshape�orderrF rF rG �_reshape_dispatcher� � rl �Cc C � t | d||d�S )a 110 Gives a new shape to an array without changing its data. 111 112 Parameters 113 ---------- 114 a : array_like 115 Array to be reshaped. 116 newshape : int or tuple of ints 117 The new shape should be compatible with the original shape. If 118 an integer, then the result will be a 1-D array of that length. 119 One shape dimension can be -1. In this case, the value is 120 inferred from the length of the array and remaining dimensions. 121 order : {'C', 'F', 'A'}, optional 122 Read the elements of `a` using this index order, and place the 123 elements into the reshaped array using this index order. 'C' 124 means to read / write the elements using C-like index order, 125 with the last axis index changing fastest, back to the first 126 axis index changing slowest. 'F' means to read / write the 127 elements using Fortran-like index order, with the first index 128 changing fastest, and the last index changing slowest. Note that 129 the 'C' and 'F' options take no account of the memory layout of 130 the underlying array, and only refer to the order of indexing. 131 'A' means to read / write the elements in Fortran-like index 132 order if `a` is Fortran *contiguous* in memory, C-like order 133 otherwise. 134 135 Returns 136 ------- 137 reshaped_array : ndarray 138 This will be a new view object if possible; otherwise, it will 139 be a copy. Note there is no guarantee of the *memory layout* (C- or 140 Fortran- contiguous) of the returned array. 141 142 See Also 143 -------- 144 ndarray.reshape : Equivalent method. 145 146 Notes 147 ----- 148 It is not always possible to change the shape of an array without 149 copying the data. If you want an error to be raised when the data is copied, 150 you should assign the new shape to the shape attribute of the array:: 151 152 >>> a = np.zeros((10, 2)) 153 154 # A transpose makes the array non-contiguous 155 >>> b = a.T 156 157 # Taking a view makes it possible to modify the shape without modifying 158 # the initial object. 159 >>> c = b.view() 160 >>> c.shape = (20) 161 Traceback (most recent call last): 162 ... 163 AttributeError: Incompatible shape for in-place modification. Use 164 `.reshape()` to make a copy with the desired shape. 165 166 The `order` keyword gives the index ordering both for *fetching* the values 167 from `a`, and then *placing* the values into the output array. 168 For example, let's say you have an array: 169 170 >>> a = np.arange(6).reshape((3, 2)) 171 >>> a 172 array([[0, 1], 173 [2, 3], 174 [4, 5]]) 175 176 You can think of reshaping as first raveling the array (using the given 177 index order), then inserting the elements from the raveled array into the 178 new array using the same kind of index ordering as was used for the 179 raveling. 180 181 >>> np.reshape(a, (2, 3)) # C-like index ordering 182 array([[0, 1, 2], 183 [3, 4, 5]]) 184 >>> np.reshape(np.ravel(a), (2, 3)) # equivalent to C ravel then C reshape 185 array([[0, 1, 2], 186 [3, 4, 5]]) 187 >>> np.reshape(a, (2, 3), order='F') # Fortran-like index ordering 188 array([[0, 4, 3], 189 [2, 1, 5]]) 190 >>> np.reshape(np.ravel(a, order='F'), (2, 3), order='F') 191 array([[0, 4, 3], 192 [2, 1, 5]]) 193 194 Examples 195 -------- 196 >>> a = np.array([[1,2,3], [4,5,6]]) 197 >>> np.reshape(a, 6) 198 array([1, 2, 3, 4, 5, 6]) 199 >>> np.reshape(a, 6, order='F') 200 array([1, 4, 2, 5, 3, 6]) 201 202 >>> np.reshape(a, (3,-1)) # the unspecified value is inferred to be 2 203 array([[1, 2], 204 [3, 4], 205 [5, 6]]) 206 r' �rk rg ri rF rF rG r' � s dr' c c s � | V |E d H |V d S r9 rF �r` �choicesrU rb rF rF rG �_choose_dispatcher- s � 207 208 rs c C � t | d|||d�S )a@ 209 Construct an array from an index array and a list of arrays to choose from. 210 211 First of all, if confused or uncertain, definitely look at the Examples - 212 in its full generality, this function is less simple than it might 213 seem from the following code description (below ndi = 214 `numpy.lib.index_tricks`): 215 216 ``np.choose(a,c) == np.array([c[a[I]][I] for I in ndi.ndindex(a.shape)])``. 217 218 But this omits some subtleties. Here is a fully general summary: 219 220 Given an "index" array (`a`) of integers and a sequence of ``n`` arrays 221 (`choices`), `a` and each choice array are first broadcast, as necessary, 222 to arrays of a common shape; calling these *Ba* and *Bchoices[i], i = 223 0,...,n-1* we have that, necessarily, ``Ba.shape == Bchoices[i].shape`` 224 for each ``i``. Then, a new array with shape ``Ba.shape`` is created as 225 follows: 226 227 * if ``mode='raise'`` (the default), then, first of all, each element of 228 ``a`` (and thus ``Ba``) must be in the range ``[0, n-1]``; now, suppose 229 that ``i`` (in that range) is the value at the ``(j0, j1, ..., jm)`` 230 position in ``Ba`` - then the value at the same position in the new array 231 is the value in ``Bchoices[i]`` at that same position; 232 233 * if ``mode='wrap'``, values in `a` (and thus `Ba`) may be any (signed) 234 integer; modular arithmetic is used to map integers outside the range 235 `[0, n-1]` back into that range; and then the new array is constructed 236 as above; 237 238 * if ``mode='clip'``, values in `a` (and thus ``Ba``) may be any (signed) 239 integer; negative integers are mapped to 0; values greater than ``n-1`` 240 are mapped to ``n-1``; and then the new array is constructed as above. 241 242 Parameters 243 ---------- 244 a : int array 245 This array must contain integers in ``[0, n-1]``, where ``n`` is the 246 number of choices, unless ``mode=wrap`` or ``mode=clip``, in which 247 cases any integers are permissible. 248 choices : sequence of arrays 249 Choice arrays. `a` and all of the choices must be broadcastable to the 250 same shape. If `choices` is itself an array (not recommended), then 251 its outermost dimension (i.e., the one corresponding to 252 ``choices.shape[0]``) is taken as defining the "sequence". 253 out : array, optional 254 If provided, the result will be inserted into this array. It should 255 be of the appropriate shape and dtype. Note that `out` is always 256 buffered if ``mode='raise'``; use other modes for better performance. 257 mode : {'raise' (default), 'wrap', 'clip'}, optional 258 Specifies how indices outside ``[0, n-1]`` will be treated: 259 260 * 'raise' : an exception is raised 261 * 'wrap' : value becomes value mod ``n`` 262 * 'clip' : values < 0 are mapped to 0, values > n-1 are mapped to n-1 263 264 Returns 265 ------- 266 merged_array : array 267 The merged result. 268 269 Raises 270 ------ 271 ValueError: shape mismatch 272 If `a` and each choice array are not all broadcastable to the same 273 shape. 274 275 See Also 276 -------- 277 ndarray.choose : equivalent method 278 numpy.take_along_axis : Preferable if `choices` is an array 279 280 Notes 281 ----- 282 To reduce the chance of misinterpretation, even though the following 283 "abuse" is nominally supported, `choices` should neither be, nor be 284 thought of as, a single array, i.e., the outermost sequence-like container 285 should be either a list or a tuple. 286 287 Examples 288 -------- 289 290 >>> choices = [[0, 1, 2, 3], [10, 11, 12, 13], 291 ... [20, 21, 22, 23], [30, 31, 32, 33]] 292 >>> np.choose([2, 3, 1, 0], choices 293 ... # the first element of the result will be the first element of the 294 ... # third (2+1) "array" in choices, namely, 20; the second element 295 ... # will be the second element of the fourth (3+1) choice array, i.e., 296 ... # 31, etc. 297 ... ) 298 array([20, 31, 12, 3]) 299 >>> np.choose([2, 4, 1, 0], choices, mode='clip') # 4 goes to 3 (4-1) 300 array([20, 31, 12, 3]) 301 >>> # because there are 4 choice arrays 302 >>> np.choose([2, 4, 1, 0], choices, mode='wrap') # 4 goes to (4 mod 4) 303 array([20, 1, 12, 3]) 304 >>> # i.e., 0 305 306 A couple examples illustrating how choose broadcasts: 307 308 >>> a = [[1, 0, 1], [0, 1, 0], [1, 0, 1]] 309 >>> choices = [-10, 10] 310 >>> np.choose(a, choices) 311 array([[ 10, -10, 10], 312 [-10, 10, -10], 313 [ 10, -10, 10]]) 314 315 >>> # With thanks to Anne Archibald 316 >>> a = np.array([0, 1]).reshape((2,1,1)) 317 >>> c1 = np.array([1, 2, 3]).reshape((1,3,1)) 318 >>> c2 = np.array([-1, -2, -3, -4, -5]).reshape((1,1,5)) 319 >>> np.choose(a, (c1, c2)) # result is 2x3x5, res[0,:,:]=c1, res[1,:,:]=c2 320 array([[[ 1, 1, 1, 1, 1], 321 [ 2, 2, 2, 2, 2], 322 [ 3, 3, 3, 3, 3]], 323 [[-1, -2, -3, -4, -5], 324 [-1, -2, -3, -4, -5], 325 [-1, -2, -3, -4, -5]]]) 326 327 r )rU rb rg rq rF rF rG r 3 s zr c C rh r9 rF �r` �repeatsrS rF rF rG �_repeat_dispatcher� rm rw c C ro )a 328 Repeat elements of an array. 329 330 Parameters 331 ---------- 332 a : array_like 333 Input array. 334 repeats : int or array of ints 335 The number of repetitions for each element. `repeats` is broadcasted 336 to fit the shape of the given axis. 337 axis : int, optional 338 The axis along which to repeat values. By default, use the 339 flattened input array, and return a flat output array. 340 341 Returns 342 ------- 343 repeated_array : ndarray 344 Output array which has the same shape as `a`, except along 345 the given axis. 346 347 See Also 348 -------- 349 tile : Tile an array. 350 unique : Find the unique elements of an array. 351 352 Examples 353 -------- 354 >>> np.repeat(3, 4) 355 array([3, 3, 3, 3]) 356 >>> x = np.array([[1,2],[3,4]]) 357 >>> np.repeat(x, 2) 358 array([1, 1, 2, 2, 3, 3, 4, 4]) 359 >>> np.repeat(x, 3, axis=1) 360 array([[1, 1, 1, 2, 2, 2], 361 [3, 3, 3, 4, 4, 4]]) 362 >>> np.repeat(x, [1, 2], axis=0) 363 array([[1, 2], 364 [3, 4], 365 [3, 4]]) 366 367 r& �rS rg ru rF rF rG r& � s +r& c C � 368 | ||fS r9 rF )r` �indrP rb rF rF rG �_put_dispatcher� � 369 r{ c 370 C sJ z| j }W n ty } z tdjt| �jd��|�d}~ww ||||d�S )aN 371 Replaces specified elements of an array with given values. 372 373 The indexing works on the flattened target array. `put` is roughly 374 equivalent to: 375 376 :: 377 378 a.flat[ind] = v 379 380 Parameters 381 ---------- 382 a : ndarray 383 Target array. 384 ind : array_like 385 Target indices, interpreted as integers. 386 v : array_like 387 Values to place in `a` at target indices. If `v` is shorter than 388 `ind` it will be repeated as necessary. 389 mode : {'raise', 'wrap', 'clip'}, optional 390 Specifies how out-of-bounds indices will behave. 391 392 * 'raise' -- raise an error (default) 393 * 'wrap' -- wrap around 394 * 'clip' -- clip to the range 395 396 'clip' mode means that all indices that are too large are replaced 397 by the index that addresses the last element along that axis. Note 398 that this disables indexing with negative numbers. In 'raise' mode, 399 if an exception occurs the target array may still be modified. 400 401 See Also 402 -------- 403 putmask, place 404 put_along_axis : Put elements by matching the array and the index arrays 405 406 Examples 407 -------- 408 >>> a = np.arange(5) 409 >>> np.put(a, [0, 2], [-44, -55]) 410 >>> a 411 array([-44, 1, -55, 3, 4]) 412 413 >>> a = np.arange(5) 414 >>> np.put(a, 22, -5, mode='clip') 415 >>> a 416 array([ 0, 1, 2, 3, -5]) 417 418 z,argument 1 must be numpy.ndarray, not {name})�nameN)rb )r$ r; rI �formatrX �__name__)r` rz rP rb r$ �erF rF rG r$ � s 3 419 420 ����r$ c C rh r9 rF �r` �axis1�axis2rF rF rG �_swapaxes_dispatcher" rm r� c C s t | d||�S )a� 421 Interchange two axes of an array. 422 423 Parameters 424 ---------- 425 a : array_like 426 Input array. 427 axis1 : int 428 First axis. 429 axis2 : int 430 Second axis. 431 432 Returns 433 ------- 434 a_swapped : ndarray 435 For NumPy >= 1.10.0, if `a` is an ndarray, then a view of `a` is 436 returned; otherwise a new array is created. For earlier NumPy 437 versions a view of `a` is returned only if the order of the 438 axes is changed, otherwise the input array is returned. 439 440 Examples 441 -------- 442 >>> x = np.array([[1,2,3]]) 443 >>> np.swapaxes(x,0,1) 444 array([[1], 445 [2], 446 [3]]) 447 448 >>> x = np.array([[[0,1],[2,3]],[[4,5],[6,7]]]) 449 >>> x 450 array([[[0, 1], 451 [2, 3]], 452 [[4, 5], 453 [6, 7]]]) 454 455 >>> np.swapaxes(x,0,2) 456 array([[[0, 4], 457 [2, 6]], 458 [[1, 5], 459 [3, 7]]]) 460 461 r2 rg r� rF rF rG r2 & s ,r2 c C rh r9 rF �r` �axesrF rF rG �_transpose_dispatcherU rm r� c C s t | d|�S )a� 462 Returns an array with axes transposed. 463 464 For a 1-D array, this returns an unchanged view of the original array, as a 465 transposed vector is simply the same vector. 466 To convert a 1-D array into a 2-D column vector, an additional dimension 467 must be added, e.g., ``np.atleast2d(a).T`` achieves this, as does 468 ``a[:, np.newaxis]``. 469 For a 2-D array, this is the standard matrix transpose. 470 For an n-D array, if axes are given, their order indicates how the 471 axes are permuted (see Examples). If axes are not provided, then 472 ``transpose(a).shape == a.shape[::-1]``. 473 474 Parameters 475 ---------- 476 a : array_like 477 Input array. 478 axes : tuple or list of ints, optional 479 If specified, it must be a tuple or list which contains a permutation 480 of [0,1,...,N-1] where N is the number of axes of `a`. The `i`'th axis 481 of the returned array will correspond to the axis numbered ``axes[i]`` 482 of the input. If not specified, defaults to ``range(a.ndim)[::-1]``, 483 which reverses the order of the axes. 484 485 Returns 486 ------- 487 p : ndarray 488 `a` with its axes permuted. A view is returned whenever possible. 489 490 See Also 491 -------- 492 ndarray.transpose : Equivalent method. 493 moveaxis : Move axes of an array to new positions. 494 argsort : Return the indices that would sort an array. 495 496 Notes 497 ----- 498 Use ``transpose(a, argsort(axes))`` to invert the transposition of tensors 499 when using the `axes` keyword argument. 500 501 Examples 502 -------- 503 >>> a = np.array([[1, 2], [3, 4]]) 504 >>> a 505 array([[1, 2], 506 [3, 4]]) 507 >>> np.transpose(a) 508 array([[1, 3], 509 [2, 4]]) 510 511 >>> a = np.array([1, 2, 3, 4]) 512 >>> a 513 array([1, 2, 3, 4]) 514 >>> np.transpose(a) 515 array([1, 2, 3, 4]) 516 517 >>> a = np.ones((1, 2, 3)) 518 >>> np.transpose(a, (1, 0, 2)).shape 519 (2, 1, 3) 520 521 >>> a = np.ones((2, 3, 4, 5)) 522 >>> np.transpose(a).shape 523 (5, 4, 3, 2) 524 525 r5 rg r� rF rF rG r5 Y s Cr5 c C rh r9 rF �r` �kthrS �kindrk rF rF rG �_partition_dispatcher� rm r� ������ introselectc C s@ |du r t | ��� } d}nt | �jdd�} | j||||d� | S )aM 526 Return a partitioned copy of an array. 527 528 Creates a copy of the array with its elements rearranged in such a 529 way that the value of the element in k-th position is in the position 530 the value would be in a sorted array. In the partitioned array, all 531 elements before the k-th element are less than or equal to that 532 element, and all the elements after the k-th element are greater than 533 or equal to that element. The ordering of the elements in the two 534 partitions is undefined. 535 536 .. versionadded:: 1.8.0 537 538 Parameters 539 ---------- 540 a : array_like 541 Array to be sorted. 542 kth : int or sequence of ints 543 Element index to partition by. The k-th value of the element 544 will be in its final sorted position and all smaller elements 545 will be moved before it and all equal or greater elements behind 546 it. The order of all elements in the partitions is undefined. If 547 provided with a sequence of k-th it will partition all elements 548 indexed by k-th of them into their sorted position at once. 549 550 .. deprecated:: 1.22.0 551 Passing booleans as index is deprecated. 552 axis : int or None, optional 553 Axis along which to sort. If None, the array is flattened before 554 sorting. The default is -1, which sorts along the last axis. 555 kind : {'introselect'}, optional 556 Selection algorithm. Default is 'introselect'. 557 order : str or list of str, optional 558 When `a` is an array with fields defined, this argument 559 specifies which fields to compare first, second, etc. A single 560 field can be specified as a string. Not all fields need be 561 specified, but unspecified fields will still be used, in the 562 order in which they come up in the dtype, to break ties. 563 564 Returns 565 ------- 566 partitioned_array : ndarray 567 Array of the same type and shape as `a`. 568 569 See Also 570 -------- 571 ndarray.partition : Method to sort an array in-place. 572 argpartition : Indirect partition. 573 sort : Full sorting 574 575 Notes 576 ----- 577 The various selection algorithms are characterized by their average 578 speed, worst case performance, work space size, and whether they are 579 stable. A stable sort keeps items with the same key in the same 580 relative order. The available algorithms have the following 581 properties: 582 583 ================= ======= ============= ============ ======= 584 kind speed worst case work space stable 585 ================= ======= ============= ============ ======= 586 'introselect' 1 O(n) 0 no 587 ================= ======= ============= ============ ======= 588 589 All the partition algorithms make temporary copies of the data when 590 partitioning along any but the last axis. Consequently, 591 partitioning along the last axis is faster and uses less space than 592 partitioning along any other axis. 593 594 The sort order for complex numbers is lexicographic. If both the 595 real and imaginary parts are non-nan then the order is determined by 596 the real parts except when they are equal, in which case the order 597 is determined by the imaginary parts. 598 599 Examples 600 -------- 601 >>> a = np.array([7, 1, 7, 7, 1, 5, 7, 2, 3, 2, 6, 2, 3, 0]) 602 >>> p = np.partition(a, 4) 603 >>> p 604 array([0, 1, 2, 1, 2, 5, 2, 3, 3, 6, 7, 7, 7, 7]) 605 606 ``p[4]`` is 2; all elements in ``p[:4]`` are less than or equal 607 to ``p[4]``, and all elements in ``p[5:]`` are greater than or 608 equal to ``p[4]``. The partition is:: 609 610 [0, 1, 2, 1], [2], [5, 2, 3, 3, 6, 7, 7, 7, 7] 611 612 The next example shows the use of multiple values passed to `kth`. 613 614 >>> p2 = np.partition(a, (4, 8)) 615 >>> p2 616 array([0, 1, 2, 1, 2, 3, 3, 2, 5, 6, 7, 7, 7, 7]) 617 618 ``p2[4]`` is 2 and ``p2[8]`` is 5. All elements in ``p2[:4]`` 619 are less than or equal to ``p2[4]``, all elements in ``p2[5:8]`` 620 are greater than or equal to ``p2[4]`` and less than or equal to 621 ``p2[8]``, and all elements in ``p2[9:]`` are greater than or 622 equal to ``p2[8]``. The partition is:: 623 624 [0, 1, 2, 1], [2], [3, 3, 2], [5], [6, 7, 7, 7, 7] 625 Nr� �Krp �rS r� rk )r �flatten�copyr r� rF rF rG r � s g r c C rh r9 rF r� rF rF rG �_argpartition_dispatcher rm r� c C rf )a� 626 627 Perform an indirect partition along the given axis using the 628 algorithm specified by the `kind` keyword. It returns an array of 629 indices of the same shape as `a` that index data along the given 630 axis in partitioned order. 631 632 .. versionadded:: 1.8.0 633 634 Parameters 635 ---------- 636 a : array_like 637 Array to sort. 638 kth : int or sequence of ints 639 Element index to partition by. The k-th element will be in its 640 final sorted position and all smaller elements will be moved 641 before it and all larger elements behind it. The order of all 642 elements in the partitions is undefined. If provided with a 643 sequence of k-th it will partition all of them into their sorted 644 position at once. 645 646 .. deprecated:: 1.22.0 647 Passing booleans as index is deprecated. 648 axis : int or None, optional 649 Axis along which to sort. The default is -1 (the last axis). If 650 None, the flattened array is used. 651 kind : {'introselect'}, optional 652 Selection algorithm. Default is 'introselect' 653 order : str or list of str, optional 654 When `a` is an array with fields defined, this argument 655 specifies which fields to compare first, second, etc. A single 656 field can be specified as a string, and not all fields need be 657 specified, but unspecified fields will still be used, in the 658 order in which they come up in the dtype, to break ties. 659 660 Returns 661 ------- 662 index_array : ndarray, int 663 Array of indices that partition `a` along the specified axis. 664 If `a` is one-dimensional, ``a[index_array]`` yields a partitioned `a`. 665 More generally, ``np.take_along_axis(a, index_array, axis=axis)`` 666 always yields the partitioned `a`, irrespective of dimensionality. 667 668 See Also 669 -------- 670 partition : Describes partition algorithms used. 671 ndarray.partition : Inplace partition. 672 argsort : Full indirect sort. 673 take_along_axis : Apply ``index_array`` from argpartition 674 to an array as if by calling partition. 675 676 Notes 677 ----- 678 See `partition` for notes on the different selection algorithms. 679 680 Examples 681 -------- 682 One dimensional array: 683 684 >>> x = np.array([3, 4, 2, 1]) 685 >>> x[np.argpartition(x, 3)] 686 array([2, 1, 3, 4]) 687 >>> x[np.argpartition(x, (1, 3))] 688 array([1, 2, 3, 4]) 689 690 >>> x = [3, 4, 2, 1] 691 >>> np.array(x)[np.argpartition(x, 3)] 692 array([2, 1, 3, 4]) 693 694 Multi-dimensional array: 695 696 >>> x = np.array([[3, 4, 2], [1, 3, 1]]) 697 >>> index_array = np.argpartition(x, kth=1, axis=-1) 698 >>> np.take_along_axis(x, index_array, axis=-1) # same as np.partition(x, kth=1) 699 array([[2, 3, 4], 700 [1, 1, 3]]) 701 702 r r� rg r� rF rF rG r s Or c C rh r9 rF �r` rS r� rk rF rF rG �_sort_dispatcherj rm r� c C s> |du r t | ��� } d}nt | �jdd�} | j|||d� | S )a� 703 Return a sorted copy of an array. 704 705 Parameters 706 ---------- 707 a : array_like 708 Array to be sorted. 709 axis : int or None, optional 710 Axis along which to sort. If None, the array is flattened before 711 sorting. The default is -1, which sorts along the last axis. 712 kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, optional 713 Sorting algorithm. The default is 'quicksort'. Note that both 'stable' 714 and 'mergesort' use timsort or radix sort under the covers and, in general, 715 the actual implementation will vary with data type. The 'mergesort' option 716 is retained for backwards compatibility. 717 718 .. versionchanged:: 1.15.0. 719 The 'stable' option was added. 720 721 order : str or list of str, optional 722 When `a` is an array with fields defined, this argument specifies 723 which fields to compare first, second, etc. A single field can 724 be specified as a string, and not all fields need be specified, 725 but unspecified fields will still be used, in the order in which 726 they come up in the dtype, to break ties. 727 728 Returns 729 ------- 730 sorted_array : ndarray 731 Array of the same type and shape as `a`. 732 733 See Also 734 -------- 735 ndarray.sort : Method to sort an array in-place. 736 argsort : Indirect sort. 737 lexsort : Indirect stable sort on multiple keys. 738 searchsorted : Find elements in a sorted array. 739 partition : Partial sort. 740 741 Notes 742 ----- 743 The various sorting algorithms are characterized by their average speed, 744 worst case performance, work space size, and whether they are stable. A 745 stable sort keeps items with the same key in the same relative 746 order. The four algorithms implemented in NumPy have the following 747 properties: 748 749 =========== ======= ============= ============ ======== 750 kind speed worst case work space stable 751 =========== ======= ============= ============ ======== 752 'quicksort' 1 O(n^2) 0 no 753 'heapsort' 3 O(n*log(n)) 0 no 754 'mergesort' 2 O(n*log(n)) ~n/2 yes 755 'timsort' 2 O(n*log(n)) ~n/2 yes 756 =========== ======= ============= ============ ======== 757 758 .. note:: The datatype determines which of 'mergesort' or 'timsort' 759 is actually used, even if 'mergesort' is specified. User selection 760 at a finer scale is not currently available. 761 762 All the sort algorithms make temporary copies of the data when 763 sorting along any but the last axis. Consequently, sorting along 764 the last axis is faster and uses less space than sorting along 765 any other axis. 766 767 The sort order for complex numbers is lexicographic. If both the real 768 and imaginary parts are non-nan then the order is determined by the 769 real parts except when they are equal, in which case the order is 770 determined by the imaginary parts. 771 772 Previous to numpy 1.4.0 sorting real and complex arrays containing nan 773 values led to undefined behaviour. In numpy versions >= 1.4.0 nan 774 values are sorted to the end. The extended sort order is: 775 776 * Real: [R, nan] 777 * Complex: [R + Rj, R + nanj, nan + Rj, nan + nanj] 778 779 where R is a non-nan real value. Complex values with the same nan 780 placements are sorted according to the non-nan part if it exists. 781 Non-nan values are sorted as before. 782 783 .. versionadded:: 1.12.0 784 785 quicksort has been changed to `introsort <https://en.wikipedia.org/wiki/Introsort>`_. 786 When sorting does not make enough progress it switches to 787 `heapsort <https://en.wikipedia.org/wiki/Heapsort>`_. 788 This implementation makes quicksort O(n*log(n)) in the worst case. 789 790 'stable' automatically chooses the best stable sorting algorithm 791 for the data type being sorted. 792 It, along with 'mergesort' is currently mapped to 793 `timsort <https://en.wikipedia.org/wiki/Timsort>`_ 794 or `radix sort <https://en.wikipedia.org/wiki/Radix_sort>`_ 795 depending on the data type. 796 API forward compatibility currently limits the 797 ability to select the implementation and it is hardwired for the different 798 data types. 799 800 .. versionadded:: 1.17.0 801 802 Timsort is added for better performance on already or nearly 803 sorted data. On random data timsort is almost identical to 804 mergesort. It is now used for stable sort while quicksort is still the 805 default sort if none is chosen. For timsort details, refer to 806 `CPython listsort.txt <https://github.com/python/cpython/blob/3.7/Objects/listsort.txt>`_. 807 'mergesort' and 'stable' are mapped to radix sort for integer data types. Radix sort is an 808 O(n) sort instead of O(n log n). 809 810 .. versionchanged:: 1.18.0 811 812 NaT now sorts to the end of arrays for consistency with NaN. 813 814 Examples 815 -------- 816 >>> a = np.array([[1,4],[3,1]]) 817 >>> np.sort(a) # sort along the last axis 818 array([[1, 4], 819 [1, 3]]) 820 >>> np.sort(a, axis=None) # sort the flattened array 821 array([1, 1, 3, 4]) 822 >>> np.sort(a, axis=0) # sort along the first axis 823 array([[1, 1], 824 [3, 4]]) 825 826 Use the `order` keyword to specify a field to use when sorting a 827 structured array: 828 829 >>> dtype = [('name', 'S10'), ('height', float), ('age', int)] 830 >>> values = [('Arthur', 1.8, 41), ('Lancelot', 1.9, 38), 831 ... ('Galahad', 1.7, 38)] 832 >>> a = np.array(values, dtype=dtype) # create a structured array 833 >>> np.sort(a, order='height') # doctest: +SKIP 834 array([('Galahad', 1.7, 38), ('Arthur', 1.8, 41), 835 ('Lancelot', 1.8999999999999999, 38)], 836 dtype=[('name', '|S10'), ('height', '<f8'), ('age', '<i4')]) 837 838 Sort by age, then height if ages are equal: 839 840 >>> np.sort(a, order=['age', 'height']) # doctest: +SKIP 841 array([('Galahad', 1.7, 38), ('Lancelot', 1.8999999999999999, 38), 842 ('Arthur', 1.8, 41)], 843 dtype=[('name', '|S10'), ('height', '<f8'), ('age', '<i4')]) 844 845 Nr� r� rp r� )r r� r� r. r� rF rF rG r. n s r. c C rh r9 rF r� rF rF rG �_argsort_dispatcher 846 rm r� c C rt )a� 847 Returns the indices that would sort an array. 848 849 Perform an indirect sort along the given axis using the algorithm specified 850 by the `kind` keyword. It returns an array of indices of the same shape as 851 `a` that index data along the given axis in sorted order. 852 853 Parameters 854 ---------- 855 a : array_like 856 Array to sort. 857 axis : int or None, optional 858 Axis along which to sort. The default is -1 (the last axis). If None, 859 the flattened array is used. 860 kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, optional 861 Sorting algorithm. The default is 'quicksort'. Note that both 'stable' 862 and 'mergesort' use timsort under the covers and, in general, the 863 actual implementation will vary with data type. The 'mergesort' option 864 is retained for backwards compatibility. 865 866 .. versionchanged:: 1.15.0. 867 The 'stable' option was added. 868 order : str or list of str, optional 869 When `a` is an array with fields defined, this argument specifies 870 which fields to compare first, second, etc. A single field can 871 be specified as a string, and not all fields need be specified, 872 but unspecified fields will still be used, in the order in which 873 they come up in the dtype, to break ties. 874 875 Returns 876 ------- 877 index_array : ndarray, int 878 Array of indices that sort `a` along the specified `axis`. 879 If `a` is one-dimensional, ``a[index_array]`` yields a sorted `a`. 880 More generally, ``np.take_along_axis(a, index_array, axis=axis)`` 881 always yields the sorted `a`, irrespective of dimensionality. 882 883 See Also 884 -------- 885 sort : Describes sorting algorithms used. 886 lexsort : Indirect stable sort with multiple keys. 887 ndarray.sort : Inplace sort. 888 argpartition : Indirect partial sort. 889 take_along_axis : Apply ``index_array`` from argsort 890 to an array as if by calling sort. 891 892 Notes 893 ----- 894 See `sort` for notes on the different sorting algorithms. 895 896 As of NumPy 1.4.0 `argsort` works with real/complex arrays containing 897 nan values. The enhanced sort order is documented in `sort`. 898 899 Examples 900 -------- 901 One dimensional array: 902 903 >>> x = np.array([3, 1, 2]) 904 >>> np.argsort(x) 905 array([1, 2, 0]) 906 907 Two-dimensional array: 908 909 >>> x = np.array([[0, 3], [2, 2]]) 910 >>> x 911 array([[0, 3], 912 [2, 2]]) 913 914 >>> ind = np.argsort(x, axis=0) # sorts along first axis (down) 915 >>> ind 916 array([[0, 1], 917 [1, 0]]) 918 >>> np.take_along_axis(x, ind, axis=0) # same as np.sort(x, axis=0) 919 array([[0, 2], 920 [2, 3]]) 921 922 >>> ind = np.argsort(x, axis=1) # sorts along last axis (across) 923 >>> ind 924 array([[0, 1], 925 [0, 1]]) 926 >>> np.take_along_axis(x, ind, axis=1) # same as np.sort(x, axis=1) 927 array([[0, 3], 928 [2, 2]]) 929 930 Indices of the sorted elements of a N-dimensional array: 931 932 >>> ind = np.unravel_index(np.argsort(x, axis=None), x.shape) 933 >>> ind 934 (array([0, 1, 1, 0]), array([0, 0, 1, 1])) 935 >>> x[ind] # same as np.sort(x, axis=None) 936 array([0, 2, 2, 3]) 937 938 Sorting with keys: 939 940 >>> x = np.array([(1, 0), (0, 1)], dtype=[('x', '<i4'), ('y', '<i4')]) 941 >>> x 942 array([(1, 0), (0, 1)], 943 dtype=[('x', '<i4'), ('y', '<i4')]) 944 945 >>> np.argsort(x, order=('x','y')) 946 array([1, 0]) 947 948 >>> np.argsort(x, order=('y','x')) 949 array([0, 1]) 950 951 r r� rg r� rF rF rG r s lr )�keepdimsc C � | |fS r9 rF �r` rS rU r� rF rF rG �_argmax_dispatcher} rd r� c C �. |t jur d|ini }t| df||d�|��S )a 952 953 Returns the indices of the maximum values along an axis. 954 955 Parameters 956 ---------- 957 a : array_like 958 Input array. 959 axis : int, optional 960 By default, the index is into the flattened array, otherwise 961 along the specified axis. 962 out : array, optional 963 If provided, the result will be inserted into this array. It should 964 be of the appropriate shape and dtype. 965 keepdims : bool, optional 966 If this is set to True, the axes which are reduced are left 967 in the result as dimensions with size one. With this option, 968 the result will broadcast correctly against the array. 969 970 .. versionadded:: 1.22.0 971 972 Returns 973 ------- 974 index_array : ndarray of ints 975 Array of indices into the array. It has the same shape as `a.shape` 976 with the dimension along `axis` removed. If `keepdims` is set to True, 977 then the size of `axis` will be 1 with the resulting array having same 978 shape as `a.shape`. 979 980 See Also 981 -------- 982 ndarray.argmax, argmin 983 amax : The maximum value along a given axis. 984 unravel_index : Convert a flat index into an index tuple. 985 take_along_axis : Apply ``np.expand_dims(index_array, axis)`` 986 from argmax to an array as if by calling max. 987 988 Notes 989 ----- 990 In case of multiple occurrences of the maximum values, the indices 991 corresponding to the first occurrence are returned. 992 993 Examples 994 -------- 995 >>> a = np.arange(6).reshape(2,3) + 10 996 >>> a 997 array([[10, 11, 12], 998 [13, 14, 15]]) 999 >>> np.argmax(a) 1000 5 1001 >>> np.argmax(a, axis=0) 1002 array([1, 1, 1]) 1003 >>> np.argmax(a, axis=1) 1004 array([2, 2]) 1005 1006 Indexes of the maximal elements of a N-dimensional array: 1007 1008 >>> ind = np.unravel_index(np.argmax(a, axis=None), a.shape) 1009 >>> ind 1010 (1, 2) 1011 >>> a[ind] 1012 15 1013 1014 >>> b = np.arange(6) 1015 >>> b[1] = 5 1016 >>> b 1017 array([0, 5, 2, 3, 4, 5]) 1018 >>> np.argmax(b) # Only the first occurrence is returned. 1019 1 1020 1021 >>> x = np.array([[4,2,3], [1,0,3]]) 1022 >>> index_array = np.argmax(x, axis=-1) 1023 >>> # Same as np.amax(x, axis=-1, keepdims=True) 1024 >>> np.take_along_axis(x, np.expand_dims(index_array, axis=-1), axis=-1) 1025 array([[4], 1026 [3]]) 1027 >>> # Same as np.amax(x, axis=-1) 1028 >>> np.take_along_axis(x, np.expand_dims(index_array, axis=-1), axis=-1).squeeze(axis=-1) 1029 array([4, 3]) 1030 1031 Setting `keepdims` to `True`, 1032 1033 >>> x = np.arange(24).reshape((2, 3, 4)) 1034 >>> res = np.argmax(x, axis=1, keepdims=True) 1035 >>> res.shape 1036 (2, 1, 4) 1037 r� r rV �rL rM rK �r` rS rU r� rC rF rF rG r � � Xr c C r� r9 rF r� rF rF rG �_argmin_dispatcher� rd r� c C r� )a) 1038 1039 Returns the indices of the minimum values along an axis. 1040 1041 Parameters 1042 ---------- 1043 a : array_like 1044 Input array. 1045 axis : int, optional 1046 By default, the index is into the flattened array, otherwise 1047 along the specified axis. 1048 out : array, optional 1049 If provided, the result will be inserted into this array. It should 1050 be of the appropriate shape and dtype. 1051 keepdims : bool, optional 1052 If this is set to True, the axes which are reduced are left 1053 in the result as dimensions with size one. With this option, 1054 the result will broadcast correctly against the array. 1055 1056 .. versionadded:: 1.22.0 1057 1058 Returns 1059 ------- 1060 index_array : ndarray of ints 1061 Array of indices into the array. It has the same shape as `a.shape` 1062 with the dimension along `axis` removed. If `keepdims` is set to True, 1063 then the size of `axis` will be 1 with the resulting array having same 1064 shape as `a.shape`. 1065 1066 See Also 1067 -------- 1068 ndarray.argmin, argmax 1069 amin : The minimum value along a given axis. 1070 unravel_index : Convert a flat index into an index tuple. 1071 take_along_axis : Apply ``np.expand_dims(index_array, axis)`` 1072 from argmin to an array as if by calling min. 1073 1074 Notes 1075 ----- 1076 In case of multiple occurrences of the minimum values, the indices 1077 corresponding to the first occurrence are returned. 1078 1079 Examples 1080 -------- 1081 >>> a = np.arange(6).reshape(2,3) + 10 1082 >>> a 1083 array([[10, 11, 12], 1084 [13, 14, 15]]) 1085 >>> np.argmin(a) 1086 0 1087 >>> np.argmin(a, axis=0) 1088 array([0, 0, 0]) 1089 >>> np.argmin(a, axis=1) 1090 array([0, 0]) 1091 1092 Indices of the minimum elements of a N-dimensional array: 1093 1094 >>> ind = np.unravel_index(np.argmin(a, axis=None), a.shape) 1095 >>> ind 1096 (0, 0) 1097 >>> a[ind] 1098 10 1099 1100 >>> b = np.arange(6) + 10 1101 >>> b[4] = 10 1102 >>> b 1103 array([10, 11, 12, 13, 10, 15]) 1104 >>> np.argmin(b) # Only the first occurrence is returned. 1105 0 1106 1107 >>> x = np.array([[4,2,3], [1,0,3]]) 1108 >>> index_array = np.argmin(x, axis=-1) 1109 >>> # Same as np.amin(x, axis=-1, keepdims=True) 1110 >>> np.take_along_axis(x, np.expand_dims(index_array, axis=-1), axis=-1) 1111 array([[2], 1112 [0]]) 1113 >>> # Same as np.amax(x, axis=-1) 1114 >>> np.take_along_axis(x, np.expand_dims(index_array, axis=-1), axis=-1).squeeze(axis=-1) 1115 array([2, 0]) 1116 1117 Setting `keepdims` to `True`, 1118 1119 >>> x = np.arange(24).reshape((2, 3, 4)) 1120 >>> res = np.argmin(x, axis=1, keepdims=True) 1121 >>> res.shape 1122 (2, 1, 4) 1123 r� r rV r� r� rF rF rG r � r� r c C � 1124 | ||fS r9 rF �r` rP �side�sorterrF rF rG �_searchsorted_dispatcher= r| r� �leftc C rt )a� 1125 Find indices where elements should be inserted to maintain order. 1126 1127 Find the indices into a sorted array `a` such that, if the 1128 corresponding elements in `v` were inserted before the indices, the 1129 order of `a` would be preserved. 1130 1131 Assuming that `a` is sorted: 1132 1133 ====== ============================ 1134 `side` returned index `i` satisfies 1135 ====== ============================ 1136 left ``a[i-1] < v <= a[i]`` 1137 right ``a[i-1] <= v < a[i]`` 1138 ====== ============================ 1139 1140 Parameters 1141 ---------- 1142 a : 1-D array_like 1143 Input array. If `sorter` is None, then it must be sorted in 1144 ascending order, otherwise `sorter` must be an array of indices 1145 that sort it. 1146 v : array_like 1147 Values to insert into `a`. 1148 side : {'left', 'right'}, optional 1149 If 'left', the index of the first suitable location found is given. 1150 If 'right', return the last such index. If there is no suitable 1151 index, return either 0 or N (where N is the length of `a`). 1152 sorter : 1-D array_like, optional 1153 Optional array of integer indices that sort array a into ascending 1154 order. They are typically the result of argsort. 1155 1156 .. versionadded:: 1.7.0 1157 1158 Returns 1159 ------- 1160 indices : int or array of ints 1161 Array of insertion points with the same shape as `v`, 1162 or an integer if `v` is a scalar. 1163 1164 See Also 1165 -------- 1166 sort : Return a sorted copy of an array. 1167 histogram : Produce histogram from 1-D data. 1168 1169 Notes 1170 ----- 1171 Binary search is used to find the required insertion points. 1172 1173 As of NumPy 1.4.0 `searchsorted` works with real/complex arrays containing 1174 `nan` values. The enhanced sort order is documented in `sort`. 1175 1176 This function uses the same algorithm as the builtin python `bisect.bisect_left` 1177 (``side='left'``) and `bisect.bisect_right` (``side='right'``) functions, 1178 which is also vectorized in the `v` argument. 1179 1180 Examples 1181 -------- 1182 >>> np.searchsorted([1,2,3,4,5], 3) 1183 2 1184 >>> np.searchsorted([1,2,3,4,5], 3, side='right') 1185 3 1186 >>> np.searchsorted([1,2,3,4,5], [-10, 10, 2, 3]) 1187 array([0, 5, 1, 2]) 1188 1189 r* )r� r� rg r� rF rF rG r* A s Dr* c C rh r9 rF )r` � new_shaperF rF rG �_resize_dispatcher� rm r� c C s� t |ttjf�r |f}t| �} d}|D ]}||9 }|dk r!td��q| jdks+|dkr2tj| |d�S | | j }t | f| �d|� } t 1190 | |�S )as 1191 Return a new array with the specified shape. 1192 1193 If the new array is larger than the original array, then the new 1194 array is filled with repeated copies of `a`. Note that this behavior 1195 is different from a.resize(new_shape) which fills with zeros instead 1196 of repeated copies of `a`. 1197 1198 Parameters 1199 ---------- 1200 a : array_like 1201 Array to be resized. 1202 1203 new_shape : int or tuple of int 1204 Shape of resized array. 1205 1206 Returns 1207 ------- 1208 reshaped_array : ndarray 1209 The new array is formed from the data in the old array, repeated 1210 if necessary to fill out the required number of elements. The 1211 data are repeated iterating over the array in C-order. 1212 1213 See Also 1214 -------- 1215 numpy.reshape : Reshape an array without changing the total size. 1216 numpy.pad : Enlarge and pad an array. 1217 numpy.repeat : Repeat elements of an array. 1218 ndarray.resize : resize an array in-place. 1219 1220 Notes 1221 ----- 1222 When the total size of the array does not change `~numpy.reshape` should 1223 be used. In most other cases either indexing (to reduce the size) 1224 or padding (to increase the size) may be a more appropriate solution. 1225 1226 Warning: This functionality does **not** consider axes separately, 1227 i.e. it does not apply interpolation/extrapolation. 1228 It fills the return array with the required number of elements, iterating 1229 over `a` in C-order, disregarding axes (and cycling back from the start if 1230 the new shape is larger). This functionality is therefore not suitable to 1231 resize images, or data where each axis represents a separate and distinct 1232 entity. 1233 1234 Examples 1235 -------- 1236 >>> a=np.array([[0,1],[2,3]]) 1237 >>> np.resize(a,(2,3)) 1238 array([[0, 1, 2], 1239 [3, 0, 1]]) 1240 >>> np.resize(a,(1,4)) 1241 array([[0, 1, 2, 3]]) 1242 >>> np.resize(a,(2,4)) 1243 array([[0, 1, 2, 3], 1244 [0, 1, 2, 3]]) 1245 1246 r r z0all elements of `new_shape` must be non-negative)r+ N) r= �int�nt�integerr% � 1247 ValueErrorr, rL � 1248 zeros_liker 1249 r' )r` r� �new_sizeZ 1250 dim_lengthrv rF rF rG r( � s ;� 1251 r( c C rh r9 rF �r` rS rF rF rG �_squeeze_dispatcher� rm r� c C sD z| j }W n ty t| d|d� Y S w |du r |� S ||d�S )a� 1252 Remove axes of length one from `a`. 1253 1254 Parameters 1255 ---------- 1256 a : array_like 1257 Input data. 1258 axis : None or int or tuple of ints, optional 1259 .. versionadded:: 1.7.0 1260 1261 Selects a subset of the entries of length one in the 1262 shape. If an axis is selected with shape entry greater than 1263 one, an error is raised. 1264 1265 Returns 1266 ------- 1267 squeezed : ndarray 1268 The input array, but with all or a subset of the 1269 dimensions of length 1 removed. This is always `a` itself 1270 or a view into `a`. Note that if all axes are squeezed, 1271 the result is a 0d array and not a scalar. 1272 1273 Raises 1274 ------ 1275 ValueError 1276 If `axis` is not None, and an axis being squeezed is not of length 1 1277 1278 See Also 1279 -------- 1280 expand_dims : The inverse operation, adding entries of length one 1281 reshape : Insert, remove, and combine dimensions, and resize existing ones 1282 1283 Examples 1284 -------- 1285 >>> x = np.array([[[0], [1], [2]]]) 1286 >>> x.shape 1287 (1, 3, 1) 1288 >>> np.squeeze(x).shape 1289 (3,) 1290 >>> np.squeeze(x, axis=0).shape 1291 (3, 1) 1292 >>> np.squeeze(x, axis=1).shape 1293 Traceback (most recent call last): 1294 ... 1295 ValueError: cannot select an axis to squeeze out which has size not equal to one 1296 >>> np.squeeze(x, axis=2).shape 1297 (1, 3) 1298 >>> x = np.array([[1234]]) 1299 >>> x.shape 1300 (1, 1) 1301 >>> np.squeeze(x) 1302 array(1234) # 0d array 1303 >>> np.squeeze(x).shape 1304 () 1305 >>> np.squeeze(x)[()] 1306 1234 1307 1308 r/ rx N)r/ r; rH )r` rS r/ rF rF rG r/ � s < 1309 � 1310 r/ c C rh r9 rF �r` �offsetr� r� rF rF rG �_diagonal_dispatcher& rm r� c C s4 t | tj�rt| �j|||d�S t| �j|||d�S )a� 1311 Return specified diagonals. 1312 1313 If `a` is 2-D, returns the diagonal of `a` with the given offset, 1314 i.e., the collection of elements of the form ``a[i, i+offset]``. If 1315 `a` has more than two dimensions, then the axes specified by `axis1` 1316 and `axis2` are used to determine the 2-D sub-array whose diagonal is 1317 returned. The shape of the resulting array can be determined by 1318 removing `axis1` and `axis2` and appending an index to the right equal 1319 to the size of the resulting diagonals. 1320 1321 In versions of NumPy prior to 1.7, this function always returned a new, 1322 independent array containing a copy of the values in the diagonal. 1323 1324 In NumPy 1.7 and 1.8, it continues to return a copy of the diagonal, 1325 but depending on this fact is deprecated. Writing to the resulting 1326 array continues to work as it used to, but a FutureWarning is issued. 1327 1328 Starting in NumPy 1.9 it returns a read-only view on the original array. 1329 Attempting to write to the resulting array will produce an error. 1330 1331 In some future release, it will return a read/write view and writing to 1332 the returned array will alter your original array. The returned array 1333 will have the same type as the input array. 1334 1335 If you don't write to the array returned by this function, then you can 1336 just ignore all of the above. 1337 1338 If you depend on the current behavior, then we suggest copying the 1339 returned array explicitly, i.e., use ``np.diagonal(a).copy()`` instead 1340 of just ``np.diagonal(a)``. This will work with both past and future 1341 versions of NumPy. 1342 1343 Parameters 1344 ---------- 1345 a : array_like 1346 Array from which the diagonals are taken. 1347 offset : int, optional 1348 Offset of the diagonal from the main diagonal. Can be positive or 1349 negative. Defaults to main diagonal (0). 1350 axis1 : int, optional 1351 Axis to be used as the first axis of the 2-D sub-arrays from which 1352 the diagonals should be taken. Defaults to first axis (0). 1353 axis2 : int, optional 1354 Axis to be used as the second axis of the 2-D sub-arrays from 1355 which the diagonals should be taken. Defaults to second axis (1). 1356 1357 Returns 1358 ------- 1359 array_of_diagonals : ndarray 1360 If `a` is 2-D, then a 1-D array containing the diagonal and of the 1361 same type as `a` is returned unless `a` is a `matrix`, in which case 1362 a 1-D array rather than a (2-D) `matrix` is returned in order to 1363 maintain backward compatibility. 1364 1365 If ``a.ndim > 2``, then the dimensions specified by `axis1` and `axis2` 1366 are removed, and a new axis inserted at the end corresponding to the 1367 diagonal. 1368 1369 Raises 1370 ------ 1371 ValueError 1372 If the dimension of `a` is less than 2. 1373 1374 See Also 1375 -------- 1376 diag : MATLAB work-a-like for 1-D and 2-D arrays. 1377 diagflat : Create diagonal arrays. 1378 trace : Sum along diagonals. 1379 1380 Examples 1381 -------- 1382 >>> a = np.arange(4).reshape(2,2) 1383 >>> a 1384 array([[0, 1], 1385 [2, 3]]) 1386 >>> a.diagonal() 1387 array([0, 3]) 1388 >>> a.diagonal(1) 1389 array([1]) 1390 1391 A 3-D example: 1392 1393 >>> a = np.arange(8).reshape(2,2,2); a 1394 array([[[0, 1], 1395 [2, 3]], 1396 [[4, 5], 1397 [6, 7]]]) 1398 >>> a.diagonal(0, # Main diagonals of two arrays created by skipping 1399 ... 0, # across the outer(left)-most axis last and 1400 ... 1) # the "middle" (row) axis first. 1401 array([[0, 6], 1402 [1, 7]]) 1403 1404 The sub-arrays whose main diagonals we just obtained; note that each 1405 corresponds to fixing the right-most (column) axis, and that the 1406 diagonals are "packed" in rows. 1407 1408 >>> a[:,:,0] # main diagonal is [0 6] 1409 array([[0, 2], 1410 [4, 6]]) 1411 >>> a[:,:,1] # main diagonal is [1 7] 1412 array([[1, 3], 1413 [5, 7]]) 1414 1415 The anti-diagonal can be obtained by reversing the order of elements 1416 using either `numpy.flipud` or `numpy.fliplr`. 1417 1418 >>> a = np.arange(9).reshape(3, 3) 1419 >>> a 1420 array([[0, 1, 2], 1421 [3, 4, 5], 1422 [6, 7, 8]]) 1423 >>> np.fliplr(a).diagonal() # Horizontal flip 1424 array([2, 4, 6]) 1425 >>> np.flipud(a).diagonal() # Vertical flip 1426 array([6, 4, 2]) 1427 1428 Note that the order in which the diagonal is retrieved varies depending 1429 on the flip function. 1430 )r� r� r� )r= rL �matrixr r r r� rF rF rG r * s {r c C s | |fS r9 rF �r` r� r� r� rT rU rF rF rG �_trace_dispatcher� � r� c C s< t | tj�rt| �j|||||d�S t| �j|||||d�S )a� 1431 Return the sum along diagonals of the array. 1432 1433 If `a` is 2-D, the sum along its diagonal with the given offset 1434 is returned, i.e., the sum of elements ``a[i,i+offset]`` for all i. 1435 1436 If `a` has more than two dimensions, then the axes specified by axis1 and 1437 axis2 are used to determine the 2-D sub-arrays whose traces are returned. 1438 The shape of the resulting array is the same as that of `a` with `axis1` 1439 and `axis2` removed. 1440 1441 Parameters 1442 ---------- 1443 a : array_like 1444 Input array, from which the diagonals are taken. 1445 offset : int, optional 1446 Offset of the diagonal from the main diagonal. Can be both positive 1447 and negative. Defaults to 0. 1448 axis1, axis2 : int, optional 1449 Axes to be used as the first and second axis of the 2-D sub-arrays 1450 from which the diagonals should be taken. Defaults are the first two 1451 axes of `a`. 1452 dtype : dtype, optional 1453 Determines the data-type of the returned array and of the accumulator 1454 where the elements are summed. If dtype has the value None and `a` is 1455 of integer type of precision less than the default integer 1456 precision, then the default integer precision is used. Otherwise, 1457 the precision is the same as that of `a`. 1458 out : ndarray, optional 1459 Array into which the output is placed. Its type is preserved and 1460 it must be of the right shape to hold the output. 1461 1462 Returns 1463 ------- 1464 sum_along_diagonals : ndarray 1465 If `a` is 2-D, the sum along the diagonal is returned. If `a` has 1466 larger dimensions, then an array of sums along diagonals is returned. 1467 1468 See Also 1469 -------- 1470 diag, diagonal, diagflat 1471 1472 Examples 1473 -------- 1474 >>> np.trace(np.eye(3)) 1475 3.0 1476 >>> a = np.arange(8).reshape((2,2,2)) 1477 >>> np.trace(a) 1478 array([6, 8]) 1479 1480 >>> a = np.arange(24).reshape((2,2,2,3)) 1481 >>> np.trace(a).shape 1482 (2, 3) 1483 1484 )r� r� r� rT rU )r= rL r� r r4 r r� rF rF rG r4 � s 9r4 c C rh r9 rF �r` rk rF rF rG �_ravel_dispatcher� rm r� c C s, t | tj�rt| �j|d�S t| �j|d�S )a� Return a contiguous flattened array. 1485 1486 A 1-D array, containing the elements of the input, is returned. A copy is 1487 made only if needed. 1488 1489 As of NumPy 1.10, the returned array will have the same type as the input 1490 array. (for example, a masked array will be returned for a masked array 1491 input) 1492 1493 Parameters 1494 ---------- 1495 a : array_like 1496 Input array. The elements in `a` are read in the order specified by 1497 `order`, and packed as a 1-D array. 1498 order : {'C','F', 'A', 'K'}, optional 1499 1500 The elements of `a` are read using this index order. 'C' means 1501 to index the elements in row-major, C-style order, 1502 with the last axis index changing fastest, back to the first 1503 axis index changing slowest. 'F' means to index the elements 1504 in column-major, Fortran-style order, with the 1505 first index changing fastest, and the last index changing 1506 slowest. Note that the 'C' and 'F' options take no account of 1507 the memory layout of the underlying array, and only refer to 1508 the order of axis indexing. 'A' means to read the elements in 1509 Fortran-like index order if `a` is Fortran *contiguous* in 1510 memory, C-like order otherwise. 'K' means to read the 1511 elements in the order they occur in memory, except for 1512 reversing the data when strides are negative. By default, 'C' 1513 index order is used. 1514 1515 Returns 1516 ------- 1517 y : array_like 1518 y is an array of the same subtype as `a`, with shape ``(a.size,)``. 1519 Note that matrices are special cased for backward compatibility, if `a` 1520 is a matrix, then y is a 1-D ndarray. 1521 1522 See Also 1523 -------- 1524 ndarray.flat : 1-D iterator over an array. 1525 ndarray.flatten : 1-D array copy of the elements of an array 1526 in row-major order. 1527 ndarray.reshape : Change the shape of an array without changing its data. 1528 1529 Notes 1530 ----- 1531 In row-major, C-style order, in two dimensions, the row index 1532 varies the slowest, and the column index the quickest. This can 1533 be generalized to multiple dimensions, where row-major order 1534 implies that the index along the first axis varies slowest, and 1535 the index along the last quickest. The opposite holds for 1536 column-major, Fortran-style index ordering. 1537 1538 When a view is desired in as many cases as possible, ``arr.reshape(-1)`` 1539 may be preferable. 1540 1541 Examples 1542 -------- 1543 It is equivalent to ``reshape(-1, order=order)``. 1544 1545 >>> x = np.array([[1, 2, 3], [4, 5, 6]]) 1546 >>> np.ravel(x) 1547 array([1, 2, 3, 4, 5, 6]) 1548 1549 >>> x.reshape(-1) 1550 array([1, 2, 3, 4, 5, 6]) 1551 1552 >>> np.ravel(x, order='F') 1553 array([1, 4, 2, 5, 3, 6]) 1554 1555 When ``order`` is 'A', it will preserve the array's 'C' or 'F' ordering: 1556 1557 >>> np.ravel(x.T) 1558 array([1, 4, 2, 5, 3, 6]) 1559 >>> np.ravel(x.T, order='A') 1560 array([1, 2, 3, 4, 5, 6]) 1561 1562 When ``order`` is 'K', it will preserve orderings that are neither 'C' 1563 nor 'F', but won't reverse axes: 1564 1565 >>> a = np.arange(3)[::-1]; a 1566 array([2, 1, 0]) 1567 >>> a.ravel(order='C') 1568 array([2, 1, 0]) 1569 >>> a.ravel(order='K') 1570 array([2, 1, 0]) 1571 1572 >>> a = np.arange(12).reshape(2,3,2).swapaxes(1,2); a 1573 array([[[ 0, 2, 4], 1574 [ 1, 3, 5]], 1575 [[ 6, 8, 10], 1576 [ 7, 9, 11]]]) 1577 >>> a.ravel(order='C') 1578 array([ 0, 2, 4, 1, 3, 5, 6, 8, 10, 7, 9, 11]) 1579 >>> a.ravel(order='K') 1580 array([ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]) 1581 1582 rp )r= rL r� r r% r r� rF rF rG r% � s er% c C rh r9 rF �r` rF rF rG �_nonzero_dispatcher` rm r� c C s 1583 t | d�S )a( 1584 1585 Return the indices of the elements that are non-zero. 1586 1587 Returns a tuple of arrays, one for each dimension of `a`, 1588 containing the indices of the non-zero elements in that 1589 dimension. The values in `a` are always tested and returned in 1590 row-major, C-style order. 1591 1592 To group the indices by element, rather than dimension, use `argwhere`, 1593 which returns a row for each non-zero element. 1594 1595 .. note:: 1596 1597 When called on a zero-d array or scalar, ``nonzero(a)`` is treated 1598 as ``nonzero(atleast_1d(a))``. 1599 1600 .. deprecated:: 1.17.0 1601 1602 Use `atleast_1d` explicitly if this behavior is deliberate. 1603 1604 Parameters 1605 ---------- 1606 a : array_like 1607 Input array. 1608 1609 Returns 1610 ------- 1611 tuple_of_arrays : tuple 1612 Indices of elements that are non-zero. 1613 1614 See Also 1615 -------- 1616 flatnonzero : 1617 Return indices that are non-zero in the flattened version of the input 1618 array. 1619 ndarray.nonzero : 1620 Equivalent ndarray method. 1621 count_nonzero : 1622 Counts the number of non-zero elements in the input array. 1623 1624 Notes 1625 ----- 1626 While the nonzero values can be obtained with ``a[nonzero(a)]``, it is 1627 recommended to use ``x[x.astype(bool)]`` or ``x[x != 0]`` instead, which 1628 will correctly handle 0-d arrays. 1629 1630 Examples 1631 -------- 1632 >>> x = np.array([[3, 0, 0], [0, 4, 0], [5, 6, 0]]) 1633 >>> x 1634 array([[3, 0, 0], 1635 [0, 4, 0], 1636 [5, 6, 0]]) 1637 >>> np.nonzero(x) 1638 (array([0, 1, 2, 2]), array([0, 1, 0, 1])) 1639 1640 >>> x[np.nonzero(x)] 1641 array([3, 4, 5, 6]) 1642 >>> np.transpose(np.nonzero(x)) 1643 array([[0, 0], 1644 [1, 1], 1645 [2, 0], 1646 [2, 1]]) 1647 1648 A common use for ``nonzero`` is to find the indices of an array, where 1649 a condition is True. Given an array `a`, the condition `a` > 3 is a 1650 boolean array and since False is interpreted as 0, np.nonzero(a > 3) 1651 yields the indices of the `a` where the condition is true. 1652 1653 >>> a = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]]) 1654 >>> a > 3 1655 array([[False, False, False], 1656 [ True, True, True], 1657 [ True, True, True]]) 1658 >>> np.nonzero(a > 3) 1659 (array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2])) 1660 1661 Using this result to index `a` is equivalent to using the mask directly: 1662 1663 >>> a[np.nonzero(a > 3)] 1664 array([4, 5, 6, 7, 8, 9]) 1665 >>> a[a > 3] # prefer this spelling 1666 array([4, 5, 6, 7, 8, 9]) 1667 1668 ``nonzero`` can also be called as a method of the array. 1669 1670 >>> (a > 3).nonzero() 1671 (array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2])) 1672 1673 r rg r� rF rF rG r d s 1674 \r c C rh r9 rF r� rF rF rG �_shape_dispatcher� rm r� c C s, z| j }W |S ty t| �j }Y |S w )a� 1675 Return the shape of an array. 1676 1677 Parameters 1678 ---------- 1679 a : array_like 1680 Input array. 1681 1682 Returns 1683 ------- 1684 shape : tuple of ints 1685 The elements of the shape tuple give the lengths of the 1686 corresponding array dimensions. 1687 1688 See Also 1689 -------- 1690 len : ``len(a)`` is equivalent to ``np.shape(a)[0]`` for N-D arrays with 1691 ``N>=1``. 1692 ndarray.shape : Equivalent array method. 1693 1694 Examples 1695 -------- 1696 >>> np.shape(np.eye(3)) 1697 (3, 3) 1698 >>> np.shape([[1, 3]]) 1699 (1, 2) 1700 >>> np.shape([0]) 1701 (1,) 1702 >>> np.shape(0) 1703 () 1704 1705 >>> a = np.array([(1, 2), (3, 4), (5, 6)], 1706 ... dtype=[('x', 'i4'), ('y', 'i4')]) 1707 >>> np.shape(a) 1708 (3,) 1709 >>> a.shape 1710 (3,) 1711 1712 )r+ r; r )r` rE rF rF rG r+ � s ) � �r+ c C r� r9 rF �� conditionr` rS rU rF rF rG �_compress_dispatcher� r| r� c C s t |d| ||d�S )a� 1713 Return selected slices of an array along given axis. 1714 1715 When working along a given axis, a slice along that axis is returned in 1716 `output` for each index where `condition` evaluates to True. When 1717 working on a 1-D array, `compress` is equivalent to `extract`. 1718 1719 Parameters 1720 ---------- 1721 condition : 1-D array of bools 1722 Array that selects which entries to return. If len(condition) 1723 is less than the size of `a` along the given axis, then output is 1724 truncated to the length of the condition array. 1725 a : array_like 1726 Array from which to extract a part. 1727 axis : int, optional 1728 Axis along which to take slices. If None (default), work on the 1729 flattened array. 1730 out : ndarray, optional 1731 Output array. Its type is preserved and it must be of the right 1732 shape to hold the output. 1733 1734 Returns 1735 ------- 1736 compressed_array : ndarray 1737 A copy of `a` without the slices along axis for which `condition` 1738 is false. 1739 1740 See Also 1741 -------- 1742 take, choose, diag, diagonal, select 1743 ndarray.compress : Equivalent method in ndarray 1744 extract : Equivalent method when working on 1-D arrays 1745 :ref:`ufuncs-output-type` 1746 1747 Examples 1748 -------- 1749 >>> a = np.array([[1, 2], [3, 4], [5, 6]]) 1750 >>> a 1751 array([[1, 2], 1752 [3, 4], 1753 [5, 6]]) 1754 >>> np.compress([0, 1], a, axis=0) 1755 array([[3, 4]]) 1756 >>> np.compress([False, True, True], a, axis=0) 1757 array([[3, 4], 1758 [5, 6]]) 1759 >>> np.compress([False, True], a, axis=1) 1760 array([[2], 1761 [4], 1762 [6]]) 1763 1764 Working on the flattened array does not return slices along an axis but 1765 selects elements. 1766 1767 >>> np.compress([False, True], a) 1768 array([2]) 1769 1770 r rV rg r� rF rF rG r � � =r c K ry r9 rF �r` Za_minZa_maxrU r[ rF rF rG �_clip_dispatcher; r| r� c K s t | d||fd|i|��S )a 1771 Clip (limit) the values in an array. 1772 1773 Given an interval, values outside the interval are clipped to 1774 the interval edges. For example, if an interval of ``[0, 1]`` 1775 is specified, values smaller than 0 become 0, and values larger 1776 than 1 become 1. 1777 1778 Equivalent to but faster than ``np.minimum(a_max, np.maximum(a, a_min))``. 1779 1780 No check is performed to ensure ``a_min < a_max``. 1781 1782 Parameters 1783 ---------- 1784 a : array_like 1785 Array containing elements to clip. 1786 a_min, a_max : array_like or None 1787 Minimum and maximum value. If ``None``, clipping is not performed on 1788 the corresponding edge. Only one of `a_min` and `a_max` may be 1789 ``None``. Both are broadcast against `a`. 1790 out : ndarray, optional 1791 The results will be placed in this array. It may be the input 1792 array for in-place clipping. `out` must be of the right shape 1793 to hold the output. Its type is preserved. 1794 **kwargs 1795 For other keyword-only arguments, see the 1796 :ref:`ufunc docs <ufuncs.kwargs>`. 1797 1798 .. versionadded:: 1.17.0 1799 1800 Returns 1801 ------- 1802 clipped_array : ndarray 1803 An array with the elements of `a`, but where values 1804 < `a_min` are replaced with `a_min`, and those > `a_max` 1805 with `a_max`. 1806 1807 See Also 1808 -------- 1809 :ref:`ufuncs-output-type` 1810 1811 Notes 1812 ----- 1813 When `a_min` is greater than `a_max`, `clip` returns an 1814 array in which all values are equal to `a_max`, 1815 as shown in the second example. 1816 1817 Examples 1818 -------- 1819 >>> a = np.arange(10) 1820 >>> a 1821 array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) 1822 >>> np.clip(a, 1, 8) 1823 array([1, 1, 2, 3, 4, 5, 6, 7, 8, 8]) 1824 >>> np.clip(a, 8, 1) 1825 array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1]) 1826 >>> np.clip(a, 3, 6, out=a) 1827 array([3, 3, 3, 3, 4, 5, 6, 6, 6, 6]) 1828 >>> a 1829 array([3, 3, 3, 3, 4, 5, 6, 6, 6, 6]) 1830 >>> a = np.arange(10) 1831 >>> a 1832 array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) 1833 >>> np.clip(a, [3, 4, 1, 1, 1, 4, 4, 4, 4, 4], 8) 1834 array([3, 4, 2, 3, 4, 5, 6, 7, 8, 8]) 1835 1836 r rU rg r� rF rF rG r ? s Er c C r^ r9 rF �r` rS rT rU r� �initial�whererF rF rG �_sum_dispatcher� r� r� c C sV t | t�r tjdtdd� t| �}|dur||d< |S |S t| tjd||||||d� S )a� 1837 Sum of array elements over a given axis. 1838 1839 Parameters 1840 ---------- 1841 a : array_like 1842 Elements to sum. 1843 axis : None or int or tuple of ints, optional 1844 Axis or axes along which a sum is performed. The default, 1845 axis=None, will sum all of the elements of the input array. If 1846 axis is negative it counts from the last to the first axis. 1847 1848 .. versionadded:: 1.7.0 1849 1850 If axis is a tuple of ints, a sum is performed on all of the axes 1851 specified in the tuple instead of a single axis or all the axes as 1852 before. 1853 dtype : dtype, optional 1854 The type of the returned array and of the accumulator in which the 1855 elements are summed. The dtype of `a` is used by default unless `a` 1856 has an integer dtype of less precision than the default platform 1857 integer. In that case, if `a` is signed then the platform integer 1858 is used while if `a` is unsigned then an unsigned integer of the 1859 same precision as the platform integer is used. 1860 out : ndarray, optional 1861 Alternative output array in which to place the result. It must have 1862 the same shape as the expected output, but the type of the output 1863 values will be cast if necessary. 1864 keepdims : bool, optional 1865 If this is set to True, the axes which are reduced are left 1866 in the result as dimensions with size one. With this option, 1867 the result will broadcast correctly against the input array. 1868 1869 If the default value is passed, then `keepdims` will not be 1870 passed through to the `sum` method of sub-classes of 1871 `ndarray`, however any non-default value will be. If the 1872 sub-class' method does not implement `keepdims` any 1873 exceptions will be raised. 1874 initial : scalar, optional 1875 Starting value for the sum. See `~numpy.ufunc.reduce` for details. 1876 1877 .. versionadded:: 1.15.0 1878 1879 where : array_like of bool, optional 1880 Elements to include in the sum. See `~numpy.ufunc.reduce` for details. 1881 1882 .. versionadded:: 1.17.0 1883 1884 Returns 1885 ------- 1886 sum_along_axis : ndarray 1887 An array with the same shape as `a`, with the specified 1888 axis removed. If `a` is a 0-d array, or if `axis` is None, a scalar 1889 is returned. If an output array is specified, a reference to 1890 `out` is returned. 1891 1892 See Also 1893 -------- 1894 ndarray.sum : Equivalent method. 1895 1896 add.reduce : Equivalent functionality of `add`. 1897 1898 cumsum : Cumulative sum of array elements. 1899 1900 trapz : Integration of array values using the composite trapezoidal rule. 1901 1902 mean, average 1903 1904 Notes 1905 ----- 1906 Arithmetic is modular when using integer types, and no error is 1907 raised on overflow. 1908 1909 The sum of an empty array is the neutral element 0: 1910 1911 >>> np.sum([]) 1912 0.0 1913 1914 For floating point numbers the numerical precision of sum (and 1915 ``np.add.reduce``) is in general limited by directly adding each number 1916 individually to the result causing rounding errors in every step. 1917 However, often numpy will use a numerically better approach (partial 1918 pairwise summation) leading to improved precision in many use-cases. 1919 This improved precision is always provided when no ``axis`` is given. 1920 When ``axis`` is given, it will depend on which axis is summed. 1921 Technically, to provide the best speed possible, the improved precision 1922 is only used when the summation is along the fast axis in memory. 1923 Note that the exact precision may vary depending on other parameters. 1924 In contrast to NumPy, Python's ``math.fsum`` function uses a slower but 1925 more precise approach to summation. 1926 Especially when summing a large number of lower precision floating point 1927 numbers, such as ``float32``, numerical errors can become significant. 1928 In such cases it can be advisable to use `dtype="float64"` to use a higher 1929 precision for the output. 1930 1931 Examples 1932 -------- 1933 >>> np.sum([0.5, 1.5]) 1934 2.0 1935 >>> np.sum([0.5, 0.7, 0.2, 1.5], dtype=np.int32) 1936 1 1937 >>> np.sum([[0, 1], [0, 5]]) 1938 6 1939 >>> np.sum([[0, 1], [0, 5]], axis=0) 1940 array([0, 6]) 1941 >>> np.sum([[0, 1], [0, 5]], axis=1) 1942 array([1, 5]) 1943 >>> np.sum([[0, 1], [np.nan, 5]], where=[False, True], axis=1) 1944 array([1., 5.]) 1945 1946 If the accumulator is too small, overflow occurs: 1947 1948 >>> np.ones(128, dtype=np.int8).sum(dtype=np.int8) 1949 -128 1950 1951 You can also start the sum with a value other than zero: 1952 1953 >>> np.sum([10], initial=5) 1954 15 1955 z�Calling np.sum(generator) is deprecated, and in the future will give a different result. Use np.sum(np.fromiter(generator)) or the python sum builtin instead.� )� 1956 stacklevelN.r1 �r� r� r� ) r= �_gentype�warnings�warn�DeprecationWarning�_sum_r] rL �add)r` rS rT rU r� r� r� �resrF rF rG r1 � s 1957 {��r1 )r� c C � 1958 | ||fS r9 rF �r` rS rU r� r� rF rF rG �_any_dispatcher � 1959 r� c 1960 C � t | tjd|d|||d�S )aK 1961 Test whether any array element along a given axis evaluates to True. 1962 1963 Returns single boolean if `axis` is ``None`` 1964 1965 Parameters 1966 ---------- 1967 a : array_like 1968 Input array or object that can be converted to an array. 1969 axis : None or int or tuple of ints, optional 1970 Axis or axes along which a logical OR reduction is performed. 1971 The default (``axis=None``) is to perform a logical OR over all 1972 the dimensions of the input array. `axis` may be negative, in 1973 which case it counts from the last to the first axis. 1974 1975 .. versionadded:: 1.7.0 1976 1977 If this is a tuple of ints, a reduction is performed on multiple 1978 axes, instead of a single axis or all the axes as before. 1979 out : ndarray, optional 1980 Alternate output array in which to place the result. It must have 1981 the same shape as the expected output and its type is preserved 1982 (e.g., if it is of type float, then it will remain so, returning 1983 1.0 for True and 0.0 for False, regardless of the type of `a`). 1984 See :ref:`ufuncs-output-type` for more details. 1985 1986 keepdims : bool, optional 1987 If this is set to True, the axes which are reduced are left 1988 in the result as dimensions with size one. With this option, 1989 the result will broadcast correctly against the input array. 1990 1991 If the default value is passed, then `keepdims` will not be 1992 passed through to the `any` method of sub-classes of 1993 `ndarray`, however any non-default value will be. If the 1994 sub-class' method does not implement `keepdims` any 1995 exceptions will be raised. 1996 1997 where : array_like of bool, optional 1998 Elements to include in checking for any `True` values. 1999 See `~numpy.ufunc.reduce` for details. 2000 2001 .. versionadded:: 1.20.0 2002 2003 Returns 2004 ------- 2005 any : bool or ndarray 2006 A new boolean or `ndarray` is returned unless `out` is specified, 2007 in which case a reference to `out` is returned. 2008 2009 See Also 2010 -------- 2011 ndarray.any : equivalent method 2012 2013 all : Test whether all elements along a given axis evaluate to True. 2014 2015 Notes 2016 ----- 2017 Not a Number (NaN), positive infinity and negative infinity evaluate 2018 to `True` because these are not equal to zero. 2019 2020 Examples 2021 -------- 2022 >>> np.any([[True, False], [True, True]]) 2023 True 2024 2025 >>> np.any([[True, False], [False, False]], axis=0) 2026 array([ True, False]) 2027 2028 >>> np.any([-1, 0, 5]) 2029 True 2030 2031 >>> np.any(np.nan) 2032 True 2033 2034 >>> np.any([[True, False], [False, False]], where=[[False], [True]]) 2035 False 2036 2037 >>> o=np.array(False) 2038 >>> z=np.any([-1, 4, 5], out=o) 2039 >>> z, o 2040 (array(True), array(True)) 2041 >>> # Check now that z is a reference to o 2042 >>> z is o 2043 True 2044 >>> id(z), id(o) # identity of z and o # doctest: +SKIP 2045 (191614240, 191614240) 2046 2047 r N�r� r� )r] rL � 2048 logical_orr� rF rF rG r s Z�r c C r� r9 rF r� rF rF rG �_all_dispatcher{ r� r� c 2049 C r� )aR 2050 2051 Test whether all array elements along a given axis evaluate to True. 2052 2053 Parameters 2054 ---------- 2055 a : array_like 2056 Input array or object that can be converted to an array. 2057 axis : None or int or tuple of ints, optional 2058 Axis or axes along which a logical AND reduction is performed. 2059 The default (``axis=None``) is to perform a logical AND over all 2060 the dimensions of the input array. `axis` may be negative, in 2061 which case it counts from the last to the first axis. 2062 2063 .. versionadded:: 1.7.0 2064 2065 If this is a tuple of ints, a reduction is performed on multiple 2066 axes, instead of a single axis or all the axes as before. 2067 out : ndarray, optional 2068 Alternate output array in which to place the result. 2069 It must have the same shape as the expected output and its 2070 type is preserved (e.g., if ``dtype(out)`` is float, the result 2071 will consist of 0.0's and 1.0's). See :ref:`ufuncs-output-type` for more 2072 details. 2073 2074 keepdims : bool, optional 2075 If this is set to True, the axes which are reduced are left 2076 in the result as dimensions with size one. With this option, 2077 the result will broadcast correctly against the input array. 2078 2079 If the default value is passed, then `keepdims` will not be 2080 passed through to the `all` method of sub-classes of 2081 `ndarray`, however any non-default value will be. If the 2082 sub-class' method does not implement `keepdims` any 2083 exceptions will be raised. 2084 2085 where : array_like of bool, optional 2086 Elements to include in checking for all `True` values. 2087 See `~numpy.ufunc.reduce` for details. 2088 2089 .. versionadded:: 1.20.0 2090 2091 Returns 2092 ------- 2093 all : ndarray, bool 2094 A new boolean or array is returned unless `out` is specified, 2095 in which case a reference to `out` is returned. 2096 2097 See Also 2098 -------- 2099 ndarray.all : equivalent method 2100 2101 any : Test whether any element along a given axis evaluates to True. 2102 2103 Notes 2104 ----- 2105 Not a Number (NaN), positive infinity and negative infinity 2106 evaluate to `True` because these are not equal to zero. 2107 2108 Examples 2109 -------- 2110 >>> np.all([[True,False],[True,True]]) 2111 False 2112 2113 >>> np.all([[True,False],[True,True]], axis=0) 2114 array([ True, False]) 2115 2116 >>> np.all([-1, 4, 5]) 2117 True 2118 2119 >>> np.all([1.0, np.nan]) 2120 True 2121 2122 >>> np.all([[True, True], [False, True]], where=[[True], [False]]) 2123 True 2124 2125 >>> o=np.array(False) 2126 >>> z=np.all([-1, 4, 5], out=o) 2127 >>> id(z), id(o), z 2128 (28293632, 28293632, array(True)) # may vary 2129 2130 r Nr� )r] rL � logical_andr� rF rF rG r � s S�r c C r^ r9 rF �r` rS rT rU rF rF rG �_cumsum_dispatcher� rd r� c C rt )a� 2131 Return the cumulative sum of the elements along a given axis. 2132 2133 Parameters 2134 ---------- 2135 a : array_like 2136 Input array. 2137 axis : int, optional 2138 Axis along which the cumulative sum is computed. The default 2139 (None) is to compute the cumsum over the flattened array. 2140 dtype : dtype, optional 2141 Type of the returned array and of the accumulator in which the 2142 elements are summed. If `dtype` is not specified, it defaults 2143 to the dtype of `a`, unless `a` has an integer dtype with a 2144 precision less than that of the default platform integer. In 2145 that case, the default platform integer is used. 2146 out : ndarray, optional 2147 Alternative output array in which to place the result. It must 2148 have the same shape and buffer length as the expected output 2149 but the type will be cast if necessary. See :ref:`ufuncs-output-type` for 2150 more details. 2151 2152 Returns 2153 ------- 2154 cumsum_along_axis : ndarray. 2155 A new array holding the result is returned unless `out` is 2156 specified, in which case a reference to `out` is returned. The 2157 result has the same size as `a`, and the same shape as `a` if 2158 `axis` is not None or `a` is a 1-d array. 2159 2160 See Also 2161 -------- 2162 sum : Sum array elements. 2163 trapz : Integration of array values using the composite trapezoidal rule. 2164 diff : Calculate the n-th discrete difference along given axis. 2165 2166 Notes 2167 ----- 2168 Arithmetic is modular when using integer types, and no error is 2169 raised on overflow. 2170 2171 ``cumsum(a)[-1]`` may not be equal to ``sum(a)`` for floating-point 2172 values since ``sum`` may use a pairwise summation routine, reducing 2173 the roundoff-error. See `sum` for more information. 2174 2175 Examples 2176 -------- 2177 >>> a = np.array([[1,2,3], [4,5,6]]) 2178 >>> a 2179 array([[1, 2, 3], 2180 [4, 5, 6]]) 2181 >>> np.cumsum(a) 2182 array([ 1, 3, 6, 10, 15, 21]) 2183 >>> np.cumsum(a, dtype=float) # specifies type of output value(s) 2184 array([ 1., 3., 6., 10., 15., 21.]) 2185 2186 >>> np.cumsum(a,axis=0) # sum over rows for each of the 3 columns 2187 array([[1, 2, 3], 2188 [5, 7, 9]]) 2189 >>> np.cumsum(a,axis=1) # sum over columns for each of the 2 rows 2190 array([[ 1, 3, 6], 2191 [ 4, 9, 15]]) 2192 2193 ``cumsum(b)[-1]`` may not be equal to ``sum(b)`` 2194 2195 >>> b = np.array([1, 2e-9, 3e-9] * 1000000) 2196 >>> b.cumsum()[-1] 2197 1000000.0050045159 2198 >>> b.sum() 2199 1000000.0050000029 2200 2201 r rR rg r� rF rF rG r � s Jr c C r� r9 rF r� rF rF rG �_ptp_dispatcher( 2202 rd r� c C sn i }|t jur ||d< t| �tjur+z| j}W n ty Y n w |d||d�|��S tj| f||d�|��S )a� 2203 2204 Range of values (maximum - minimum) along an axis. 2205 2206 The name of the function comes from the acronym for 'peak to peak'. 2207 2208 .. warning:: 2209 `ptp` preserves the data type of the array. This means the 2210 return value for an input of signed integers with n bits 2211 (e.g. `np.int8`, `np.int16`, etc) is also a signed integer 2212 with n bits. In that case, peak-to-peak values greater than 2213 ``2**(n-1)-1`` will be returned as negative values. An example 2214 with a work-around is shown below. 2215 2216 Parameters 2217 ---------- 2218 a : array_like 2219 Input values. 2220 axis : None or int or tuple of ints, optional 2221 Axis along which to find the peaks. By default, flatten the 2222 array. `axis` may be negative, in 2223 which case it counts from the last to the first axis. 2224 2225 .. versionadded:: 1.15.0 2226 2227 If this is a tuple of ints, a reduction is performed on multiple 2228 axes, instead of a single axis or all the axes as before. 2229 out : array_like 2230 Alternative output array in which to place the result. It must 2231 have the same shape and buffer length as the expected output, 2232 but the type of the output values will be cast if necessary. 2233 2234 keepdims : bool, optional 2235 If this is set to True, the axes which are reduced are left 2236 in the result as dimensions with size one. With this option, 2237 the result will broadcast correctly against the input array. 2238 2239 If the default value is passed, then `keepdims` will not be 2240 passed through to the `ptp` method of sub-classes of 2241 `ndarray`, however any non-default value will be. If the 2242 sub-class' method does not implement `keepdims` any 2243 exceptions will be raised. 2244 2245 Returns 2246 ------- 2247 ptp : ndarray or scalar 2248 The range of a given array - `scalar` if array is one-dimensional 2249 or a new array holding the result along the given axis 2250 2251 Examples 2252 -------- 2253 >>> x = np.array([[4, 9, 2, 10], 2254 ... [6, 9, 7, 12]]) 2255 2256 >>> np.ptp(x, axis=1) 2257 array([8, 6]) 2258 2259 >>> np.ptp(x, axis=0) 2260 array([2, 0, 5, 2]) 2261 2262 >>> np.ptp(x) 2263 10 2264 2265 This example shows that a negative value can be returned when 2266 the input is an array of signed integers. 2267 2268 >>> y = np.array([[1, 127], 2269 ... [0, 127], 2270 ... [-1, 127], 2271 ... [-2, 127]], dtype=np.int8) 2272 >>> np.ptp(y, axis=1) 2273 array([ 126, 127, -128, -127], dtype=int8) 2274 2275 A work-around is to use the `view()` method to view the result as 2276 unsigned integers with the same bit width: 2277 2278 >>> np.ptp(y, axis=1).view(np.uint8) 2279 array([126, 127, 128, 129], dtype=uint8) 2280 2281 r� rV NrF ) rL rM rX r> r? r# r; r �_ptp)r` rS rU r� r[ r# rF rF rG r# , 2282 s Q 2283 2284 �r# c C r� r9 rF �r` rS rU r� r� r� rF rF rG �_amax_dispatcher� 2285 r� r� c C � t | tjd|d||||d� S )a� 2286 Return the maximum of an array or maximum along an axis. 2287 2288 Parameters 2289 ---------- 2290 a : array_like 2291 Input data. 2292 axis : None or int or tuple of ints, optional 2293 Axis or axes along which to operate. By default, flattened input is 2294 used. 2295 2296 .. versionadded:: 1.7.0 2297 2298 If this is a tuple of ints, the maximum is selected over multiple axes, 2299 instead of a single axis or all the axes as before. 2300 out : ndarray, optional 2301 Alternative output array in which to place the result. Must 2302 be of the same shape and buffer length as the expected output. 2303 See :ref:`ufuncs-output-type` for more details. 2304 2305 keepdims : bool, optional 2306 If this is set to True, the axes which are reduced are left 2307 in the result as dimensions with size one. With this option, 2308 the result will broadcast correctly against the input array. 2309 2310 If the default value is passed, then `keepdims` will not be 2311 passed through to the `amax` method of sub-classes of 2312 `ndarray`, however any non-default value will be. If the 2313 sub-class' method does not implement `keepdims` any 2314 exceptions will be raised. 2315 2316 initial : scalar, optional 2317 The minimum value of an output element. Must be present to allow 2318 computation on empty slice. See `~numpy.ufunc.reduce` for details. 2319 2320 .. versionadded:: 1.15.0 2321 2322 where : array_like of bool, optional 2323 Elements to compare for the maximum. See `~numpy.ufunc.reduce` 2324 for details. 2325 2326 .. versionadded:: 1.17.0 2327 2328 Returns 2329 ------- 2330 amax : ndarray or scalar 2331 Maximum of `a`. If `axis` is None, the result is a scalar value. 2332 If `axis` is an int, the result is an array of dimension 2333 ``a.ndim - 1``. If `axis` is a tuple, the result is an array of 2334 dimension ``a.ndim - len(axis)``. 2335 2336 See Also 2337 -------- 2338 amin : 2339 The minimum value of an array along a given axis, propagating any NaNs. 2340 nanmax : 2341 The maximum value of an array along a given axis, ignoring any NaNs. 2342 maximum : 2343 Element-wise maximum of two arrays, propagating any NaNs. 2344 fmax : 2345 Element-wise maximum of two arrays, ignoring any NaNs. 2346 argmax : 2347 Return the indices of the maximum values. 2348 2349 nanmin, minimum, fmin 2350 2351 Notes 2352 ----- 2353 NaN values are propagated, that is if at least one item is NaN, the 2354 corresponding max value will be NaN as well. To ignore NaN values 2355 (MATLAB behavior), please use nanmax. 2356 2357 Don't use `amax` for element-wise comparison of 2 arrays; when 2358 ``a.shape[0]`` is 2, ``maximum(a[0], a[1])`` is faster than 2359 ``amax(a, axis=0)``. 2360 2361 Examples 2362 -------- 2363 >>> a = np.arange(4).reshape((2,2)) 2364 >>> a 2365 array([[0, 1], 2366 [2, 3]]) 2367 >>> np.amax(a) # Maximum of the flattened array 2368 3 2369 >>> np.amax(a, axis=0) # Maxima along the first axis 2370 array([2, 3]) 2371 >>> np.amax(a, axis=1) # Maxima along the second axis 2372 array([1, 3]) 2373 >>> np.amax(a, where=[False, True], initial=-1, axis=0) 2374 array([-1, 3]) 2375 >>> b = np.arange(5, dtype=float) 2376 >>> b[2] = np.NaN 2377 >>> np.amax(b) 2378 nan 2379 >>> np.amax(b, where=~np.isnan(b), initial=-1) 2380 4.0 2381 >>> np.nanmax(b) 2382 4.0 2383 2384 You can use an initial value to compute the maximum of an empty slice, or 2385 to initialize it to a different value: 2386 2387 >>> np.amax([[-50], [10]], axis=-1, initial=0) 2388 array([ 0, 10]) 2389 2390 Notice that the initial value is used as one of the elements for which the 2391 maximum is determined, unlike for the default argument Python's max 2392 function, which is only used for empty iterables. 2393 2394 >>> np.amax([5], initial=6) 2395 6 2396 >>> max([5], default=6) 2397 5 2398 �maxNr� )r] rL �maximumr� rF rF rG r � 2399 � u�r c C r� r9 rF r� rF rF rG �_amin_dispatcher r� r� c C r� )a� 2400 Return the minimum of an array or minimum along an axis. 2401 2402 Parameters 2403 ---------- 2404 a : array_like 2405 Input data. 2406 axis : None or int or tuple of ints, optional 2407 Axis or axes along which to operate. By default, flattened input is 2408 used. 2409 2410 .. versionadded:: 1.7.0 2411 2412 If this is a tuple of ints, the minimum is selected over multiple axes, 2413 instead of a single axis or all the axes as before. 2414 out : ndarray, optional 2415 Alternative output array in which to place the result. Must 2416 be of the same shape and buffer length as the expected output. 2417 See :ref:`ufuncs-output-type` for more details. 2418 2419 keepdims : bool, optional 2420 If this is set to True, the axes which are reduced are left 2421 in the result as dimensions with size one. With this option, 2422 the result will broadcast correctly against the input array. 2423 2424 If the default value is passed, then `keepdims` will not be 2425 passed through to the `amin` method of sub-classes of 2426 `ndarray`, however any non-default value will be. If the 2427 sub-class' method does not implement `keepdims` any 2428 exceptions will be raised. 2429 2430 initial : scalar, optional 2431 The maximum value of an output element. Must be present to allow 2432 computation on empty slice. See `~numpy.ufunc.reduce` for details. 2433 2434 .. versionadded:: 1.15.0 2435 2436 where : array_like of bool, optional 2437 Elements to compare for the minimum. See `~numpy.ufunc.reduce` 2438 for details. 2439 2440 .. versionadded:: 1.17.0 2441 2442 Returns 2443 ------- 2444 amin : ndarray or scalar 2445 Minimum of `a`. If `axis` is None, the result is a scalar value. 2446 If `axis` is an int, the result is an array of dimension 2447 ``a.ndim - 1``. If `axis` is a tuple, the result is an array of 2448 dimension ``a.ndim - len(axis)``. 2449 2450 See Also 2451 -------- 2452 amax : 2453 The maximum value of an array along a given axis, propagating any NaNs. 2454 nanmin : 2455 The minimum value of an array along a given axis, ignoring any NaNs. 2456 minimum : 2457 Element-wise minimum of two arrays, propagating any NaNs. 2458 fmin : 2459 Element-wise minimum of two arrays, ignoring any NaNs. 2460 argmin : 2461 Return the indices of the minimum values. 2462 2463 nanmax, maximum, fmax 2464 2465 Notes 2466 ----- 2467 NaN values are propagated, that is if at least one item is NaN, the 2468 corresponding min value will be NaN as well. To ignore NaN values 2469 (MATLAB behavior), please use nanmin. 2470 2471 Don't use `amin` for element-wise comparison of 2 arrays; when 2472 ``a.shape[0]`` is 2, ``minimum(a[0], a[1])`` is faster than 2473 ``amin(a, axis=0)``. 2474 2475 Examples 2476 -------- 2477 >>> a = np.arange(4).reshape((2,2)) 2478 >>> a 2479 array([[0, 1], 2480 [2, 3]]) 2481 >>> np.amin(a) # Minimum of the flattened array 2482 0 2483 >>> np.amin(a, axis=0) # Minima along the first axis 2484 array([0, 1]) 2485 >>> np.amin(a, axis=1) # Minima along the second axis 2486 array([0, 2]) 2487 >>> np.amin(a, where=[False, True], initial=10, axis=0) 2488 array([10, 1]) 2489 2490 >>> b = np.arange(5, dtype=float) 2491 >>> b[2] = np.NaN 2492 >>> np.amin(b) 2493 nan 2494 >>> np.amin(b, where=~np.isnan(b), initial=10) 2495 0.0 2496 >>> np.nanmin(b) 2497 0.0 2498 2499 >>> np.amin([[-50], [10]], axis=-1, initial=0) 2500 array([-50, 0]) 2501 2502 Notice that the initial value is used as one of the elements for which the 2503 minimum is determined, unlike for the default argument Python's max 2504 function, which is only used for empty iterables. 2505 2506 Notice that this isn't the same as Python's ``default`` argument. 2507 2508 >>> np.amin([6], initial=5) 2509 5 2510 >>> min([6], default=5) 2511 6 2512 �minNr� )r] rL �minimumr� rF rF rG r r� r c C r^ r9 rF r� rF rF rG �_prod_dispatcher� r� r� c C s t | tjd||||||d� S )a� 2513 Return the product of array elements over a given axis. 2514 2515 Parameters 2516 ---------- 2517 a : array_like 2518 Input data. 2519 axis : None or int or tuple of ints, optional 2520 Axis or axes along which a product is performed. The default, 2521 axis=None, will calculate the product of all the elements in the 2522 input array. If axis is negative it counts from the last to the 2523 first axis. 2524 2525 .. versionadded:: 1.7.0 2526 2527 If axis is a tuple of ints, a product is performed on all of the 2528 axes specified in the tuple instead of a single axis or all the 2529 axes as before. 2530 dtype : dtype, optional 2531 The type of the returned array, as well as of the accumulator in 2532 which the elements are multiplied. The dtype of `a` is used by 2533 default unless `a` has an integer dtype of less precision than the 2534 default platform integer. In that case, if `a` is signed then the 2535 platform integer is used while if `a` is unsigned then an unsigned 2536 integer of the same precision as the platform integer is used. 2537 out : ndarray, optional 2538 Alternative output array in which to place the result. It must have 2539 the same shape as the expected output, but the type of the output 2540 values will be cast if necessary. 2541 keepdims : bool, optional 2542 If this is set to True, the axes which are reduced are left in the 2543 result as dimensions with size one. With this option, the result 2544 will broadcast correctly against the input array. 2545 2546 If the default value is passed, then `keepdims` will not be 2547 passed through to the `prod` method of sub-classes of 2548 `ndarray`, however any non-default value will be. If the 2549 sub-class' method does not implement `keepdims` any 2550 exceptions will be raised. 2551 initial : scalar, optional 2552 The starting value for this product. See `~numpy.ufunc.reduce` for details. 2553 2554 .. versionadded:: 1.15.0 2555 2556 where : array_like of bool, optional 2557 Elements to include in the product. See `~numpy.ufunc.reduce` for details. 2558 2559 .. versionadded:: 1.17.0 2560 2561 Returns 2562 ------- 2563 product_along_axis : ndarray, see `dtype` parameter above. 2564 An array shaped as `a` but with the specified axis removed. 2565 Returns a reference to `out` if specified. 2566 2567 See Also 2568 -------- 2569 ndarray.prod : equivalent method 2570 :ref:`ufuncs-output-type` 2571 2572 Notes 2573 ----- 2574 Arithmetic is modular when using integer types, and no error is 2575 raised on overflow. That means that, on a 32-bit platform: 2576 2577 >>> x = np.array([536870910, 536870910, 536870910, 536870910]) 2578 >>> np.prod(x) 2579 16 # may vary 2580 2581 The product of an empty array is the neutral element 1: 2582 2583 >>> np.prod([]) 2584 1.0 2585 2586 Examples 2587 -------- 2588 By default, calculate the product of all elements: 2589 2590 >>> np.prod([1.,2.]) 2591 2.0 2592 2593 Even when the input array is two-dimensional: 2594 2595 >>> a = np.array([[1., 2.], [3., 4.]]) 2596 >>> np.prod(a) 2597 24.0 2598 2599 But we can also specify the axis over which to multiply: 2600 2601 >>> np.prod(a, axis=1) 2602 array([ 2., 12.]) 2603 >>> np.prod(a, axis=0) 2604 array([3., 8.]) 2605 2606 Or select specific elements to include: 2607 2608 >>> np.prod([1., np.nan, 3.], where=[True, False, True]) 2609 3.0 2610 2611 If the type of `x` is unsigned, then the output type is 2612 the unsigned platform integer: 2613 2614 >>> x = np.array([1, 2, 3], dtype=np.uint8) 2615 >>> np.prod(x).dtype == np.uint 2616 True 2617 2618 If `x` is of a signed integer type, then the output type 2619 is the default platform integer: 2620 2621 >>> x = np.array([1, 2, 3], dtype=np.int8) 2622 >>> np.prod(x).dtype == int 2623 True 2624 2625 You can also start the product with a value other than one: 2626 2627 >>> np.prod([1, 2], initial=5) 2628 10 2629 r! r� )r] rL �multiplyr� rF rF rG r! � s y�r! c C r^ r9 rF r� rF rF rG �_cumprod_dispatcher rd r� c C rt )al 2630 Return the cumulative product of elements along a given axis. 2631 2632 Parameters 2633 ---------- 2634 a : array_like 2635 Input array. 2636 axis : int, optional 2637 Axis along which the cumulative product is computed. By default 2638 the input is flattened. 2639 dtype : dtype, optional 2640 Type of the returned array, as well as of the accumulator in which 2641 the elements are multiplied. If *dtype* is not specified, it 2642 defaults to the dtype of `a`, unless `a` has an integer dtype with 2643 a precision less than that of the default platform integer. In 2644 that case, the default platform integer is used instead. 2645 out : ndarray, optional 2646 Alternative output array in which to place the result. It must 2647 have the same shape and buffer length as the expected output 2648 but the type of the resulting values will be cast if necessary. 2649 2650 Returns 2651 ------- 2652 cumprod : ndarray 2653 A new array holding the result is returned unless `out` is 2654 specified, in which case a reference to out is returned. 2655 2656 See Also 2657 -------- 2658 :ref:`ufuncs-output-type` 2659 2660 Notes 2661 ----- 2662 Arithmetic is modular when using integer types, and no error is 2663 raised on overflow. 2664 2665 Examples 2666 -------- 2667 >>> a = np.array([1,2,3]) 2668 >>> np.cumprod(a) # intermediate results 1, 1*2 2669 ... # total product 1*2*3 = 6 2670 array([1, 2, 6]) 2671 >>> a = np.array([[1, 2, 3], [4, 5, 6]]) 2672 >>> np.cumprod(a, dtype=float) # specify type of output 2673 array([ 1., 2., 6., 24., 120., 720.]) 2674 2675 The cumulative product for each column (i.e., over the rows) of `a`: 2676 2677 >>> np.cumprod(a, axis=0) 2678 array([[ 1, 2, 3], 2679 [ 4, 10, 18]]) 2680 2681 The cumulative product for each row (i.e. over the columns) of `a`: 2682 2683 >>> np.cumprod(a,axis=1) 2684 array([[ 1, 2, 6], 2685 [ 4, 20, 120]]) 2686 2687 r rR rg r� rF rF rG r r� r c C rh r9 rF r� rF rF rG �_ndim_dispatcherL rm r� c C s& z| j W S ty t| �j Y S w )a[ 2688 Return the number of dimensions of an array. 2689 2690 Parameters 2691 ---------- 2692 a : array_like 2693 Input array. If it is not already an ndarray, a conversion is 2694 attempted. 2695 2696 Returns 2697 ------- 2698 number_of_dimensions : int 2699 The number of dimensions in `a`. Scalars are zero-dimensional. 2700 2701 See Also 2702 -------- 2703 ndarray.ndim : equivalent method 2704 shape : dimensions of array 2705 ndarray.shape : dimensions of array 2706 2707 Examples 2708 -------- 2709 >>> np.ndim([[1,2,3],[4,5,6]]) 2710 2 2711 >>> np.ndim(np.array([[1,2,3],[4,5,6]])) 2712 2 2713 >>> np.ndim(1) 2714 0 2715 2716 )r r; r r� rF rF rG r P s 2717 �r c C rh r9 rF r� rF rF rG �_size_dispatcherv rm r� c C s\ |du rz| j W S ty t| �j Y S w z| j| W S ty- t| �j| Y S w )a� 2718 Return the number of elements along a given axis. 2719 2720 Parameters 2721 ---------- 2722 a : array_like 2723 Input data. 2724 axis : int, optional 2725 Axis along which the elements are counted. By default, give 2726 the total number of elements. 2727 2728 Returns 2729 ------- 2730 element_count : int 2731 Number of elements along the specified axis. 2732 2733 See Also 2734 -------- 2735 shape : dimensions of array 2736 ndarray.shape : dimensions of array 2737 ndarray.size : number of elements in array 2738 2739 Examples 2740 -------- 2741 >>> a = np.array([[1,2,3],[4,5,6]]) 2742 >>> np.size(a) 2743 6 2744 >>> np.size(a,1) 2745 3 2746 >>> np.size(a,0) 2747 2 2748 2749 N)r, r; r r+ r� rF rF rG r, z s # � �r, c C r� r9 rF �r` �decimalsrU rF rF rG �_around_dispatcher� rd r� c C ro )av 2750 Evenly round to the given number of decimals. 2751 2752 Parameters 2753 ---------- 2754 a : array_like 2755 Input data. 2756 decimals : int, optional 2757 Number of decimal places to round to (default: 0). If 2758 decimals is negative, it specifies the number of positions to 2759 the left of the decimal point. 2760 out : ndarray, optional 2761 Alternative output array in which to place the result. It must have 2762 the same shape as the expected output, but the type of the output 2763 values will be cast if necessary. See :ref:`ufuncs-output-type` for more 2764 details. 2765 2766 Returns 2767 ------- 2768 rounded_array : ndarray 2769 An array of the same type as `a`, containing the rounded values. 2770 Unless `out` was specified, a new array is created. A reference to 2771 the result is returned. 2772 2773 The real and imaginary parts of complex numbers are rounded 2774 separately. The result of rounding a float is a float. 2775 2776 See Also 2777 -------- 2778 ndarray.round : equivalent method 2779 ceil, fix, floor, rint, trunc 2780 2781 2782 Notes 2783 ----- 2784 `~numpy.round` is often used as an alias for `~numpy.around`. 2785 2786 For values exactly halfway between rounded decimal values, NumPy 2787 rounds to the nearest even value. Thus 1.5 and 2.5 round to 2.0, 2788 -0.5 and 0.5 round to 0.0, etc. 2789 2790 ``np.around`` uses a fast but sometimes inexact algorithm to round 2791 floating-point datatypes. For positive `decimals` it is equivalent to 2792 ``np.true_divide(np.rint(a * 10**decimals), 10**decimals)``, which has 2793 error due to the inexact representation of decimal fractions in the IEEE 2794 floating point standard [1]_ and errors introduced when scaling by powers 2795 of ten. For instance, note the extra "1" in the following: 2796 2797 >>> np.round(56294995342131.5, 3) 2798 56294995342131.51 2799 2800 If your goal is to print such values with a fixed number of decimals, it is 2801 preferable to use numpy's float printing routines to limit the number of 2802 printed decimals: 2803 2804 >>> np.format_float_positional(56294995342131.5, precision=3) 2805 '56294995342131.5' 2806 2807 The float printing routines use an accurate but much more computationally 2808 demanding algorithm to compute the number of digits after the decimal 2809 point. 2810 2811 Alternatively, Python's builtin `round` function uses a more accurate 2812 but slower algorithm for 64-bit floating point values: 2813 2814 >>> round(56294995342131.5, 3) 2815 56294995342131.5 2816 >>> np.round(16.055, 2), round(16.055, 2) # equals 16.0549999999999997 2817 (16.06, 16.05) 2818 2819 2820 References 2821 ---------- 2822 .. [1] "Lecture Notes on the Status of IEEE 754", William Kahan, 2823 https://people.eecs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF 2824 2825 Examples 2826 -------- 2827 >>> np.around([0.37, 1.64]) 2828 array([0., 2.]) 2829 >>> np.around([0.37, 1.64], decimals=1) 2830 array([0.4, 1.6]) 2831 >>> np.around([.5, 1.5, 2.5, 3.5, 4.5]) # rounds to nearest even value 2832 array([0., 2., 2., 4., 4.]) 2833 >>> np.around([1,2,3,11], decimals=1) # ndarray of ints is returned 2834 array([ 1, 2, 3, 11]) 2835 >>> np.around([1,2,3,11], decimals=-1) 2836 array([ 0, 0, 0, 10]) 2837 2838 �round�r� rU rg r� rF rF rG r � s \r c C s 2839 | ||fS r9 rF )r` rS rT rU r� r� rF rF rG �_mean_dispatcher r� r� c C s� i }|t jur ||d< |t jur||d< t| �tjur5z| j}W n ty) Y n w |d|||d�|��S tj| f|||d�|��S )a� 2840 Compute the arithmetic mean along the specified axis. 2841 2842 Returns the average of the array elements. The average is taken over 2843 the flattened array by default, otherwise over the specified axis. 2844 `float64` intermediate and return values are used for integer inputs. 2845 2846 Parameters 2847 ---------- 2848 a : array_like 2849 Array containing numbers whose mean is desired. If `a` is not an 2850 array, a conversion is attempted. 2851 axis : None or int or tuple of ints, optional 2852 Axis or axes along which the means are computed. The default is to 2853 compute the mean of the flattened array. 2854 2855 .. versionadded:: 1.7.0 2856 2857 If this is a tuple of ints, a mean is performed over multiple axes, 2858 instead of a single axis or all the axes as before. 2859 dtype : data-type, optional 2860 Type to use in computing the mean. For integer inputs, the default 2861 is `float64`; for floating point inputs, it is the same as the 2862 input dtype. 2863 out : ndarray, optional 2864 Alternate output array in which to place the result. The default 2865 is ``None``; if provided, it must have the same shape as the 2866 expected output, but the type will be cast if necessary. 2867 See :ref:`ufuncs-output-type` for more details. 2868 2869 keepdims : bool, optional 2870 If this is set to True, the axes which are reduced are left 2871 in the result as dimensions with size one. With this option, 2872 the result will broadcast correctly against the input array. 2873 2874 If the default value is passed, then `keepdims` will not be 2875 passed through to the `mean` method of sub-classes of 2876 `ndarray`, however any non-default value will be. If the 2877 sub-class' method does not implement `keepdims` any 2878 exceptions will be raised. 2879 2880 where : array_like of bool, optional 2881 Elements to include in the mean. See `~numpy.ufunc.reduce` for details. 2882 2883 .. versionadded:: 1.20.0 2884 2885 Returns 2886 ------- 2887 m : ndarray, see dtype parameter above 2888 If `out=None`, returns a new array containing the mean values, 2889 otherwise a reference to the output array is returned. 2890 2891 See Also 2892 -------- 2893 average : Weighted average 2894 std, var, nanmean, nanstd, nanvar 2895 2896 Notes 2897 ----- 2898 The arithmetic mean is the sum of the elements along the axis divided 2899 by the number of elements. 2900 2901 Note that for floating-point input, the mean is computed using the 2902 same precision the input has. Depending on the input data, this can 2903 cause the results to be inaccurate, especially for `float32` (see 2904 example below). Specifying a higher-precision accumulator using the 2905 `dtype` keyword can alleviate this issue. 2906 2907 By default, `float16` results are computed using `float32` intermediates 2908 for extra precision. 2909 2910 Examples 2911 -------- 2912 >>> a = np.array([[1, 2], [3, 4]]) 2913 >>> np.mean(a) 2914 2.5 2915 >>> np.mean(a, axis=0) 2916 array([2., 3.]) 2917 >>> np.mean(a, axis=1) 2918 array([1.5, 3.5]) 2919 2920 In single precision, `mean` can be inaccurate: 2921 2922 >>> a = np.zeros((2, 512*512), dtype=np.float32) 2923 >>> a[0, :] = 1.0 2924 >>> a[1, :] = 0.1 2925 >>> np.mean(a) 2926 0.54999924 2927 2928 Computing the mean in float64 is more accurate: 2929 2930 >>> np.mean(a, dtype=np.float64) 2931 0.55000000074505806 # may vary 2932 2933 Specifying a where argument: 2934 2935 >>> a = np.array([[5, 9, 13], [14, 10, 12], [11, 15, 19]]) 2936 >>> np.mean(a) 2937 12.0 2938 >>> np.mean(a, where=[[True], [False], [False]]) 2939 9.0 2940 2941 r� r� rR NrF ) rL rM rX r> r? r r; r �_mean)r` rS rT rU r� r� r[ r rF rF rG r s" j 2942 2943 2944 � ��r c C � 2945 | ||fS r9 rF �r` rS rT rU �ddofr� r� rF rF rG �_std_dispatcher� r� r� c C � i }|t jur ||d< |t jur||d< t| �tjur6z| j}W n ty) Y n w |d||||d�|��S tj| f||||d�|��S )a| 2946 Compute the standard deviation along the specified axis. 2947 2948 Returns the standard deviation, a measure of the spread of a distribution, 2949 of the array elements. The standard deviation is computed for the 2950 flattened array by default, otherwise over the specified axis. 2951 2952 Parameters 2953 ---------- 2954 a : array_like 2955 Calculate the standard deviation of these values. 2956 axis : None or int or tuple of ints, optional 2957 Axis or axes along which the standard deviation is computed. The 2958 default is to compute the standard deviation of the flattened array. 2959 2960 .. versionadded:: 1.7.0 2961 2962 If this is a tuple of ints, a standard deviation is performed over 2963 multiple axes, instead of a single axis or all the axes as before. 2964 dtype : dtype, optional 2965 Type to use in computing the standard deviation. For arrays of 2966 integer type the default is float64, for arrays of float types it is 2967 the same as the array type. 2968 out : ndarray, optional 2969 Alternative output array in which to place the result. It must have 2970 the same shape as the expected output but the type (of the calculated 2971 values) will be cast if necessary. 2972 ddof : int, optional 2973 Means Delta Degrees of Freedom. The divisor used in calculations 2974 is ``N - ddof``, where ``N`` represents the number of elements. 2975 By default `ddof` is zero. 2976 keepdims : bool, optional 2977 If this is set to True, the axes which are reduced are left 2978 in the result as dimensions with size one. With this option, 2979 the result will broadcast correctly against the input array. 2980 2981 If the default value is passed, then `keepdims` will not be 2982 passed through to the `std` method of sub-classes of 2983 `ndarray`, however any non-default value will be. If the 2984 sub-class' method does not implement `keepdims` any 2985 exceptions will be raised. 2986 2987 where : array_like of bool, optional 2988 Elements to include in the standard deviation. 2989 See `~numpy.ufunc.reduce` for details. 2990 2991 .. versionadded:: 1.20.0 2992 2993 Returns 2994 ------- 2995 standard_deviation : ndarray, see dtype parameter above. 2996 If `out` is None, return a new array containing the standard deviation, 2997 otherwise return a reference to the output array. 2998 2999 See Also 3000 -------- 3001 var, mean, nanmean, nanstd, nanvar 3002 :ref:`ufuncs-output-type` 3003 3004 Notes 3005 ----- 3006 The standard deviation is the square root of the average of the squared 3007 deviations from the mean, i.e., ``std = sqrt(mean(x))``, where 3008 ``x = abs(a - a.mean())**2``. 3009 3010 The average squared deviation is typically calculated as ``x.sum() / N``, 3011 where ``N = len(x)``. If, however, `ddof` is specified, the divisor 3012 ``N - ddof`` is used instead. In standard statistical practice, ``ddof=1`` 3013 provides an unbiased estimator of the variance of the infinite population. 3014 ``ddof=0`` provides a maximum likelihood estimate of the variance for 3015 normally distributed variables. The standard deviation computed in this 3016 function is the square root of the estimated variance, so even with 3017 ``ddof=1``, it will not be an unbiased estimate of the standard deviation 3018 per se. 3019 3020 Note that, for complex numbers, `std` takes the absolute 3021 value before squaring, so that the result is always real and nonnegative. 3022 3023 For floating-point input, the *std* is computed using the same 3024 precision the input has. Depending on the input data, this can cause 3025 the results to be inaccurate, especially for float32 (see example below). 3026 Specifying a higher-accuracy accumulator using the `dtype` keyword can 3027 alleviate this issue. 3028 3029 Examples 3030 -------- 3031 >>> a = np.array([[1, 2], [3, 4]]) 3032 >>> np.std(a) 3033 1.1180339887498949 # may vary 3034 >>> np.std(a, axis=0) 3035 array([1., 1.]) 3036 >>> np.std(a, axis=1) 3037 array([0.5, 0.5]) 3038 3039 In single precision, std() can be inaccurate: 3040 3041 >>> a = np.zeros((2, 512*512), dtype=np.float32) 3042 >>> a[0, :] = 1.0 3043 >>> a[1, :] = 0.1 3044 >>> np.std(a) 3045 0.45000005 3046 3047 Computing the standard deviation in float64 is more accurate: 3048 3049 >>> np.std(a, dtype=np.float64) 3050 0.44999999925494177 # may vary 3051 3052 Specifying a where argument: 3053 3054 >>> a = np.array([[14, 8, 11, 10], [7, 9, 10, 11], [10, 15, 5, 10]]) 3055 >>> np.std(a) 3056 2.614064523559687 # may vary 3057 >>> np.std(a, where=[[True], [True], [False]]) 3058 2.0 3059 3060 r� r� �rS rT rU r� NrF ) rL rM rX r> r? r0 r; r �_std) r` rS rT rU r� r� r� r[ r0 rF rF rG r0 � s w 3061 3062 3063 ��r0 c C r� r9 rF r� rF rF rG �_var_dispatcher r� r� c C r� )a_ 3064 Compute the variance along the specified axis. 3065 3066 Returns the variance of the array elements, a measure of the spread of a 3067 distribution. The variance is computed for the flattened array by 3068 default, otherwise over the specified axis. 3069 3070 Parameters 3071 ---------- 3072 a : array_like 3073 Array containing numbers whose variance is desired. If `a` is not an 3074 array, a conversion is attempted. 3075 axis : None or int or tuple of ints, optional 3076 Axis or axes along which the variance is computed. The default is to 3077 compute the variance of the flattened array. 3078 3079 .. versionadded:: 1.7.0 3080 3081 If this is a tuple of ints, a variance is performed over multiple axes, 3082 instead of a single axis or all the axes as before. 3083 dtype : data-type, optional 3084 Type to use in computing the variance. For arrays of integer type 3085 the default is `float64`; for arrays of float types it is the same as 3086 the array type. 3087 out : ndarray, optional 3088 Alternate output array in which to place the result. It must have 3089 the same shape as the expected output, but the type is cast if 3090 necessary. 3091 ddof : int, optional 3092 "Delta Degrees of Freedom": the divisor used in the calculation is 3093 ``N - ddof``, where ``N`` represents the number of elements. By 3094 default `ddof` is zero. 3095 keepdims : bool, optional 3096 If this is set to True, the axes which are reduced are left 3097 in the result as dimensions with size one. With this option, 3098 the result will broadcast correctly against the input array. 3099 3100 If the default value is passed, then `keepdims` will not be 3101 passed through to the `var` method of sub-classes of 3102 `ndarray`, however any non-default value will be. If the 3103 sub-class' method does not implement `keepdims` any 3104 exceptions will be raised. 3105 3106 where : array_like of bool, optional 3107 Elements to include in the variance. See `~numpy.ufunc.reduce` for 3108 details. 3109 3110 .. versionadded:: 1.20.0 3111 3112 Returns 3113 ------- 3114 variance : ndarray, see dtype parameter above 3115 If ``out=None``, returns a new array containing the variance; 3116 otherwise, a reference to the output array is returned. 3117 3118 See Also 3119 -------- 3120 std, mean, nanmean, nanstd, nanvar 3121 :ref:`ufuncs-output-type` 3122 3123 Notes 3124 ----- 3125 The variance is the average of the squared deviations from the mean, 3126 i.e., ``var = mean(x)``, where ``x = abs(a - a.mean())**2``. 3127 3128 The mean is typically calculated as ``x.sum() / N``, where ``N = len(x)``. 3129 If, however, `ddof` is specified, the divisor ``N - ddof`` is used 3130 instead. In standard statistical practice, ``ddof=1`` provides an 3131 unbiased estimator of the variance of a hypothetical infinite population. 3132 ``ddof=0`` provides a maximum likelihood estimate of the variance for 3133 normally distributed variables. 3134 3135 Note that for complex numbers, the absolute value is taken before 3136 squaring, so that the result is always real and nonnegative. 3137 3138 For floating-point input, the variance is computed using the same 3139 precision the input has. Depending on the input data, this can cause 3140 the results to be inaccurate, especially for `float32` (see example 3141 below). Specifying a higher-accuracy accumulator using the ``dtype`` 3142 keyword can alleviate this issue. 3143 3144 Examples 3145 -------- 3146 >>> a = np.array([[1, 2], [3, 4]]) 3147 >>> np.var(a) 3148 1.25 3149 >>> np.var(a, axis=0) 3150 array([1., 1.]) 3151 >>> np.var(a, axis=1) 3152 array([0.25, 0.25]) 3153 3154 In single precision, var() can be inaccurate: 3155 3156 >>> a = np.zeros((2, 512*512), dtype=np.float32) 3157 >>> a[0, :] = 1.0 3158 >>> a[1, :] = 0.1 3159 >>> np.var(a) 3160 0.20250003 3161 3162 Computing the variance in float64 is more accurate: 3163 3164 >>> np.var(a, dtype=np.float64) 3165 0.20249999932944759 # may vary 3166 >>> ((1-0.55)**2 + (0.1-0.55)**2)/2 3167 0.2025 3168 3169 Specifying a where argument: 3170 3171 >>> a = np.array([[14, 8, 11, 10], [7, 9, 10, 11], [10, 15, 5, 10]]) 3172 >>> np.var(a) 3173 6.833333333333333 # may vary 3174 >>> np.var(a, where=[[True], [True], [False]]) 3175 4.0 3176 3177 r� r� r� NrF ) rL rM rX r> r? r6 r; r �_var) r` rS rT rU r� r� r� r[ r6 rF rF rG r6 s v 3178 3179 3180 ��r6 c C s t | ||d�S )z� 3181 Round an array to the given number of decimals. 3182 3183 See Also 3184 -------- 3185 around : equivalent function; see for details. 3186 r� )r r� rF rF rG r) � � r) F)�verifyc O � t | i |��S )z� 3187 Return the product of array elements over a given axis. 3188 3189 See Also 3190 -------- 3191 prod : equivalent function; see for details. 3192 )r! �rB r[ rF rF rG r" � r� r" c O r� )z� 3193 Return the cumulative product over the given axis. 3194 3195 See Also 3196 -------- 3197 cumprod : equivalent function; see for details. 3198 )r r� rF rF rG r � r� r c O r� )z� 3199 Check whether some values are true. 3200 3201 Refer to `any` for full documentation. 3202 3203 See Also 3204 -------- 3205 any : equivalent function; see for details. 3206 )r r� rF rF rG r- � s r- c O r� )z� 3207 Check if all elements of input array are true. 3208 3209 See Also 3210 -------- 3211 numpy.all : Equivalent function; see for details. 3212 )r r� rF rF rG r � r� r )NNN)NNre r9 )rn )NN)Nre )re )r� r� N)r� NN)r� N)r r r )NNNNN)r r r NN)NNNNNN)r N)NNNN)p�__doc__� functools�typesr� r7 rL � r r> r r �umr r� r r r r 3213 r � sctype2char�_dt_�__all__� GeneratorTyper� r1 r� �partial�array_function_dispatchrH rK r] rc r3 rl r' rs r rw r& r{ r$ r� r2 r� r5 r� r r� r r� r. r� r rM r� r r� r r� r* r� r( r� r/ r� r r� r4 r� r% r� r r� r+ r� r r� r r� r� r r� r r� r r� r# r� r r� r r� r! r� r r� r r� r, r� r r� r r� r0 r� r6 r) r" r r- r rF rF rF rG �<module> sv 3214 � 3215 3216 c 3217 f 3218 | 3219 - ; 3220 3221 . 3222 E 3223 p 3224 Q 3225 n[ 3226 [ F 3227 3228 O 3229 E 3230 � 3231 ? j 3232 ^ 3233 3234 / 3235 ? G 3236 � 3237 � � ] � 3238 V 3239 L] 3240 � �x 3241 � �x 3242 � 3243 � 3244 | ? 3245 3246 % 3247 . ^ � �z� �� � �� 3248 3249 3250 3251 3252 3253 3254