Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.9/dist-packages/numpy/core/fromnumeric.py: 52%

1"""Module containing non-deprecated functions borrowed from Numeric.

3"""

4import functools

5import types

6import warnings

8import numpy as np

9from .._utils import set_module

10from . import multiarray as mu

11from . import overrides

12from . import umath as um

13from . import numerictypes as nt

14from .multiarray import asarray, array, asanyarray, concatenate

15from . import _methods

17_dt_ = nt.sctype2char

19# functions that are methods

20__all__ = [

21 'all', 'alltrue', 'amax', 'amin', 'any', 'argmax',

22 'argmin', 'argpartition', 'argsort', 'around', 'choose', 'clip',

23 'compress', 'cumprod', 'cumproduct', 'cumsum', 'diagonal', 'mean',

24 'max', 'min',

25 'ndim', 'nonzero', 'partition', 'prod', 'product', 'ptp', 'put',

26 'ravel', 'repeat', 'reshape', 'resize', 'round', 'round_',

27 'searchsorted', 'shape', 'size', 'sometrue', 'sort', 'squeeze',

28 'std', 'sum', 'swapaxes', 'take', 'trace', 'transpose', 'var',

29]

31_gentype = types.GeneratorType

32# save away Python sum

33_sum_ = sum

35array_function_dispatch = functools.partial(

36 overrides.array_function_dispatch, module='numpy')

39# functions that are now methods

40def _wrapit(obj, method, *args, **kwds):

41 try:

42 wrap = obj.__array_wrap__

43 except AttributeError:

44 wrap = None

45 result = getattr(asarray(obj), method)(*args, **kwds)

46 if wrap:

47 if not isinstance(result, mu.ndarray):

48 result = asarray(result)

49 result = wrap(result)

50 return result

53def _wrapfunc(obj, method, *args, **kwds):

54 bound = getattr(obj, method, None)

55 if bound is None:

56 return _wrapit(obj, method, *args, **kwds)

58 try:

59 return bound(*args, **kwds)

60 except TypeError:

61 # A TypeError occurs if the object does have such a method in its

62 # class, but its signature is not identical to that of NumPy's. This

63 # situation has occurred in the case of a downstream library like

64 # 'pandas'.

65 #

66 # Call _wrapit from within the except clause to ensure a potential

67 # exception has a traceback chain.

68 return _wrapit(obj, method, *args, **kwds)

71def _wrapreduction(obj, ufunc, method, axis, dtype, out, **kwargs):

72 passkwargs = {k: v for k, v in kwargs.items()

73 if v is not np._NoValue}

75 if type(obj) is not mu.ndarray:

76 try:

77 reduction = getattr(obj, method)

78 except AttributeError:

79 pass

80 else:

81 # This branch is needed for reductions like any which don't

82 # support a dtype.

83 if dtype is not None:

84 return reduction(axis=axis, dtype=dtype, out=out, **passkwargs)

85 else:

86 return reduction(axis=axis, out=out, **passkwargs)

88 return ufunc.reduce(obj, axis, dtype, out, **passkwargs)

91def _take_dispatcher(a, indices, axis=None, out=None, mode=None):

92 return (a, out)

95@array_function_dispatch(_take_dispatcher)

96def take(a, indices, axis=None, out=None, mode='raise'):

97 """

98 Take elements from an array along an axis.

100 When axis is not None, this function does the same thing as "fancy"

101 indexing (indexing arrays using arrays); however, it can be easier to use

102 if you need elements along a given axis. A call such as

103 ``np.take(arr, indices, axis=3)`` is equivalent to

104 ``arr[:,:,:,indices,...]``.

105

106 Explained without fancy indexing, this is equivalent to the following use

107 of `ndindex`, which sets each of ``ii``, ``jj``, and ``kk`` to a tuple of

108 indices::

109

110 Ni, Nk = a.shape[:axis], a.shape[axis+1:]

111 Nj = indices.shape

112 for ii in ndindex(Ni):

113 for jj in ndindex(Nj):

114 for kk in ndindex(Nk):

115 out[ii + jj + kk] = a[ii + (indices[jj],) + kk]

116

117 Parameters

118 ----------

119 a : array_like (Ni..., M, Nk...)

120 The source array.

121 indices : array_like (Nj...)

122 The indices of the values to extract.

123

124 .. versionadded:: 1.8.0

125

126 Also allow scalars for indices.

127 axis : int, optional

128 The axis over which to select values. By default, the flattened

129 input array is used.

130 out : ndarray, optional (Ni..., Nj..., Nk...)

131 If provided, the result will be placed in this array. It should

132 be of the appropriate shape and dtype. Note that `out` is always

133 buffered if `mode='raise'`; use other modes for better performance.

134 mode : {'raise', 'wrap', 'clip'}, optional

135 Specifies how out-of-bounds indices will behave.

136

137 * 'raise' -- raise an error (default)

138 * 'wrap' -- wrap around

139 * 'clip' -- clip to the range

140

141 'clip' mode means that all indices that are too large are replaced

142 by the index that addresses the last element along that axis. Note

143 that this disables indexing with negative numbers.

144

145 Returns

146 -------

147 out : ndarray (Ni..., Nj..., Nk...)

148 The returned array has the same type as `a`.

149

150 See Also

151 --------

152 compress : Take elements using a boolean mask

153 ndarray.take : equivalent method

154 take_along_axis : Take elements by matching the array and the index arrays

155

156 Notes

157 -----

158

159 By eliminating the inner loop in the description above, and using `s_` to

160 build simple slice objects, `take` can be expressed in terms of applying

161 fancy indexing to each 1-d slice::

162

163 Ni, Nk = a.shape[:axis], a.shape[axis+1:]

164 for ii in ndindex(Ni):

165 for kk in ndindex(Nj):

166 out[ii + s_[...,] + kk] = a[ii + s_[:,] + kk][indices]

167

168 For this reason, it is equivalent to (but faster than) the following use

169 of `apply_along_axis`::

170

171 out = np.apply_along_axis(lambda a_1d: a_1d[indices], axis, a)

172

173 Examples

174 --------

175 >>> a = [4, 3, 5, 7, 6, 8]

176 >>> indices = [0, 1, 4]

177 >>> np.take(a, indices)

178 array([4, 3, 6])

179

180 In this example if `a` is an ndarray, "fancy" indexing can be used.

181

182 >>> a = np.array(a)

183 >>> a[indices]

184 array([4, 3, 6])

185

186 If `indices` is not one dimensional, the output also has these dimensions.

187

188 >>> np.take(a, [[0, 1], [2, 3]])

189 array([[4, 3],

190 [5, 7]])

191 """

192 return _wrapfunc(a, 'take', indices, axis=axis, out=out, mode=mode)

193

194

195def _reshape_dispatcher(a, newshape, order=None):

196 return (a,)

197

198

199# not deprecated --- copy if necessary, view otherwise

200@array_function_dispatch(_reshape_dispatcher)

201def reshape(a, newshape, order='C'):

202 """

203 Gives a new shape to an array without changing its data.

204

205 Parameters

206 ----------

207 a : array_like

208 Array to be reshaped.

209 newshape : int or tuple of ints

210 The new shape should be compatible with the original shape. If

211 an integer, then the result will be a 1-D array of that length.

212 One shape dimension can be -1. In this case, the value is

213 inferred from the length of the array and remaining dimensions.

214 order : {'C', 'F', 'A'}, optional

215 Read the elements of `a` using this index order, and place the

216 elements into the reshaped array using this index order. 'C'

217 means to read / write the elements using C-like index order,

218 with the last axis index changing fastest, back to the first

219 axis index changing slowest. 'F' means to read / write the

220 elements using Fortran-like index order, with the first index

221 changing fastest, and the last index changing slowest. Note that

222 the 'C' and 'F' options take no account of the memory layout of

223 the underlying array, and only refer to the order of indexing.

224 'A' means to read / write the elements in Fortran-like index

225 order if `a` is Fortran *contiguous* in memory, C-like order

226 otherwise.

227

228 Returns

229 -------

230 reshaped_array : ndarray

231 This will be a new view object if possible; otherwise, it will

232 be a copy. Note there is no guarantee of the *memory layout* (C- or

233 Fortran- contiguous) of the returned array.

234

235 See Also

236 --------

237 ndarray.reshape : Equivalent method.

238

239 Notes

240 -----

241 It is not always possible to change the shape of an array without copying

242 the data.

243

244 The `order` keyword gives the index ordering both for *fetching* the values

245 from `a`, and then *placing* the values into the output array.

246 For example, let's say you have an array:

247

248 >>> a = np.arange(6).reshape((3, 2))

249 >>> a

250 array([[0, 1],

251 [2, 3],

252 [4, 5]])

253

254 You can think of reshaping as first raveling the array (using the given

255 index order), then inserting the elements from the raveled array into the

256 new array using the same kind of index ordering as was used for the

257 raveling.

258

259 >>> np.reshape(a, (2, 3)) # C-like index ordering

260 array([[0, 1, 2],

261 [3, 4, 5]])

262 >>> np.reshape(np.ravel(a), (2, 3)) # equivalent to C ravel then C reshape

263 array([[0, 1, 2],

264 [3, 4, 5]])

265 >>> np.reshape(a, (2, 3), order='F') # Fortran-like index ordering

266 array([[0, 4, 3],

267 [2, 1, 5]])

268 >>> np.reshape(np.ravel(a, order='F'), (2, 3), order='F')

269 array([[0, 4, 3],

270 [2, 1, 5]])

271

272 Examples

273 --------

274 >>> a = np.array([[1,2,3], [4,5,6]])

275 >>> np.reshape(a, 6)

276 array([1, 2, 3, 4, 5, 6])

277 >>> np.reshape(a, 6, order='F')

278 array([1, 4, 2, 5, 3, 6])

279

280 >>> np.reshape(a, (3,-1)) # the unspecified value is inferred to be 2

281 array([[1, 2],

282 [3, 4],

283 [5, 6]])

284 """

285 return _wrapfunc(a, 'reshape', newshape, order=order)

286

287

288def _choose_dispatcher(a, choices, out=None, mode=None):

289 yield a

290 yield from choices

291 yield out

292

293

294@array_function_dispatch(_choose_dispatcher)

295def choose(a, choices, out=None, mode='raise'):

296 """

297 Construct an array from an index array and a list of arrays to choose from.

298

299 First of all, if confused or uncertain, definitely look at the Examples -

300 in its full generality, this function is less simple than it might

301 seem from the following code description (below ndi =

302 `numpy.lib.index_tricks`):

303

304 ``np.choose(a,c) == np.array([c[a[I]][I] for I in ndi.ndindex(a.shape)])``.

305

306 But this omits some subtleties. Here is a fully general summary:

307

308 Given an "index" array (`a`) of integers and a sequence of ``n`` arrays

309 (`choices`), `a` and each choice array are first broadcast, as necessary,

310 to arrays of a common shape; calling these *Ba* and *Bchoices[i], i =

311 0,...,n-1* we have that, necessarily, ``Ba.shape == Bchoices[i].shape``

312 for each ``i``. Then, a new array with shape ``Ba.shape`` is created as

313 follows:

314

315 * if ``mode='raise'`` (the default), then, first of all, each element of

316 ``a`` (and thus ``Ba``) must be in the range ``[0, n-1]``; now, suppose

317 that ``i`` (in that range) is the value at the ``(j0, j1, ..., jm)``

318 position in ``Ba`` - then the value at the same position in the new array

319 is the value in ``Bchoices[i]`` at that same position;

320

321 * if ``mode='wrap'``, values in `a` (and thus `Ba`) may be any (signed)

322 integer; modular arithmetic is used to map integers outside the range

323 `[0, n-1]` back into that range; and then the new array is constructed

324 as above;

325

326 * if ``mode='clip'``, values in `a` (and thus ``Ba``) may be any (signed)

327 integer; negative integers are mapped to 0; values greater than ``n-1``

328 are mapped to ``n-1``; and then the new array is constructed as above.

329

330 Parameters

331 ----------

332 a : int array

333 This array must contain integers in ``[0, n-1]``, where ``n`` is the

334 number of choices, unless ``mode=wrap`` or ``mode=clip``, in which

335 cases any integers are permissible.

336 choices : sequence of arrays

337 Choice arrays. `a` and all of the choices must be broadcastable to the

338 same shape. If `choices` is itself an array (not recommended), then

339 its outermost dimension (i.e., the one corresponding to

340 ``choices.shape[0]``) is taken as defining the "sequence".

341 out : array, optional

342 If provided, the result will be inserted into this array. It should

343 be of the appropriate shape and dtype. Note that `out` is always

344 buffered if ``mode='raise'``; use other modes for better performance.

345 mode : {'raise' (default), 'wrap', 'clip'}, optional

346 Specifies how indices outside ``[0, n-1]`` will be treated:

347

348 * 'raise' : an exception is raised

349 * 'wrap' : value becomes value mod ``n``

350 * 'clip' : values < 0 are mapped to 0, values > n-1 are mapped to n-1

351

352 Returns

353 -------

354 merged_array : array

355 The merged result.

356

357 Raises

358 ------

359 ValueError: shape mismatch

360 If `a` and each choice array are not all broadcastable to the same

361 shape.

362

363 See Also

364 --------

365 ndarray.choose : equivalent method

366 numpy.take_along_axis : Preferable if `choices` is an array

367

368 Notes

369 -----

370 To reduce the chance of misinterpretation, even though the following

371 "abuse" is nominally supported, `choices` should neither be, nor be

372 thought of as, a single array, i.e., the outermost sequence-like container

373 should be either a list or a tuple.

374

375 Examples

376 --------

377

378 >>> choices = [[0, 1, 2, 3], [10, 11, 12, 13],

379 ... [20, 21, 22, 23], [30, 31, 32, 33]]

380 >>> np.choose([2, 3, 1, 0], choices

381 ... # the first element of the result will be the first element of the

382 ... # third (2+1) "array" in choices, namely, 20; the second element

383 ... # will be the second element of the fourth (3+1) choice array, i.e.,

384 ... # 31, etc.

385 ... )

386 array([20, 31, 12, 3])

387 >>> np.choose([2, 4, 1, 0], choices, mode='clip') # 4 goes to 3 (4-1)

388 array([20, 31, 12, 3])

389 >>> # because there are 4 choice arrays

390 >>> np.choose([2, 4, 1, 0], choices, mode='wrap') # 4 goes to (4 mod 4)

391 array([20, 1, 12, 3])

392 >>> # i.e., 0

393

394 A couple examples illustrating how choose broadcasts:

395

396 >>> a = [[1, 0, 1], [0, 1, 0], [1, 0, 1]]

397 >>> choices = [-10, 10]

398 >>> np.choose(a, choices)

399 array([[ 10, -10, 10],

400 [-10, 10, -10],

401 [ 10, -10, 10]])

402

403 >>> # With thanks to Anne Archibald

404 >>> a = np.array([0, 1]).reshape((2,1,1))

405 >>> c1 = np.array([1, 2, 3]).reshape((1,3,1))

406 >>> c2 = np.array([-1, -2, -3, -4, -5]).reshape((1,1,5))

407 >>> np.choose(a, (c1, c2)) # result is 2x3x5, res[0,:,:]=c1, res[1,:,:]=c2

408 array([[[ 1, 1, 1, 1, 1],

409 [ 2, 2, 2, 2, 2],

410 [ 3, 3, 3, 3, 3]],

411 [[-1, -2, -3, -4, -5],

412 [-1, -2, -3, -4, -5],

413 [-1, -2, -3, -4, -5]]])

414

415 """

416 return _wrapfunc(a, 'choose', choices, out=out, mode=mode)

417

418

419def _repeat_dispatcher(a, repeats, axis=None):

420 return (a,)

421

422

423@array_function_dispatch(_repeat_dispatcher)

424def repeat(a, repeats, axis=None):

425 """

426 Repeat each element of an array after themselves

427

428 Parameters

429 ----------

430 a : array_like

431 Input array.

432 repeats : int or array of ints

433 The number of repetitions for each element. `repeats` is broadcasted

434 to fit the shape of the given axis.

435 axis : int, optional

436 The axis along which to repeat values. By default, use the

437 flattened input array, and return a flat output array.

438

439 Returns

440 -------

441 repeated_array : ndarray

442 Output array which has the same shape as `a`, except along

443 the given axis.

444

445 See Also

446 --------

447 tile : Tile an array.

448 unique : Find the unique elements of an array.

449

450 Examples

451 --------

452 >>> np.repeat(3, 4)

453 array([3, 3, 3, 3])

454 >>> x = np.array([[1,2],[3,4]])

455 >>> np.repeat(x, 2)

456 array([1, 1, 2, 2, 3, 3, 4, 4])

457 >>> np.repeat(x, 3, axis=1)

458 array([[1, 1, 1, 2, 2, 2],

459 [3, 3, 3, 4, 4, 4]])

460 >>> np.repeat(x, [1, 2], axis=0)

461 array([[1, 2],

462 [3, 4],

463 [3, 4]])

464

465 """

466 return _wrapfunc(a, 'repeat', repeats, axis=axis)

467

468

469def _put_dispatcher(a, ind, v, mode=None):

470 return (a, ind, v)

471

472

473@array_function_dispatch(_put_dispatcher)

474def put(a, ind, v, mode='raise'):

475 """

476 Replaces specified elements of an array with given values.

477

478 The indexing works on the flattened target array. `put` is roughly

479 equivalent to:

480

481 ::

482

483 a.flat[ind] = v

484

485 Parameters

486 ----------

487 a : ndarray

488 Target array.

489 ind : array_like

490 Target indices, interpreted as integers.

491 v : array_like

492 Values to place in `a` at target indices. If `v` is shorter than

493 `ind` it will be repeated as necessary.

494 mode : {'raise', 'wrap', 'clip'}, optional

495 Specifies how out-of-bounds indices will behave.

496

497 * 'raise' -- raise an error (default)

498 * 'wrap' -- wrap around

499 * 'clip' -- clip to the range

500

501 'clip' mode means that all indices that are too large are replaced

502 by the index that addresses the last element along that axis. Note

503 that this disables indexing with negative numbers. In 'raise' mode,

504 if an exception occurs the target array may still be modified.

505

506 See Also

507 --------

508 putmask, place

509 put_along_axis : Put elements by matching the array and the index arrays

510

511 Examples

512 --------

513 >>> a = np.arange(5)

514 >>> np.put(a, [0, 2], [-44, -55])

515 >>> a

516 array([-44, 1, -55, 3, 4])

517

518 >>> a = np.arange(5)

519 >>> np.put(a, 22, -5, mode='clip')

520 >>> a

521 array([ 0, 1, 2, 3, -5])

522

523 """

524 try:

525 put = a.put

526 except AttributeError as e:

527 raise TypeError("argument 1 must be numpy.ndarray, "

528 "not {name}".format(name=type(a).__name__)) from e

529

530 return put(ind, v, mode=mode)

531

532

533def _swapaxes_dispatcher(a, axis1, axis2):

534 return (a,)

535

536

537@array_function_dispatch(_swapaxes_dispatcher)

538def swapaxes(a, axis1, axis2):

539 """

540 Interchange two axes of an array.

541

542 Parameters

543 ----------

544 a : array_like

545 Input array.

546 axis1 : int

547 First axis.

548 axis2 : int

549 Second axis.

550

551 Returns

552 -------

553 a_swapped : ndarray

554 For NumPy >= 1.10.0, if `a` is an ndarray, then a view of `a` is

555 returned; otherwise a new array is created. For earlier NumPy

556 versions a view of `a` is returned only if the order of the

557 axes is changed, otherwise the input array is returned.

558

559 Examples

560 --------

561 >>> x = np.array([[1,2,3]])

562 >>> np.swapaxes(x,0,1)

563 array([[1],

564 [2],

565 [3]])

566

567 >>> x = np.array([[[0,1],[2,3]],[[4,5],[6,7]]])

568 >>> x

569 array([[[0, 1],

570 [2, 3]],

571 [[4, 5],

572 [6, 7]]])

573

574 >>> np.swapaxes(x,0,2)

575 array([[[0, 4],

576 [2, 6]],

577 [[1, 5],

578 [3, 7]]])

579

580 """

581 return _wrapfunc(a, 'swapaxes', axis1, axis2)

582

583

584def _transpose_dispatcher(a, axes=None):

585 return (a,)

586

587

588@array_function_dispatch(_transpose_dispatcher)

589def transpose(a, axes=None):

590 """

591 Returns an array with axes transposed.

592

593 For a 1-D array, this returns an unchanged view of the original array, as a

594 transposed vector is simply the same vector.

595 To convert a 1-D array into a 2-D column vector, an additional dimension

596 must be added, e.g., ``np.atleast2d(a).T`` achieves this, as does

597 ``a[:, np.newaxis]``.

598 For a 2-D array, this is the standard matrix transpose.

599 For an n-D array, if axes are given, their order indicates how the

600 axes are permuted (see Examples). If axes are not provided, then

601 ``transpose(a).shape == a.shape[::-1]``.

602

603 Parameters

604 ----------

605 a : array_like

606 Input array.

607 axes : tuple or list of ints, optional

608 If specified, it must be a tuple or list which contains a permutation

609 of [0,1,...,N-1] where N is the number of axes of `a`. The `i`'th axis

610 of the returned array will correspond to the axis numbered ``axes[i]``

611 of the input. If not specified, defaults to ``range(a.ndim)[::-1]``,

612 which reverses the order of the axes.

613

614 Returns

615 -------

616 p : ndarray

617 `a` with its axes permuted. A view is returned whenever possible.

618

619 See Also

620 --------

621 ndarray.transpose : Equivalent method.

622 moveaxis : Move axes of an array to new positions.

623 argsort : Return the indices that would sort an array.

624

625 Notes

626 -----

627 Use ``transpose(a, argsort(axes))`` to invert the transposition of tensors

628 when using the `axes` keyword argument.

629

630 Examples

631 --------

632 >>> a = np.array([[1, 2], [3, 4]])

633 >>> a

634 array([[1, 2],

635 [3, 4]])

636 >>> np.transpose(a)

637 array([[1, 3],

638 [2, 4]])

639

640 >>> a = np.array([1, 2, 3, 4])

641 >>> a

642 array([1, 2, 3, 4])

643 >>> np.transpose(a)

644 array([1, 2, 3, 4])

645

646 >>> a = np.ones((1, 2, 3))

647 >>> np.transpose(a, (1, 0, 2)).shape

648 (2, 1, 3)

649

650 >>> a = np.ones((2, 3, 4, 5))

651 >>> np.transpose(a).shape

652 (5, 4, 3, 2)

653

654 """

655 return _wrapfunc(a, 'transpose', axes)

656

657

658def _partition_dispatcher(a, kth, axis=None, kind=None, order=None):

659 return (a,)

660

661

662@array_function_dispatch(_partition_dispatcher)

663def partition(a, kth, axis=-1, kind='introselect', order=None):

664 """

665 Return a partitioned copy of an array.

666

667 Creates a copy of the array with its elements rearranged in such a

668 way that the value of the element in k-th position is in the position

669 the value would be in a sorted array. In the partitioned array, all

670 elements before the k-th element are less than or equal to that

671 element, and all the elements after the k-th element are greater than

672 or equal to that element. The ordering of the elements in the two

673 partitions is undefined.

674

675 .. versionadded:: 1.8.0

676

677 Parameters

678 ----------

679 a : array_like

680 Array to be sorted.

681 kth : int or sequence of ints

682 Element index to partition by. The k-th value of the element

683 will be in its final sorted position and all smaller elements

684 will be moved before it and all equal or greater elements behind

685 it. The order of all elements in the partitions is undefined. If

686 provided with a sequence of k-th it will partition all elements

687 indexed by k-th of them into their sorted position at once.

688

689 .. deprecated:: 1.22.0

690 Passing booleans as index is deprecated.

691 axis : int or None, optional

692 Axis along which to sort. If None, the array is flattened before

693 sorting. The default is -1, which sorts along the last axis.

694 kind : {'introselect'}, optional

695 Selection algorithm. Default is 'introselect'.

696 order : str or list of str, optional

697 When `a` is an array with fields defined, this argument

698 specifies which fields to compare first, second, etc. A single

699 field can be specified as a string. Not all fields need be

700 specified, but unspecified fields will still be used, in the

701 order in which they come up in the dtype, to break ties.

702

703 Returns

704 -------

705 partitioned_array : ndarray

706 Array of the same type and shape as `a`.

707

708 See Also

709 --------

710 ndarray.partition : Method to sort an array in-place.

711 argpartition : Indirect partition.

712 sort : Full sorting

713

714 Notes

715 -----

716 The various selection algorithms are characterized by their average

717 speed, worst case performance, work space size, and whether they are

718 stable. A stable sort keeps items with the same key in the same

719 relative order. The available algorithms have the following

720 properties:

721

722 ================= ======= ============= ============ =======

723 kind speed worst case work space stable

724 ================= ======= ============= ============ =======

725 'introselect' 1 O(n) 0 no

726 ================= ======= ============= ============ =======

727

728 All the partition algorithms make temporary copies of the data when

729 partitioning along any but the last axis. Consequently,

730 partitioning along the last axis is faster and uses less space than

731 partitioning along any other axis.

732

733 The sort order for complex numbers is lexicographic. If both the

734 real and imaginary parts are non-nan then the order is determined by

735 the real parts except when they are equal, in which case the order

736 is determined by the imaginary parts.

737

738 Examples

739 --------

740 >>> a = np.array([7, 1, 7, 7, 1, 5, 7, 2, 3, 2, 6, 2, 3, 0])

741 >>> p = np.partition(a, 4)

742 >>> p

743 array([0, 1, 2, 1, 2, 5, 2, 3, 3, 6, 7, 7, 7, 7])

744

745 ``p[4]`` is 2; all elements in ``p[:4]`` are less than or equal

746 to ``p[4]``, and all elements in ``p[5:]`` are greater than or

747 equal to ``p[4]``. The partition is::

748

749 [0, 1, 2, 1], [2], [5, 2, 3, 3, 6, 7, 7, 7, 7]

750

751 The next example shows the use of multiple values passed to `kth`.

752

753 >>> p2 = np.partition(a, (4, 8))

754 >>> p2

755 array([0, 1, 2, 1, 2, 3, 3, 2, 5, 6, 7, 7, 7, 7])

756

757 ``p2[4]`` is 2 and ``p2[8]`` is 5. All elements in ``p2[:4]``

758 are less than or equal to ``p2[4]``, all elements in ``p2[5:8]``

759 are greater than or equal to ``p2[4]`` and less than or equal to

760 ``p2[8]``, and all elements in ``p2[9:]`` are greater than or

761 equal to ``p2[8]``. The partition is::

762

763 [0, 1, 2, 1], [2], [3, 3, 2], [5], [6, 7, 7, 7, 7]

764 """

765 if axis is None:

766 # flatten returns (1, N) for np.matrix, so always use the last axis

767 a = asanyarray(a).flatten()

768 axis = -1

769 else:

770 a = asanyarray(a).copy(order="K")

771 a.partition(kth, axis=axis, kind=kind, order=order)

772 return a

773

774

775def _argpartition_dispatcher(a, kth, axis=None, kind=None, order=None):

776 return (a,)

777

778

779@array_function_dispatch(_argpartition_dispatcher)

780def argpartition(a, kth, axis=-1, kind='introselect', order=None):

781 """

782 Perform an indirect partition along the given axis using the

783 algorithm specified by the `kind` keyword. It returns an array of

784 indices of the same shape as `a` that index data along the given

785 axis in partitioned order.

786

787 .. versionadded:: 1.8.0

788

789 Parameters

790 ----------

791 a : array_like

792 Array to sort.

793 kth : int or sequence of ints

794 Element index to partition by. The k-th element will be in its

795 final sorted position and all smaller elements will be moved

796 before it and all larger elements behind it. The order of all

797 elements in the partitions is undefined. If provided with a

798 sequence of k-th it will partition all of them into their sorted

799 position at once.

800

801 .. deprecated:: 1.22.0

802 Passing booleans as index is deprecated.

803 axis : int or None, optional

804 Axis along which to sort. The default is -1 (the last axis). If

805 None, the flattened array is used.

806 kind : {'introselect'}, optional

807 Selection algorithm. Default is 'introselect'

808 order : str or list of str, optional

809 When `a` is an array with fields defined, this argument

810 specifies which fields to compare first, second, etc. A single

811 field can be specified as a string, and not all fields need be

812 specified, but unspecified fields will still be used, in the

813 order in which they come up in the dtype, to break ties.

814

815 Returns

816 -------

817 index_array : ndarray, int

818 Array of indices that partition `a` along the specified axis.

819 If `a` is one-dimensional, ``a[index_array]`` yields a partitioned `a`.

820 More generally, ``np.take_along_axis(a, index_array, axis=axis)``

821 always yields the partitioned `a`, irrespective of dimensionality.

822

823 See Also

824 --------

825 partition : Describes partition algorithms used.

826 ndarray.partition : Inplace partition.

827 argsort : Full indirect sort.

828 take_along_axis : Apply ``index_array`` from argpartition

829 to an array as if by calling partition.

830

831 Notes

832 -----

833 See `partition` for notes on the different selection algorithms.

834

835 Examples

836 --------

837 One dimensional array:

838

839 >>> x = np.array([3, 4, 2, 1])

840 >>> x[np.argpartition(x, 3)]

841 array([2, 1, 3, 4])

842 >>> x[np.argpartition(x, (1, 3))]

843 array([1, 2, 3, 4])

844

845 >>> x = [3, 4, 2, 1]

846 >>> np.array(x)[np.argpartition(x, 3)]

847 array([2, 1, 3, 4])

848

849 Multi-dimensional array:

850

851 >>> x = np.array([[3, 4, 2], [1, 3, 1]])

852 >>> index_array = np.argpartition(x, kth=1, axis=-1)

853 >>> np.take_along_axis(x, index_array, axis=-1) # same as np.partition(x, kth=1)

854 array([[2, 3, 4],

855 [1, 1, 3]])

856

857 """

858 return _wrapfunc(a, 'argpartition', kth, axis=axis, kind=kind, order=order)

859

860

861def _sort_dispatcher(a, axis=None, kind=None, order=None):

862 return (a,)

863

864

865@array_function_dispatch(_sort_dispatcher)

866def sort(a, axis=-1, kind=None, order=None):

867 """

868 Return a sorted copy of an array.

869

870 Parameters

871 ----------

872 a : array_like

873 Array to be sorted.

874 axis : int or None, optional

875 Axis along which to sort. If None, the array is flattened before

876 sorting. The default is -1, which sorts along the last axis.

877 kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, optional

878 Sorting algorithm. The default is 'quicksort'. Note that both 'stable'

879 and 'mergesort' use timsort or radix sort under the covers and, in general,

880 the actual implementation will vary with data type. The 'mergesort' option

881 is retained for backwards compatibility.

882

883 .. versionchanged:: 1.15.0.

884 The 'stable' option was added.

885

886 order : str or list of str, optional

887 When `a` is an array with fields defined, this argument specifies

888 which fields to compare first, second, etc. A single field can

889 be specified as a string, and not all fields need be specified,

890 but unspecified fields will still be used, in the order in which

891 they come up in the dtype, to break ties.

892

893 Returns

894 -------

895 sorted_array : ndarray

896 Array of the same type and shape as `a`.

897

898 See Also

899 --------

900 ndarray.sort : Method to sort an array in-place.

901 argsort : Indirect sort.

902 lexsort : Indirect stable sort on multiple keys.

903 searchsorted : Find elements in a sorted array.

904 partition : Partial sort.

905

906 Notes

907 -----

908 The various sorting algorithms are characterized by their average speed,

909 worst case performance, work space size, and whether they are stable. A

910 stable sort keeps items with the same key in the same relative

911 order. The four algorithms implemented in NumPy have the following

912 properties:

913

914 =========== ======= ============= ============ ========

915 kind speed worst case work space stable

916 =========== ======= ============= ============ ========

917 'quicksort' 1 O(n^2) 0 no

918 'heapsort' 3 O(n*log(n)) 0 no

919 'mergesort' 2 O(n*log(n)) ~n/2 yes

920 'timsort' 2 O(n*log(n)) ~n/2 yes

921 =========== ======= ============= ============ ========

922

923 .. note:: The datatype determines which of 'mergesort' or 'timsort'

924 is actually used, even if 'mergesort' is specified. User selection

925 at a finer scale is not currently available.

926

927 All the sort algorithms make temporary copies of the data when

928 sorting along any but the last axis. Consequently, sorting along

929 the last axis is faster and uses less space than sorting along

930 any other axis.

931

932 The sort order for complex numbers is lexicographic. If both the real

933 and imaginary parts are non-nan then the order is determined by the

934 real parts except when they are equal, in which case the order is

935 determined by the imaginary parts.

936

937 Previous to numpy 1.4.0 sorting real and complex arrays containing nan

938 values led to undefined behaviour. In numpy versions >= 1.4.0 nan

939 values are sorted to the end. The extended sort order is:

940

941 * Real: [R, nan]

942 * Complex: [R + Rj, R + nanj, nan + Rj, nan + nanj]

943

944 where R is a non-nan real value. Complex values with the same nan

945 placements are sorted according to the non-nan part if it exists.

946 Non-nan values are sorted as before.

947

948 .. versionadded:: 1.12.0

949

950 quicksort has been changed to `introsort <https://en.wikipedia.org/wiki/Introsort>`_.

951 When sorting does not make enough progress it switches to

952 `heapsort <https://en.wikipedia.org/wiki/Heapsort>`_.

953 This implementation makes quicksort O(n*log(n)) in the worst case.

954

955 'stable' automatically chooses the best stable sorting algorithm

956 for the data type being sorted.

957 It, along with 'mergesort' is currently mapped to

958 `timsort <https://en.wikipedia.org/wiki/Timsort>`_

959 or `radix sort <https://en.wikipedia.org/wiki/Radix_sort>`_

960 depending on the data type.

961 API forward compatibility currently limits the

962 ability to select the implementation and it is hardwired for the different

963 data types.

964

965 .. versionadded:: 1.17.0

966

967 Timsort is added for better performance on already or nearly

968 sorted data. On random data timsort is almost identical to

969 mergesort. It is now used for stable sort while quicksort is still the

970 default sort if none is chosen. For timsort details, refer to

971 `CPython listsort.txt <https://github.com/python/cpython/blob/3.7/Objects/listsort.txt>`_.

972 'mergesort' and 'stable' are mapped to radix sort for integer data types. Radix sort is an

973 O(n) sort instead of O(n log n).

974

975 .. versionchanged:: 1.18.0

976

977 NaT now sorts to the end of arrays for consistency with NaN.

978

979 Examples

980 --------

981 >>> a = np.array([[1,4],[3,1]])

982 >>> np.sort(a) # sort along the last axis

983 array([[1, 4],

984 [1, 3]])

985 >>> np.sort(a, axis=None) # sort the flattened array

986 array([1, 1, 3, 4])

987 >>> np.sort(a, axis=0) # sort along the first axis

988 array([[1, 1],

989 [3, 4]])

990

991 Use the `order` keyword to specify a field to use when sorting a

992 structured array:

993

994 >>> dtype = [('name', 'S10'), ('height', float), ('age', int)]

995 >>> values = [('Arthur', 1.8, 41), ('Lancelot', 1.9, 38),

996 ... ('Galahad', 1.7, 38)]

997 >>> a = np.array(values, dtype=dtype) # create a structured array

998 >>> np.sort(a, order='height') # doctest: +SKIP

999 array([('Galahad', 1.7, 38), ('Arthur', 1.8, 41),

1000 ('Lancelot', 1.8999999999999999, 38)],

1001 dtype=[('name', '|S10'), ('height', '<f8'), ('age', '<i4')])

1002

1003 Sort by age, then height if ages are equal:

1004

1005 >>> np.sort(a, order=['age', 'height']) # doctest: +SKIP

1006 array([('Galahad', 1.7, 38), ('Lancelot', 1.8999999999999999, 38),

1007 ('Arthur', 1.8, 41)],

1008 dtype=[('name', '|S10'), ('height', '<f8'), ('age', '<i4')])

1009

1010 """

1011 if axis is None:

1012 # flatten returns (1, N) for np.matrix, so always use the last axis

1013 a = asanyarray(a).flatten()

1014 axis = -1

1015 else:

1016 a = asanyarray(a).copy(order="K")

1017 a.sort(axis=axis, kind=kind, order=order)

1018 return a

1019

1020

1021def _argsort_dispatcher(a, axis=None, kind=None, order=None):

1022 return (a,)

1023

1024

1025@array_function_dispatch(_argsort_dispatcher)

1026def argsort(a, axis=-1, kind=None, order=None):

1027 """

1028 Returns the indices that would sort an array.

1029

1030 Perform an indirect sort along the given axis using the algorithm specified

1031 by the `kind` keyword. It returns an array of indices of the same shape as

1032 `a` that index data along the given axis in sorted order.

1033

1034 Parameters

1035 ----------

1036 a : array_like

1037 Array to sort.

1038 axis : int or None, optional

1039 Axis along which to sort. The default is -1 (the last axis). If None,

1040 the flattened array is used.

1041 kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, optional

1042 Sorting algorithm. The default is 'quicksort'. Note that both 'stable'

1043 and 'mergesort' use timsort under the covers and, in general, the

1044 actual implementation will vary with data type. The 'mergesort' option

1045 is retained for backwards compatibility.

1046

1047 .. versionchanged:: 1.15.0.

1048 The 'stable' option was added.

1049 order : str or list of str, optional

1050 When `a` is an array with fields defined, this argument specifies

1051 which fields to compare first, second, etc. A single field can

1052 be specified as a string, and not all fields need be specified,

1053 but unspecified fields will still be used, in the order in which

1054 they come up in the dtype, to break ties.

1055

1056 Returns

1057 -------

1058 index_array : ndarray, int

1059 Array of indices that sort `a` along the specified `axis`.

1060 If `a` is one-dimensional, ``a[index_array]`` yields a sorted `a`.

1061 More generally, ``np.take_along_axis(a, index_array, axis=axis)``

1062 always yields the sorted `a`, irrespective of dimensionality.

1063

1064 See Also

1065 --------

1066 sort : Describes sorting algorithms used.

1067 lexsort : Indirect stable sort with multiple keys.

1068 ndarray.sort : Inplace sort.

1069 argpartition : Indirect partial sort.

1070 take_along_axis : Apply ``index_array`` from argsort

1071 to an array as if by calling sort.

1072

1073 Notes

1074 -----

1075 See `sort` for notes on the different sorting algorithms.

1076

1077 As of NumPy 1.4.0 `argsort` works with real/complex arrays containing

1078 nan values. The enhanced sort order is documented in `sort`.

1079

1080 Examples

1081 --------

1082 One dimensional array:

1083

1084 >>> x = np.array([3, 1, 2])

1085 >>> np.argsort(x)

1086 array([1, 2, 0])

1087

1088 Two-dimensional array:

1089

1090 >>> x = np.array([[0, 3], [2, 2]])

1091 >>> x

1092 array([[0, 3],

1093 [2, 2]])

1094

1095 >>> ind = np.argsort(x, axis=0) # sorts along first axis (down)

1096 >>> ind

1097 array([[0, 1],

1098 [1, 0]])

1099 >>> np.take_along_axis(x, ind, axis=0) # same as np.sort(x, axis=0)

1100 array([[0, 2],

1101 [2, 3]])

1102

1103 >>> ind = np.argsort(x, axis=1) # sorts along last axis (across)

1104 >>> ind

1105 array([[0, 1],

1106 [0, 1]])

1107 >>> np.take_along_axis(x, ind, axis=1) # same as np.sort(x, axis=1)

1108 array([[0, 3],

1109 [2, 2]])

1110

1111 Indices of the sorted elements of a N-dimensional array:

1112

1113 >>> ind = np.unravel_index(np.argsort(x, axis=None), x.shape)

1114 >>> ind

1115 (array([0, 1, 1, 0]), array([0, 0, 1, 1]))

1116 >>> x[ind] # same as np.sort(x, axis=None)

1117 array([0, 2, 2, 3])

1118

1119 Sorting with keys:

1120

1121 >>> x = np.array([(1, 0), (0, 1)], dtype=[('x', '<i4'), ('y', '<i4')])

1122 >>> x

1123 array([(1, 0), (0, 1)],

1124 dtype=[('x', '<i4'), ('y', '<i4')])

1125

1126 >>> np.argsort(x, order=('x','y'))

1127 array([1, 0])

1128

1129 >>> np.argsort(x, order=('y','x'))

1130 array([0, 1])

1131

1132 """

1133 return _wrapfunc(a, 'argsort', axis=axis, kind=kind, order=order)

1134

1135

1136def _argmax_dispatcher(a, axis=None, out=None, *, keepdims=np._NoValue):

1137 return (a, out)

1138

1139

1140@array_function_dispatch(_argmax_dispatcher)

1141def argmax(a, axis=None, out=None, *, keepdims=np._NoValue):

1142 """

1143 Returns the indices of the maximum values along an axis.

1144

1145 Parameters

1146 ----------

1147 a : array_like

1148 Input array.

1149 axis : int, optional

1150 By default, the index is into the flattened array, otherwise

1151 along the specified axis.

1152 out : array, optional

1153 If provided, the result will be inserted into this array. It should

1154 be of the appropriate shape and dtype.

1155 keepdims : bool, optional

1156 If this is set to True, the axes which are reduced are left

1157 in the result as dimensions with size one. With this option,

1158 the result will broadcast correctly against the array.

1159

1160 .. versionadded:: 1.22.0

1161

1162 Returns

1163 -------

1164 index_array : ndarray of ints

1165 Array of indices into the array. It has the same shape as `a.shape`

1166 with the dimension along `axis` removed. If `keepdims` is set to True,

1167 then the size of `axis` will be 1 with the resulting array having same

1168 shape as `a.shape`.

1169

1170 See Also

1171 --------

1172 ndarray.argmax, argmin

1173 amax : The maximum value along a given axis.

1174 unravel_index : Convert a flat index into an index tuple.

1175 take_along_axis : Apply ``np.expand_dims(index_array, axis)``

1176 from argmax to an array as if by calling max.

1177

1178 Notes

1179 -----

1180 In case of multiple occurrences of the maximum values, the indices

1181 corresponding to the first occurrence are returned.

1182

1183 Examples

1184 --------

1185 >>> a = np.arange(6).reshape(2,3) + 10

1186 >>> a

1187 array([[10, 11, 12],

1188 [13, 14, 15]])

1189 >>> np.argmax(a)

1190 5

1191 >>> np.argmax(a, axis=0)

1192 array([1, 1, 1])

1193 >>> np.argmax(a, axis=1)

1194 array([2, 2])

1195

1196 Indexes of the maximal elements of a N-dimensional array:

1197

1198 >>> ind = np.unravel_index(np.argmax(a, axis=None), a.shape)

1199 >>> ind

1200 (1, 2)

1201 >>> a[ind]

1202 15

1203

1204 >>> b = np.arange(6)

1205 >>> b[1] = 5

1206 >>> b

1207 array([0, 5, 2, 3, 4, 5])

1208 >>> np.argmax(b) # Only the first occurrence is returned.

1209 1

1210

1211 >>> x = np.array([[4,2,3], [1,0,3]])

1212 >>> index_array = np.argmax(x, axis=-1)

1213 >>> # Same as np.amax(x, axis=-1, keepdims=True)

1214 >>> np.take_along_axis(x, np.expand_dims(index_array, axis=-1), axis=-1)

1215 array([[4],

1216 [3]])

1217 >>> # Same as np.amax(x, axis=-1)

1218 >>> np.take_along_axis(x, np.expand_dims(index_array, axis=-1), axis=-1).squeeze(axis=-1)

1219 array([4, 3])

1220

1221 Setting `keepdims` to `True`,

1222

1223 >>> x = np.arange(24).reshape((2, 3, 4))

1224 >>> res = np.argmax(x, axis=1, keepdims=True)

1225 >>> res.shape

1226 (2, 1, 4)

1227 """

1228 kwds = {'keepdims': keepdims} if keepdims is not np._NoValue else {}

1229 return _wrapfunc(a, 'argmax', axis=axis, out=out, **kwds)

1230

1231

1232def _argmin_dispatcher(a, axis=None, out=None, *, keepdims=np._NoValue):

1233 return (a, out)

1234

1235

1236@array_function_dispatch(_argmin_dispatcher)

1237def argmin(a, axis=None, out=None, *, keepdims=np._NoValue):

1238 """

1239 Returns the indices of the minimum values along an axis.

1240

1241 Parameters

1242 ----------

1243 a : array_like

1244 Input array.

1245 axis : int, optional

1246 By default, the index is into the flattened array, otherwise

1247 along the specified axis.

1248 out : array, optional

1249 If provided, the result will be inserted into this array. It should

1250 be of the appropriate shape and dtype.

1251 keepdims : bool, optional

1252 If this is set to True, the axes which are reduced are left

1253 in the result as dimensions with size one. With this option,

1254 the result will broadcast correctly against the array.

1255

1256 .. versionadded:: 1.22.0

1257

1258 Returns

1259 -------

1260 index_array : ndarray of ints

1261 Array of indices into the array. It has the same shape as `a.shape`

1262 with the dimension along `axis` removed. If `keepdims` is set to True,

1263 then the size of `axis` will be 1 with the resulting array having same

1264 shape as `a.shape`.

1265

1266 See Also

1267 --------

1268 ndarray.argmin, argmax

1269 amin : The minimum value along a given axis.

1270 unravel_index : Convert a flat index into an index tuple.

1271 take_along_axis : Apply ``np.expand_dims(index_array, axis)``

1272 from argmin to an array as if by calling min.

1273

1274 Notes

1275 -----

1276 In case of multiple occurrences of the minimum values, the indices

1277 corresponding to the first occurrence are returned.

1278

1279 Examples

1280 --------

1281 >>> a = np.arange(6).reshape(2,3) + 10

1282 >>> a

1283 array([[10, 11, 12],

1284 [13, 14, 15]])

1285 >>> np.argmin(a)

1286 0

1287 >>> np.argmin(a, axis=0)

1288 array([0, 0, 0])

1289 >>> np.argmin(a, axis=1)

1290 array([0, 0])

1291

1292 Indices of the minimum elements of a N-dimensional array:

1293

1294 >>> ind = np.unravel_index(np.argmin(a, axis=None), a.shape)

1295 >>> ind

1296 (0, 0)

1297 >>> a[ind]

1298 10

1299

1300 >>> b = np.arange(6) + 10

1301 >>> b[4] = 10

1302 >>> b

1303 array([10, 11, 12, 13, 10, 15])

1304 >>> np.argmin(b) # Only the first occurrence is returned.

1305 0

1306

1307 >>> x = np.array([[4,2,3], [1,0,3]])

1308 >>> index_array = np.argmin(x, axis=-1)

1309 >>> # Same as np.amin(x, axis=-1, keepdims=True)

1310 >>> np.take_along_axis(x, np.expand_dims(index_array, axis=-1), axis=-1)

1311 array([[2],

1312 [0]])

1313 >>> # Same as np.amax(x, axis=-1)

1314 >>> np.take_along_axis(x, np.expand_dims(index_array, axis=-1), axis=-1).squeeze(axis=-1)

1315 array([2, 0])

1316

1317 Setting `keepdims` to `True`,

1318

1319 >>> x = np.arange(24).reshape((2, 3, 4))

1320 >>> res = np.argmin(x, axis=1, keepdims=True)

1321 >>> res.shape

1322 (2, 1, 4)

1323 """

1324 kwds = {'keepdims': keepdims} if keepdims is not np._NoValue else {}

1325 return _wrapfunc(a, 'argmin', axis=axis, out=out, **kwds)

1326

1327

1328def _searchsorted_dispatcher(a, v, side=None, sorter=None):

1329 return (a, v, sorter)

1330

1331

1332@array_function_dispatch(_searchsorted_dispatcher)

1333def searchsorted(a, v, side='left', sorter=None):

1334 """

1335 Find indices where elements should be inserted to maintain order.

1336

1337 Find the indices into a sorted array `a` such that, if the

1338 corresponding elements in `v` were inserted before the indices, the

1339 order of `a` would be preserved.

1340

1341 Assuming that `a` is sorted:

1342

1343 ====== ============================

1344 `side` returned index `i` satisfies

1345 ====== ============================

1346 left ``a[i-1] < v <= a[i]``

1347 right ``a[i-1] <= v < a[i]``

1348 ====== ============================

1349

1350 Parameters

1351 ----------

1352 a : 1-D array_like

1353 Input array. If `sorter` is None, then it must be sorted in

1354 ascending order, otherwise `sorter` must be an array of indices

1355 that sort it.

1356 v : array_like

1357 Values to insert into `a`.

1358 side : {'left', 'right'}, optional

1359 If 'left', the index of the first suitable location found is given.

1360 If 'right', return the last such index. If there is no suitable

1361 index, return either 0 or N (where N is the length of `a`).

1362 sorter : 1-D array_like, optional

1363 Optional array of integer indices that sort array a into ascending

1364 order. They are typically the result of argsort.

1365

1366 .. versionadded:: 1.7.0

1367

1368 Returns

1369 -------

1370 indices : int or array of ints

1371 Array of insertion points with the same shape as `v`,

1372 or an integer if `v` is a scalar.

1373

1374 See Also

1375 --------

1376 sort : Return a sorted copy of an array.

1377 histogram : Produce histogram from 1-D data.

1378

1379 Notes

1380 -----

1381 Binary search is used to find the required insertion points.

1382

1383 As of NumPy 1.4.0 `searchsorted` works with real/complex arrays containing

1384 `nan` values. The enhanced sort order is documented in `sort`.

1385

1386 This function uses the same algorithm as the builtin python `bisect.bisect_left`

1387 (``side='left'``) and `bisect.bisect_right` (``side='right'``) functions,

1388 which is also vectorized in the `v` argument.

1389

1390 Examples

1391 --------

1392 >>> np.searchsorted([1,2,3,4,5], 3)

1393 2

1394 >>> np.searchsorted([1,2,3,4,5], 3, side='right')

1395 3

1396 >>> np.searchsorted([1,2,3,4,5], [-10, 10, 2, 3])

1397 array([0, 5, 1, 2])

1398

1399 """

1400 return _wrapfunc(a, 'searchsorted', v, side=side, sorter=sorter)

1401

1402

1403def _resize_dispatcher(a, new_shape):

1404 return (a,)

1405

1406

1407@array_function_dispatch(_resize_dispatcher)

1408def resize(a, new_shape):

1409 """

1410 Return a new array with the specified shape.

1411

1412 If the new array is larger than the original array, then the new

1413 array is filled with repeated copies of `a`. Note that this behavior

1414 is different from a.resize(new_shape) which fills with zeros instead

1415 of repeated copies of `a`.

1416

1417 Parameters

1418 ----------

1419 a : array_like

1420 Array to be resized.

1421

1422 new_shape : int or tuple of int

1423 Shape of resized array.

1424

1425 Returns

1426 -------

1427 reshaped_array : ndarray

1428 The new array is formed from the data in the old array, repeated

1429 if necessary to fill out the required number of elements. The

1430 data are repeated iterating over the array in C-order.

1431

1432 See Also

1433 --------

1434 numpy.reshape : Reshape an array without changing the total size.

1435 numpy.pad : Enlarge and pad an array.

1436 numpy.repeat : Repeat elements of an array.

1437 ndarray.resize : resize an array in-place.

1438

1439 Notes

1440 -----

1441 When the total size of the array does not change `~numpy.reshape` should

1442 be used. In most other cases either indexing (to reduce the size)

1443 or padding (to increase the size) may be a more appropriate solution.

1444

1445 Warning: This functionality does **not** consider axes separately,

1446 i.e. it does not apply interpolation/extrapolation.

1447 It fills the return array with the required number of elements, iterating

1448 over `a` in C-order, disregarding axes (and cycling back from the start if

1449 the new shape is larger). This functionality is therefore not suitable to

1450 resize images, or data where each axis represents a separate and distinct

1451 entity.

1452

1453 Examples

1454 --------

1455 >>> a=np.array([[0,1],[2,3]])

1456 >>> np.resize(a,(2,3))

1457 array([[0, 1, 2],

1458 [3, 0, 1]])

1459 >>> np.resize(a,(1,4))

1460 array([[0, 1, 2, 3]])

1461 >>> np.resize(a,(2,4))

1462 array([[0, 1, 2, 3],

1463 [0, 1, 2, 3]])

1464

1465 """

1466 if isinstance(new_shape, (int, nt.integer)):

1467 new_shape = (new_shape,)

1468

1469 a = ravel(a)

1470

1471 new_size = 1

1472 for dim_length in new_shape:

1473 new_size *= dim_length

1474 if dim_length < 0:

1475 raise ValueError('all elements of `new_shape` must be non-negative')

1476

1477 if a.size == 0 or new_size == 0:

1478 # First case must zero fill. The second would have repeats == 0.

1479 return np.zeros_like(a, shape=new_shape)

1480

1481 repeats = -(-new_size // a.size) # ceil division

1482 a = concatenate((a,) * repeats)[:new_size]

1483

1484 return reshape(a, new_shape)

1485

1486

1487def _squeeze_dispatcher(a, axis=None):

1488 return (a,)

1489

1490

1491@array_function_dispatch(_squeeze_dispatcher)

1492def squeeze(a, axis=None):

1493 """

1494 Remove axes of length one from `a`.

1495

1496 Parameters

1497 ----------

1498 a : array_like

1499 Input data.

1500 axis : None or int or tuple of ints, optional

1501 .. versionadded:: 1.7.0

1502

1503 Selects a subset of the entries of length one in the

1504 shape. If an axis is selected with shape entry greater than

1505 one, an error is raised.

1506

1507 Returns

1508 -------

1509 squeezed : ndarray

1510 The input array, but with all or a subset of the

1511 dimensions of length 1 removed. This is always `a` itself

1512 or a view into `a`. Note that if all axes are squeezed,

1513 the result is a 0d array and not a scalar.

1514

1515 Raises

1516 ------

1517 ValueError

1518 If `axis` is not None, and an axis being squeezed is not of length 1

1519

1520 See Also

1521 --------

1522 expand_dims : The inverse operation, adding entries of length one

1523 reshape : Insert, remove, and combine dimensions, and resize existing ones

1524

1525 Examples

1526 --------

1527 >>> x = np.array([[[0], [1], [2]]])

1528 >>> x.shape

1529 (1, 3, 1)

1530 >>> np.squeeze(x).shape

1531 (3,)

1532 >>> np.squeeze(x, axis=0).shape

1533 (3, 1)

1534 >>> np.squeeze(x, axis=1).shape

1535 Traceback (most recent call last):

1536 ...

1537 ValueError: cannot select an axis to squeeze out which has size not equal to one

1538 >>> np.squeeze(x, axis=2).shape

1539 (1, 3)

1540 >>> x = np.array([[1234]])

1541 >>> x.shape

1542 (1, 1)

1543 >>> np.squeeze(x)

1544 array(1234) # 0d array

1545 >>> np.squeeze(x).shape

1546 ()

1547 >>> np.squeeze(x)[()]

1548 1234

1549

1550 """

1551 try:

1552 squeeze = a.squeeze

1553 except AttributeError:

1554 return _wrapit(a, 'squeeze', axis=axis)

1555 if axis is None:

1556 return squeeze()

1557 else:

1558 return squeeze(axis=axis)

1559

1560

1561def _diagonal_dispatcher(a, offset=None, axis1=None, axis2=None):

1562 return (a,)

1563

1564

1565@array_function_dispatch(_diagonal_dispatcher)

1566def diagonal(a, offset=0, axis1=0, axis2=1):

1567 """

1568 Return specified diagonals.

1569

1570 If `a` is 2-D, returns the diagonal of `a` with the given offset,

1571 i.e., the collection of elements of the form ``a[i, i+offset]``. If

1572 `a` has more than two dimensions, then the axes specified by `axis1`

1573 and `axis2` are used to determine the 2-D sub-array whose diagonal is

1574 returned. The shape of the resulting array can be determined by

1575 removing `axis1` and `axis2` and appending an index to the right equal

1576 to the size of the resulting diagonals.

1577

1578 In versions of NumPy prior to 1.7, this function always returned a new,

1579 independent array containing a copy of the values in the diagonal.

1580

1581 In NumPy 1.7 and 1.8, it continues to return a copy of the diagonal,

1582 but depending on this fact is deprecated. Writing to the resulting

1583 array continues to work as it used to, but a FutureWarning is issued.

1584

1585 Starting in NumPy 1.9 it returns a read-only view on the original array.

1586 Attempting to write to the resulting array will produce an error.

1587

1588 In some future release, it will return a read/write view and writing to

1589 the returned array will alter your original array. The returned array

1590 will have the same type as the input array.

1591

1592 If you don't write to the array returned by this function, then you can

1593 just ignore all of the above.

1594

1595 If you depend on the current behavior, then we suggest copying the

1596 returned array explicitly, i.e., use ``np.diagonal(a).copy()`` instead

1597 of just ``np.diagonal(a)``. This will work with both past and future

1598 versions of NumPy.

1599

1600 Parameters

1601 ----------

1602 a : array_like

1603 Array from which the diagonals are taken.

1604 offset : int, optional

1605 Offset of the diagonal from the main diagonal. Can be positive or

1606 negative. Defaults to main diagonal (0).

1607 axis1 : int, optional

1608 Axis to be used as the first axis of the 2-D sub-arrays from which

1609 the diagonals should be taken. Defaults to first axis (0).

1610 axis2 : int, optional

1611 Axis to be used as the second axis of the 2-D sub-arrays from

1612 which the diagonals should be taken. Defaults to second axis (1).

1613

1614 Returns

1615 -------

1616 array_of_diagonals : ndarray

1617 If `a` is 2-D, then a 1-D array containing the diagonal and of the

1618 same type as `a` is returned unless `a` is a `matrix`, in which case

1619 a 1-D array rather than a (2-D) `matrix` is returned in order to

1620 maintain backward compatibility.

1621

1622 If ``a.ndim > 2``, then the dimensions specified by `axis1` and `axis2`

1623 are removed, and a new axis inserted at the end corresponding to the

1624 diagonal.

1625

1626 Raises

1627 ------

1628 ValueError

1629 If the dimension of `a` is less than 2.

1630

1631 See Also

1632 --------

1633 diag : MATLAB work-a-like for 1-D and 2-D arrays.

1634 diagflat : Create diagonal arrays.

1635 trace : Sum along diagonals.

1636

1637 Examples

1638 --------

1639 >>> a = np.arange(4).reshape(2,2)

1640 >>> a

1641 array([[0, 1],

1642 [2, 3]])

1643 >>> a.diagonal()

1644 array([0, 3])

1645 >>> a.diagonal(1)

1646 array([1])

1647

1648 A 3-D example:

1649

1650 >>> a = np.arange(8).reshape(2,2,2); a

1651 array([[[0, 1],

1652 [2, 3]],

1653 [[4, 5],

1654 [6, 7]]])

1655 >>> a.diagonal(0, # Main diagonals of two arrays created by skipping

1656 ... 0, # across the outer(left)-most axis last and

1657 ... 1) # the "middle" (row) axis first.

1658 array([[0, 6],

1659 [1, 7]])

1660

1661 The sub-arrays whose main diagonals we just obtained; note that each

1662 corresponds to fixing the right-most (column) axis, and that the

1663 diagonals are "packed" in rows.

1664

1665 >>> a[:,:,0] # main diagonal is [0 6]

1666 array([[0, 2],

1667 [4, 6]])

1668 >>> a[:,:,1] # main diagonal is [1 7]

1669 array([[1, 3],

1670 [5, 7]])

1671

1672 The anti-diagonal can be obtained by reversing the order of elements

1673 using either `numpy.flipud` or `numpy.fliplr`.

1674

1675 >>> a = np.arange(9).reshape(3, 3)

1676 >>> a

1677 array([[0, 1, 2],

1678 [3, 4, 5],

1679 [6, 7, 8]])

1680 >>> np.fliplr(a).diagonal() # Horizontal flip

1681 array([2, 4, 6])

1682 >>> np.flipud(a).diagonal() # Vertical flip

1683 array([6, 4, 2])

1684

1685 Note that the order in which the diagonal is retrieved varies depending

1686 on the flip function.

1687 """

1688 if isinstance(a, np.matrix):

1689 # Make diagonal of matrix 1-D to preserve backward compatibility.

1690 return asarray(a).diagonal(offset=offset, axis1=axis1, axis2=axis2)

1691 else:

1692 return asanyarray(a).diagonal(offset=offset, axis1=axis1, axis2=axis2)

1693

1694

1695def _trace_dispatcher(

1696 a, offset=None, axis1=None, axis2=None, dtype=None, out=None):

1697 return (a, out)

1698

1699

1700@array_function_dispatch(_trace_dispatcher)

1701def trace(a, offset=0, axis1=0, axis2=1, dtype=None, out=None):

1702 """

1703 Return the sum along diagonals of the array.

1704

1705 If `a` is 2-D, the sum along its diagonal with the given offset

1706 is returned, i.e., the sum of elements ``a[i,i+offset]`` for all i.

1707

1708 If `a` has more than two dimensions, then the axes specified by axis1 and

1709 axis2 are used to determine the 2-D sub-arrays whose traces are returned.

1710 The shape of the resulting array is the same as that of `a` with `axis1`

1711 and `axis2` removed.

1712

1713 Parameters

1714 ----------

1715 a : array_like

1716 Input array, from which the diagonals are taken.

1717 offset : int, optional

1718 Offset of the diagonal from the main diagonal. Can be both positive

1719 and negative. Defaults to 0.

1720 axis1, axis2 : int, optional

1721 Axes to be used as the first and second axis of the 2-D sub-arrays

1722 from which the diagonals should be taken. Defaults are the first two

1723 axes of `a`.

1724 dtype : dtype, optional

1725 Determines the data-type of the returned array and of the accumulator

1726 where the elements are summed. If dtype has the value None and `a` is

1727 of integer type of precision less than the default integer

1728 precision, then the default integer precision is used. Otherwise,

1729 the precision is the same as that of `a`.

1730 out : ndarray, optional

1731 Array into which the output is placed. Its type is preserved and

1732 it must be of the right shape to hold the output.

1733

1734 Returns

1735 -------

1736 sum_along_diagonals : ndarray

1737 If `a` is 2-D, the sum along the diagonal is returned. If `a` has

1738 larger dimensions, then an array of sums along diagonals is returned.

1739

1740 See Also

1741 --------

1742 diag, diagonal, diagflat

1743

1744 Examples

1745 --------

1746 >>> np.trace(np.eye(3))

1747 3.0

1748 >>> a = np.arange(8).reshape((2,2,2))

1749 >>> np.trace(a)

1750 array([6, 8])

1751

1752 >>> a = np.arange(24).reshape((2,2,2,3))

1753 >>> np.trace(a).shape

1754 (2, 3)

1755

1756 """

1757 if isinstance(a, np.matrix):

1758 # Get trace of matrix via an array to preserve backward compatibility.

1759 return asarray(a).trace(offset=offset, axis1=axis1, axis2=axis2, dtype=dtype, out=out)

1760 else:

1761 return asanyarray(a).trace(offset=offset, axis1=axis1, axis2=axis2, dtype=dtype, out=out)

1762

1763

1764def _ravel_dispatcher(a, order=None):

1765 return (a,)

1766

1767

1768@array_function_dispatch(_ravel_dispatcher)

1769def ravel(a, order='C'):

1770 """Return a contiguous flattened array.

1771

1772 A 1-D array, containing the elements of the input, is returned. A copy is

1773 made only if needed.

1774

1775 As of NumPy 1.10, the returned array will have the same type as the input

1776 array. (for example, a masked array will be returned for a masked array

1777 input)

1778

1779 Parameters

1780 ----------

1781 a : array_like

1782 Input array. The elements in `a` are read in the order specified by

1783 `order`, and packed as a 1-D array.

1784 order : {'C','F', 'A', 'K'}, optional

1785

1786 The elements of `a` are read using this index order. 'C' means

1787 to index the elements in row-major, C-style order,

1788 with the last axis index changing fastest, back to the first

1789 axis index changing slowest. 'F' means to index the elements

1790 in column-major, Fortran-style order, with the

1791 first index changing fastest, and the last index changing

1792 slowest. Note that the 'C' and 'F' options take no account of

1793 the memory layout of the underlying array, and only refer to

1794 the order of axis indexing. 'A' means to read the elements in

1795 Fortran-like index order if `a` is Fortran *contiguous* in

1796 memory, C-like order otherwise. 'K' means to read the

1797 elements in the order they occur in memory, except for

1798 reversing the data when strides are negative. By default, 'C'

1799 index order is used.

1800

1801 Returns

1802 -------

1803 y : array_like

1804 y is a contiguous 1-D array of the same subtype as `a`,

1805 with shape ``(a.size,)``.

1806 Note that matrices are special cased for backward compatibility,

1807 if `a` is a matrix, then y is a 1-D ndarray.

1808

1809 See Also

1810 --------

1811 ndarray.flat : 1-D iterator over an array.

1812 ndarray.flatten : 1-D array copy of the elements of an array

1813 in row-major order.

1814 ndarray.reshape : Change the shape of an array without changing its data.

1815

1816 Notes

1817 -----

1818 In row-major, C-style order, in two dimensions, the row index

1819 varies the slowest, and the column index the quickest. This can

1820 be generalized to multiple dimensions, where row-major order

1821 implies that the index along the first axis varies slowest, and

1822 the index along the last quickest. The opposite holds for

1823 column-major, Fortran-style index ordering.

1824

1825 When a view is desired in as many cases as possible, ``arr.reshape(-1)``

1826 may be preferable. However, ``ravel`` supports ``K`` in the optional

1827 ``order`` argument while ``reshape`` does not.

1828

1829 Examples

1830 --------

1831 It is equivalent to ``reshape(-1, order=order)``.

1832

1833 >>> x = np.array([[1, 2, 3], [4, 5, 6]])

1834 >>> np.ravel(x)

1835 array([1, 2, 3, 4, 5, 6])

1836

1837 >>> x.reshape(-1)

1838 array([1, 2, 3, 4, 5, 6])

1839

1840 >>> np.ravel(x, order='F')

1841 array([1, 4, 2, 5, 3, 6])

1842

1843 When ``order`` is 'A', it will preserve the array's 'C' or 'F' ordering:

1844

1845 >>> np.ravel(x.T)

1846 array([1, 4, 2, 5, 3, 6])

1847 >>> np.ravel(x.T, order='A')

1848 array([1, 2, 3, 4, 5, 6])

1849

1850 When ``order`` is 'K', it will preserve orderings that are neither 'C'

1851 nor 'F', but won't reverse axes:

1852

1853 >>> a = np.arange(3)[::-1]; a

1854 array([2, 1, 0])

1855 >>> a.ravel(order='C')

1856 array([2, 1, 0])

1857 >>> a.ravel(order='K')

1858 array([2, 1, 0])

1859

1860 >>> a = np.arange(12).reshape(2,3,2).swapaxes(1,2); a

1861 array([[[ 0, 2, 4],

1862 [ 1, 3, 5]],

1863 [[ 6, 8, 10],

1864 [ 7, 9, 11]]])

1865 >>> a.ravel(order='C')

1866 array([ 0, 2, 4, 1, 3, 5, 6, 8, 10, 7, 9, 11])

1867 >>> a.ravel(order='K')

1868 array([ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])

1869

1870 """

1871 if isinstance(a, np.matrix):

1872 return asarray(a).ravel(order=order)

1873 else:

1874 return asanyarray(a).ravel(order=order)

1875

1876

1877def _nonzero_dispatcher(a):

1878 return (a,)

1879

1880

1881@array_function_dispatch(_nonzero_dispatcher)

1882def nonzero(a):

1883 """

1884 Return the indices of the elements that are non-zero.

1885

1886 Returns a tuple of arrays, one for each dimension of `a`,

1887 containing the indices of the non-zero elements in that

1888 dimension. The values in `a` are always tested and returned in

1889 row-major, C-style order.

1890

1891 To group the indices by element, rather than dimension, use `argwhere`,

1892 which returns a row for each non-zero element.

1893

1894 .. note::

1895

1896 When called on a zero-d array or scalar, ``nonzero(a)`` is treated

1897 as ``nonzero(atleast_1d(a))``.

1898

1899 .. deprecated:: 1.17.0

1900

1901 Use `atleast_1d` explicitly if this behavior is deliberate.

1902

1903 Parameters

1904 ----------

1905 a : array_like

1906 Input array.

1907

1908 Returns

1909 -------

1910 tuple_of_arrays : tuple

1911 Indices of elements that are non-zero.

1912

1913 See Also

1914 --------

1915 flatnonzero :

1916 Return indices that are non-zero in the flattened version of the input

1917 array.

1918 ndarray.nonzero :

1919 Equivalent ndarray method.

1920 count_nonzero :

1921 Counts the number of non-zero elements in the input array.

1922

1923 Notes

1924 -----

1925 While the nonzero values can be obtained with ``a[nonzero(a)]``, it is

1926 recommended to use ``x[x.astype(bool)]`` or ``x[x != 0]`` instead, which

1927 will correctly handle 0-d arrays.

1928

1929 Examples

1930 --------

1931 >>> x = np.array([[3, 0, 0], [0, 4, 0], [5, 6, 0]])

1932 >>> x

1933 array([[3, 0, 0],

1934 [0, 4, 0],

1935 [5, 6, 0]])

1936 >>> np.nonzero(x)

1937 (array([0, 1, 2, 2]), array([0, 1, 0, 1]))

1938

1939 >>> x[np.nonzero(x)]

1940 array([3, 4, 5, 6])

1941 >>> np.transpose(np.nonzero(x))

1942 array([[0, 0],

1943 [1, 1],

1944 [2, 0],

1945 [2, 1]])

1946

1947 A common use for ``nonzero`` is to find the indices of an array, where

1948 a condition is True. Given an array `a`, the condition `a` > 3 is a

1949 boolean array and since False is interpreted as 0, np.nonzero(a > 3)

1950 yields the indices of the `a` where the condition is true.

1951

1952 >>> a = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])

1953 >>> a > 3

1954 array([[False, False, False],

1955 [ True, True, True],

1956 [ True, True, True]])

1957 >>> np.nonzero(a > 3)

1958 (array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))

1959

1960 Using this result to index `a` is equivalent to using the mask directly:

1961

1962 >>> a[np.nonzero(a > 3)]

1963 array([4, 5, 6, 7, 8, 9])

1964 >>> a[a > 3] # prefer this spelling

1965 array([4, 5, 6, 7, 8, 9])

1966

1967 ``nonzero`` can also be called as a method of the array.

1968

1969 >>> (a > 3).nonzero()

1970 (array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))

1971

1972 """

1973 return _wrapfunc(a, 'nonzero')

1974

1975

1976def _shape_dispatcher(a):

1977 return (a,)

1978

1979

1980@array_function_dispatch(_shape_dispatcher)

1981def shape(a):

1982 """

1983 Return the shape of an array.

1984

1985 Parameters

1986 ----------

1987 a : array_like

1988 Input array.

1989

1990 Returns

1991 -------

1992 shape : tuple of ints

1993 The elements of the shape tuple give the lengths of the

1994 corresponding array dimensions.

1995

1996 See Also

1997 --------

1998 len : ``len(a)`` is equivalent to ``np.shape(a)[0]`` for N-D arrays with

1999 ``N>=1``.

2000 ndarray.shape : Equivalent array method.

2001

2002 Examples

2003 --------

2004 >>> np.shape(np.eye(3))

2005 (3, 3)

2006 >>> np.shape([[1, 3]])

2007 (1, 2)

2008 >>> np.shape([0])

2009 (1,)

2010 >>> np.shape(0)

2011 ()

2012

2013 >>> a = np.array([(1, 2), (3, 4), (5, 6)],

2014 ... dtype=[('x', 'i4'), ('y', 'i4')])

2015 >>> np.shape(a)

2016 (3,)

2017 >>> a.shape

2018 (3,)

2019

2020 """

2021 try:

2022 result = a.shape

2023 except AttributeError:

2024 result = asarray(a).shape

2025 return result

2026

2027

2028def _compress_dispatcher(condition, a, axis=None, out=None):

2029 return (condition, a, out)

2030

2031

2032@array_function_dispatch(_compress_dispatcher)

2033def compress(condition, a, axis=None, out=None):

2034 """

2035 Return selected slices of an array along given axis.

2036

2037 When working along a given axis, a slice along that axis is returned in

2038 `output` for each index where `condition` evaluates to True. When

2039 working on a 1-D array, `compress` is equivalent to `extract`.

2040

2041 Parameters

2042 ----------

2043 condition : 1-D array of bools

2044 Array that selects which entries to return. If len(condition)

2045 is less than the size of `a` along the given axis, then output is

2046 truncated to the length of the condition array.

2047 a : array_like

2048 Array from which to extract a part.

2049 axis : int, optional

2050 Axis along which to take slices. If None (default), work on the

2051 flattened array.

2052 out : ndarray, optional

2053 Output array. Its type is preserved and it must be of the right

2054 shape to hold the output.

2055

2056 Returns

2057 -------

2058 compressed_array : ndarray

2059 A copy of `a` without the slices along axis for which `condition`

2060 is false.

2061

2062 See Also

2063 --------

2064 take, choose, diag, diagonal, select

2065 ndarray.compress : Equivalent method in ndarray

2066 extract : Equivalent method when working on 1-D arrays

2067 :ref:`ufuncs-output-type`

2068

2069 Examples

2070 --------

2071 >>> a = np.array([[1, 2], [3, 4], [5, 6]])

2072 >>> a

2073 array([[1, 2],

2074 [3, 4],

2075 [5, 6]])

2076 >>> np.compress([0, 1], a, axis=0)

2077 array([[3, 4]])

2078 >>> np.compress([False, True, True], a, axis=0)

2079 array([[3, 4],

2080 [5, 6]])

2081 >>> np.compress([False, True], a, axis=1)

2082 array([[2],

2083 [4],

2084 [6]])

2085

2086 Working on the flattened array does not return slices along an axis but

2087 selects elements.

2088

2089 >>> np.compress([False, True], a)

2090 array([2])

2091

2092 """

2093 return _wrapfunc(a, 'compress', condition, axis=axis, out=out)

2094

2095

2096def _clip_dispatcher(a, a_min, a_max, out=None, **kwargs):

2097 return (a, a_min, a_max)

2098

2099

2100@array_function_dispatch(_clip_dispatcher)

2101def clip(a, a_min, a_max, out=None, **kwargs):

2102 """

2103 Clip (limit) the values in an array.

2104

2105 Given an interval, values outside the interval are clipped to

2106 the interval edges. For example, if an interval of ``[0, 1]``

2107 is specified, values smaller than 0 become 0, and values larger

2108 than 1 become 1.

2109

2110 Equivalent to but faster than ``np.minimum(a_max, np.maximum(a, a_min))``.

2111

2112 No check is performed to ensure ``a_min < a_max``.

2113

2114 Parameters

2115 ----------

2116 a : array_like

2117 Array containing elements to clip.

2118 a_min, a_max : array_like or None

2119 Minimum and maximum value. If ``None``, clipping is not performed on

2120 the corresponding edge. Only one of `a_min` and `a_max` may be

2121 ``None``. Both are broadcast against `a`.

2122 out : ndarray, optional

2123 The results will be placed in this array. It may be the input

2124 array for in-place clipping. `out` must be of the right shape

2125 to hold the output. Its type is preserved.

2126 **kwargs

2127 For other keyword-only arguments, see the

2128 :ref:`ufunc docs <ufuncs.kwargs>`.

2129

2130 .. versionadded:: 1.17.0

2131

2132 Returns

2133 -------

2134 clipped_array : ndarray

2135 An array with the elements of `a`, but where values

2136 < `a_min` are replaced with `a_min`, and those > `a_max`

2137 with `a_max`.

2138

2139 See Also

2140 --------

2141 :ref:`ufuncs-output-type`

2142

2143 Notes

2144 -----

2145 When `a_min` is greater than `a_max`, `clip` returns an

2146 array in which all values are equal to `a_max`,

2147 as shown in the second example.

2148

2149 Examples

2150 --------

2151 >>> a = np.arange(10)

2152 >>> a

2153 array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])

2154 >>> np.clip(a, 1, 8)

2155 array([1, 1, 2, 3, 4, 5, 6, 7, 8, 8])

2156 >>> np.clip(a, 8, 1)

2157 array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1])

2158 >>> np.clip(a, 3, 6, out=a)

2159 array([3, 3, 3, 3, 4, 5, 6, 6, 6, 6])

2160 >>> a

2161 array([3, 3, 3, 3, 4, 5, 6, 6, 6, 6])

2162 >>> a = np.arange(10)

2163 >>> a

2164 array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])

2165 >>> np.clip(a, [3, 4, 1, 1, 1, 4, 4, 4, 4, 4], 8)

2166 array([3, 4, 2, 3, 4, 5, 6, 7, 8, 8])

2167

2168 """

2169 return _wrapfunc(a, 'clip', a_min, a_max, out=out, **kwargs)

2170

2171

2172def _sum_dispatcher(a, axis=None, dtype=None, out=None, keepdims=None,

2173 initial=None, where=None):

2174 return (a, out)

2175

2176

2177@array_function_dispatch(_sum_dispatcher)

2178def sum(a, axis=None, dtype=None, out=None, keepdims=np._NoValue,

2179 initial=np._NoValue, where=np._NoValue):

2180 """

2181 Sum of array elements over a given axis.

2182

2183 Parameters

2184 ----------

2185 a : array_like

2186 Elements to sum.

2187 axis : None or int or tuple of ints, optional

2188 Axis or axes along which a sum is performed. The default,

2189 axis=None, will sum all of the elements of the input array. If

2190 axis is negative it counts from the last to the first axis.

2191

2192 .. versionadded:: 1.7.0

2193

2194 If axis is a tuple of ints, a sum is performed on all of the axes

2195 specified in the tuple instead of a single axis or all the axes as

2196 before.

2197 dtype : dtype, optional

2198 The type of the returned array and of the accumulator in which the

2199 elements are summed. The dtype of `a` is used by default unless `a`

2200 has an integer dtype of less precision than the default platform

2201 integer. In that case, if `a` is signed then the platform integer

2202 is used while if `a` is unsigned then an unsigned integer of the

2203 same precision as the platform integer is used.

2204 out : ndarray, optional

2205 Alternative output array in which to place the result. It must have

2206 the same shape as the expected output, but the type of the output

2207 values will be cast if necessary.

2208 keepdims : bool, optional

2209 If this is set to True, the axes which are reduced are left

2210 in the result as dimensions with size one. With this option,

2211 the result will broadcast correctly against the input array.

2212

2213 If the default value is passed, then `keepdims` will not be

2214 passed through to the `sum` method of sub-classes of

2215 `ndarray`, however any non-default value will be. If the

2216 sub-class' method does not implement `keepdims` any

2217 exceptions will be raised.

2218 initial : scalar, optional

2219 Starting value for the sum. See `~numpy.ufunc.reduce` for details.

2220

2221 .. versionadded:: 1.15.0

2222

2223 where : array_like of bool, optional

2224 Elements to include in the sum. See `~numpy.ufunc.reduce` for details.

2225

2226 .. versionadded:: 1.17.0

2227

2228 Returns

2229 -------

2230 sum_along_axis : ndarray

2231 An array with the same shape as `a`, with the specified

2232 axis removed. If `a` is a 0-d array, or if `axis` is None, a scalar

2233 is returned. If an output array is specified, a reference to

2234 `out` is returned.

2235

2236 See Also

2237 --------

2238 ndarray.sum : Equivalent method.

2239

2240 add.reduce : Equivalent functionality of `add`.

2241

2242 cumsum : Cumulative sum of array elements.

2243

2244 trapz : Integration of array values using the composite trapezoidal rule.

2245

2246 mean, average

2247

2248 Notes

2249 -----

2250 Arithmetic is modular when using integer types, and no error is

2251 raised on overflow.

2252

2253 The sum of an empty array is the neutral element 0:

2254

2255 >>> np.sum([])

2256 0.0

2257

2258 For floating point numbers the numerical precision of sum (and

2259 ``np.add.reduce``) is in general limited by directly adding each number

2260 individually to the result causing rounding errors in every step.

2261 However, often numpy will use a numerically better approach (partial

2262 pairwise summation) leading to improved precision in many use-cases.

2263 This improved precision is always provided when no ``axis`` is given.

2264 When ``axis`` is given, it will depend on which axis is summed.

2265 Technically, to provide the best speed possible, the improved precision

2266 is only used when the summation is along the fast axis in memory.

2267 Note that the exact precision may vary depending on other parameters.

2268 In contrast to NumPy, Python's ``math.fsum`` function uses a slower but

2269 more precise approach to summation.

2270 Especially when summing a large number of lower precision floating point

2271 numbers, such as ``float32``, numerical errors can become significant.

2272 In such cases it can be advisable to use `dtype="float64"` to use a higher

2273 precision for the output.

2274

2275 Examples

2276 --------

2277 >>> np.sum([0.5, 1.5])

2278 2.0

2279 >>> np.sum([0.5, 0.7, 0.2, 1.5], dtype=np.int32)

2280 1

2281 >>> np.sum([[0, 1], [0, 5]])

2282 6

2283 >>> np.sum([[0, 1], [0, 5]], axis=0)

2284 array([0, 6])

2285 >>> np.sum([[0, 1], [0, 5]], axis=1)

2286 array([1, 5])

2287 >>> np.sum([[0, 1], [np.nan, 5]], where=[False, True], axis=1)

2288 array([1., 5.])

2289

2290 If the accumulator is too small, overflow occurs:

2291

2292 >>> np.ones(128, dtype=np.int8).sum(dtype=np.int8)

2293 -128

2294

2295 You can also start the sum with a value other than zero:

2296

2297 >>> np.sum([10], initial=5)

2298 15

2299 """

2300 if isinstance(a, _gentype):

2301 # 2018-02-25, 1.15.0

2302 warnings.warn(

2303 "Calling np.sum(generator) is deprecated, and in the future will give a different result. "

2304 "Use np.sum(np.fromiter(generator)) or the python sum builtin instead.",

2305 DeprecationWarning, stacklevel=2)

2306

2307 res = _sum_(a)

2308 if out is not None:

2309 out[...] = res

2310 return out

2311 return res

2312

2313 return _wrapreduction(a, np.add, 'sum', axis, dtype, out, keepdims=keepdims,

2314 initial=initial, where=where)

2315

2316

2317def _any_dispatcher(a, axis=None, out=None, keepdims=None, *,

2318 where=np._NoValue):

2319 return (a, where, out)

2320

2321

2322@array_function_dispatch(_any_dispatcher)

2323def any(a, axis=None, out=None, keepdims=np._NoValue, *, where=np._NoValue):

2324 """

2325 Test whether any array element along a given axis evaluates to True.

2326

2327 Returns single boolean if `axis` is ``None``

2328

2329 Parameters

2330 ----------

2331 a : array_like

2332 Input array or object that can be converted to an array.

2333 axis : None or int or tuple of ints, optional

2334 Axis or axes along which a logical OR reduction is performed.

2335 The default (``axis=None``) is to perform a logical OR over all

2336 the dimensions of the input array. `axis` may be negative, in

2337 which case it counts from the last to the first axis.

2338

2339 .. versionadded:: 1.7.0

2340

2341 If this is a tuple of ints, a reduction is performed on multiple

2342 axes, instead of a single axis or all the axes as before.

2343 out : ndarray, optional

2344 Alternate output array in which to place the result. It must have

2345 the same shape as the expected output and its type is preserved

2346 (e.g., if it is of type float, then it will remain so, returning

2347 1.0 for True and 0.0 for False, regardless of the type of `a`).

2348 See :ref:`ufuncs-output-type` for more details.

2349

2350 keepdims : bool, optional

2351 If this is set to True, the axes which are reduced are left

2352 in the result as dimensions with size one. With this option,

2353 the result will broadcast correctly against the input array.

2354

2355 If the default value is passed, then `keepdims` will not be

2356 passed through to the `any` method of sub-classes of

2357 `ndarray`, however any non-default value will be. If the

2358 sub-class' method does not implement `keepdims` any

2359 exceptions will be raised.

2360

2361 where : array_like of bool, optional

2362 Elements to include in checking for any `True` values.

2363 See `~numpy.ufunc.reduce` for details.

2364

2365 .. versionadded:: 1.20.0

2366

2367 Returns

2368 -------

2369 any : bool or ndarray

2370 A new boolean or `ndarray` is returned unless `out` is specified,

2371 in which case a reference to `out` is returned.

2372

2373 See Also

2374 --------

2375 ndarray.any : equivalent method

2376

2377 all : Test whether all elements along a given axis evaluate to True.

2378

2379 Notes

2380 -----

2381 Not a Number (NaN), positive infinity and negative infinity evaluate

2382 to `True` because these are not equal to zero.

2383

2384 Examples

2385 --------

2386 >>> np.any([[True, False], [True, True]])

2387 True

2388

2389 >>> np.any([[True, False], [False, False]], axis=0)

2390 array([ True, False])

2391

2392 >>> np.any([-1, 0, 5])

2393 True

2394

2395 >>> np.any(np.nan)

2396 True

2397

2398 >>> np.any([[True, False], [False, False]], where=[[False], [True]])

2399 False

2400

2401 >>> o=np.array(False)

2402 >>> z=np.any([-1, 4, 5], out=o)

2403 >>> z, o

2404 (array(True), array(True))

2405 >>> # Check now that z is a reference to o

2406 >>> z is o

2407 True

2408 >>> id(z), id(o) # identity of z and o # doctest: +SKIP

2409 (191614240, 191614240)

2410

2411 """

2412 return _wrapreduction(a, np.logical_or, 'any', axis, None, out,

2413 keepdims=keepdims, where=where)

2414

2415

2416def _all_dispatcher(a, axis=None, out=None, keepdims=None, *,

2417 where=None):

2418 return (a, where, out)

2419

2420

2421@array_function_dispatch(_all_dispatcher)

2422def all(a, axis=None, out=None, keepdims=np._NoValue, *, where=np._NoValue):

2423 """

2424 Test whether all array elements along a given axis evaluate to True.

2425

2426 Parameters

2427 ----------

2428 a : array_like

2429 Input array or object that can be converted to an array.

2430 axis : None or int or tuple of ints, optional

2431 Axis or axes along which a logical AND reduction is performed.

2432 The default (``axis=None``) is to perform a logical AND over all

2433 the dimensions of the input array. `axis` may be negative, in

2434 which case it counts from the last to the first axis.

2435

2436 .. versionadded:: 1.7.0

2437

2438 If this is a tuple of ints, a reduction is performed on multiple

2439 axes, instead of a single axis or all the axes as before.

2440 out : ndarray, optional

2441 Alternate output array in which to place the result.

2442 It must have the same shape as the expected output and its

2443 type is preserved (e.g., if ``dtype(out)`` is float, the result

2444 will consist of 0.0's and 1.0's). See :ref:`ufuncs-output-type` for more

2445 details.

2446

2447 keepdims : bool, optional

2448 If this is set to True, the axes which are reduced are left

2449 in the result as dimensions with size one. With this option,

2450 the result will broadcast correctly against the input array.

2451

2452 If the default value is passed, then `keepdims` will not be

2453 passed through to the `all` method of sub-classes of

2454 `ndarray`, however any non-default value will be. If the

2455 sub-class' method does not implement `keepdims` any

2456 exceptions will be raised.

2457

2458 where : array_like of bool, optional

2459 Elements to include in checking for all `True` values.

2460 See `~numpy.ufunc.reduce` for details.

2461

2462 .. versionadded:: 1.20.0

2463

2464 Returns

2465 -------

2466 all : ndarray, bool

2467 A new boolean or array is returned unless `out` is specified,

2468 in which case a reference to `out` is returned.

2469

2470 See Also

2471 --------

2472 ndarray.all : equivalent method

2473

2474 any : Test whether any element along a given axis evaluates to True.

2475

2476 Notes

2477 -----

2478 Not a Number (NaN), positive infinity and negative infinity

2479 evaluate to `True` because these are not equal to zero.

2480

2481 Examples

2482 --------

2483 >>> np.all([[True,False],[True,True]])

2484 False

2485

2486 >>> np.all([[True,False],[True,True]], axis=0)

2487 array([ True, False])

2488

2489 >>> np.all([-1, 4, 5])

2490 True

2491

2492 >>> np.all([1.0, np.nan])

2493 True

2494

2495 >>> np.all([[True, True], [False, True]], where=[[True], [False]])

2496 True

2497

2498 >>> o=np.array(False)

2499 >>> z=np.all([-1, 4, 5], out=o)

2500 >>> id(z), id(o), z

2501 (28293632, 28293632, array(True)) # may vary

2502

2503 """

2504 return _wrapreduction(a, np.logical_and, 'all', axis, None, out,

2505 keepdims=keepdims, where=where)

2506

2507

2508def _cumsum_dispatcher(a, axis=None, dtype=None, out=None):

2509 return (a, out)

2510

2511

2512@array_function_dispatch(_cumsum_dispatcher)

2513def cumsum(a, axis=None, dtype=None, out=None):

2514 """

2515 Return the cumulative sum of the elements along a given axis.

2516

2517 Parameters

2518 ----------

2519 a : array_like

2520 Input array.

2521 axis : int, optional

2522 Axis along which the cumulative sum is computed. The default

2523 (None) is to compute the cumsum over the flattened array.

2524 dtype : dtype, optional

2525 Type of the returned array and of the accumulator in which the

2526 elements are summed. If `dtype` is not specified, it defaults

2527 to the dtype of `a`, unless `a` has an integer dtype with a

2528 precision less than that of the default platform integer. In

2529 that case, the default platform integer is used.

2530 out : ndarray, optional

2531 Alternative output array in which to place the result. It must

2532 have the same shape and buffer length as the expected output

2533 but the type will be cast if necessary. See :ref:`ufuncs-output-type` for

2534 more details.

2535

2536 Returns

2537 -------

2538 cumsum_along_axis : ndarray.

2539 A new array holding the result is returned unless `out` is

2540 specified, in which case a reference to `out` is returned. The

2541 result has the same size as `a`, and the same shape as `a` if

2542 `axis` is not None or `a` is a 1-d array.

2543

2544 See Also

2545 --------

2546 sum : Sum array elements.

2547 trapz : Integration of array values using the composite trapezoidal rule.

2548 diff : Calculate the n-th discrete difference along given axis.

2549

2550 Notes

2551 -----

2552 Arithmetic is modular when using integer types, and no error is

2553 raised on overflow.

2554

2555 ``cumsum(a)[-1]`` may not be equal to ``sum(a)`` for floating-point

2556 values since ``sum`` may use a pairwise summation routine, reducing

2557 the roundoff-error. See `sum` for more information.

2558

2559 Examples

2560 --------

2561 >>> a = np.array([[1,2,3], [4,5,6]])

2562 >>> a

2563 array([[1, 2, 3],

2564 [4, 5, 6]])

2565 >>> np.cumsum(a)

2566 array([ 1, 3, 6, 10, 15, 21])

2567 >>> np.cumsum(a, dtype=float) # specifies type of output value(s)

2568 array([ 1., 3., 6., 10., 15., 21.])

2569

2570 >>> np.cumsum(a,axis=0) # sum over rows for each of the 3 columns

2571 array([[1, 2, 3],

2572 [5, 7, 9]])

2573 >>> np.cumsum(a,axis=1) # sum over columns for each of the 2 rows

2574 array([[ 1, 3, 6],

2575 [ 4, 9, 15]])

2576

2577 ``cumsum(b)[-1]`` may not be equal to ``sum(b)``

2578

2579 >>> b = np.array([1, 2e-9, 3e-9] * 1000000)

2580 >>> b.cumsum()[-1]

2581 1000000.0050045159

2582 >>> b.sum()

2583 1000000.0050000029

2584

2585 """

2586 return _wrapfunc(a, 'cumsum', axis=axis, dtype=dtype, out=out)

2587

2588

2589def _ptp_dispatcher(a, axis=None, out=None, keepdims=None):

2590 return (a, out)

2591

2592

2593@array_function_dispatch(_ptp_dispatcher)

2594def ptp(a, axis=None, out=None, keepdims=np._NoValue):

2595 """

2596 Range of values (maximum - minimum) along an axis.

2597

2598 The name of the function comes from the acronym for 'peak to peak'.

2599

2600 .. warning::

2601 `ptp` preserves the data type of the array. This means the

2602 return value for an input of signed integers with n bits

2603 (e.g. `np.int8`, `np.int16`, etc) is also a signed integer

2604 with n bits. In that case, peak-to-peak values greater than

2605 ``2**(n-1)-1`` will be returned as negative values. An example

2606 with a work-around is shown below.

2607

2608 Parameters

2609 ----------

2610 a : array_like

2611 Input values.

2612 axis : None or int or tuple of ints, optional

2613 Axis along which to find the peaks. By default, flatten the

2614 array. `axis` may be negative, in

2615 which case it counts from the last to the first axis.

2616

2617 .. versionadded:: 1.15.0

2618

2619 If this is a tuple of ints, a reduction is performed on multiple

2620 axes, instead of a single axis or all the axes as before.

2621 out : array_like

2622 Alternative output array in which to place the result. It must

2623 have the same shape and buffer length as the expected output,

2624 but the type of the output values will be cast if necessary.

2625

2626 keepdims : bool, optional

2627 If this is set to True, the axes which are reduced are left

2628 in the result as dimensions with size one. With this option,

2629 the result will broadcast correctly against the input array.

2630

2631 If the default value is passed, then `keepdims` will not be

2632 passed through to the `ptp` method of sub-classes of

2633 `ndarray`, however any non-default value will be. If the

2634 sub-class' method does not implement `keepdims` any

2635 exceptions will be raised.

2636

2637 Returns

2638 -------

2639 ptp : ndarray or scalar

2640 The range of a given array - `scalar` if array is one-dimensional

2641 or a new array holding the result along the given axis

2642

2643 Examples

2644 --------

2645 >>> x = np.array([[4, 9, 2, 10],

2646 ... [6, 9, 7, 12]])

2647

2648 >>> np.ptp(x, axis=1)

2649 array([8, 6])

2650

2651 >>> np.ptp(x, axis=0)

2652 array([2, 0, 5, 2])

2653

2654 >>> np.ptp(x)

2655 10

2656

2657 This example shows that a negative value can be returned when

2658 the input is an array of signed integers.

2659

2660 >>> y = np.array([[1, 127],

2661 ... [0, 127],

2662 ... [-1, 127],

2663 ... [-2, 127]], dtype=np.int8)

2664 >>> np.ptp(y, axis=1)

2665 array([ 126, 127, -128, -127], dtype=int8)

2666

2667 A work-around is to use the `view()` method to view the result as

2668 unsigned integers with the same bit width:

2669

2670 >>> np.ptp(y, axis=1).view(np.uint8)

2671 array([126, 127, 128, 129], dtype=uint8)

2672

2673 """

2674 kwargs = {}

2675 if keepdims is not np._NoValue:

2676 kwargs['keepdims'] = keepdims

2677 if type(a) is not mu.ndarray:

2678 try:

2679 ptp = a.ptp

2680 except AttributeError:

2681 pass

2682 else:

2683 return ptp(axis=axis, out=out, **kwargs)

2684 return _methods._ptp(a, axis=axis, out=out, **kwargs)

2685

2686

2687def _max_dispatcher(a, axis=None, out=None, keepdims=None, initial=None,

2688 where=None):

2689 return (a, out)

2690

2691

2692@array_function_dispatch(_max_dispatcher)

2693@set_module('numpy')

2694def max(a, axis=None, out=None, keepdims=np._NoValue, initial=np._NoValue,

2695 where=np._NoValue):

2696 """

2697 Return the maximum of an array or maximum along an axis.

2698

2699 Parameters

2700 ----------

2701 a : array_like

2702 Input data.

2703 axis : None or int or tuple of ints, optional

2704 Axis or axes along which to operate. By default, flattened input is

2705 used.

2706

2707 .. versionadded:: 1.7.0

2708

2709 If this is a tuple of ints, the maximum is selected over multiple axes,

2710 instead of a single axis or all the axes as before.

2711 out : ndarray, optional

2712 Alternative output array in which to place the result. Must

2713 be of the same shape and buffer length as the expected output.

2714 See :ref:`ufuncs-output-type` for more details.

2715

2716 keepdims : bool, optional

2717 If this is set to True, the axes which are reduced are left

2718 in the result as dimensions with size one. With this option,

2719 the result will broadcast correctly against the input array.

2720

2721 If the default value is passed, then `keepdims` will not be

2722 passed through to the ``max`` method of sub-classes of

2723 `ndarray`, however any non-default value will be. If the

2724 sub-class' method does not implement `keepdims` any

2725 exceptions will be raised.

2726

2727 initial : scalar, optional

2728 The minimum value of an output element. Must be present to allow

2729 computation on empty slice. See `~numpy.ufunc.reduce` for details.

2730

2731 .. versionadded:: 1.15.0

2732

2733 where : array_like of bool, optional

2734 Elements to compare for the maximum. See `~numpy.ufunc.reduce`

2735 for details.

2736

2737 .. versionadded:: 1.17.0

2738

2739 Returns

2740 -------

2741 max : ndarray or scalar

2742 Maximum of `a`. If `axis` is None, the result is a scalar value.

2743 If `axis` is an int, the result is an array of dimension

2744 ``a.ndim - 1``. If `axis` is a tuple, the result is an array of

2745 dimension ``a.ndim - len(axis)``.

2746

2747 See Also

2748 --------

2749 amin :

2750 The minimum value of an array along a given axis, propagating any NaNs.

2751 nanmax :

2752 The maximum value of an array along a given axis, ignoring any NaNs.

2753 maximum :

2754 Element-wise maximum of two arrays, propagating any NaNs.

2755 fmax :

2756 Element-wise maximum of two arrays, ignoring any NaNs.

2757 argmax :

2758 Return the indices of the maximum values.

2759

2760 nanmin, minimum, fmin

2761

2762 Notes

2763 -----

2764 NaN values are propagated, that is if at least one item is NaN, the

2765 corresponding max value will be NaN as well. To ignore NaN values

2766 (MATLAB behavior), please use nanmax.

2767

2768 Don't use `~numpy.max` for element-wise comparison of 2 arrays; when

2769 ``a.shape[0]`` is 2, ``maximum(a[0], a[1])`` is faster than

2770 ``max(a, axis=0)``.

2771

2772 Examples

2773 --------

2774 >>> a = np.arange(4).reshape((2,2))

2775 >>> a

2776 array([[0, 1],

2777 [2, 3]])

2778 >>> np.max(a) # Maximum of the flattened array

2779 3

2780 >>> np.max(a, axis=0) # Maxima along the first axis

2781 array([2, 3])

2782 >>> np.max(a, axis=1) # Maxima along the second axis

2783 array([1, 3])

2784 >>> np.max(a, where=[False, True], initial=-1, axis=0)

2785 array([-1, 3])

2786 >>> b = np.arange(5, dtype=float)

2787 >>> b[2] = np.NaN

2788 >>> np.max(b)

2789 nan

2790 >>> np.max(b, where=~np.isnan(b), initial=-1)

2791 4.0

2792 >>> np.nanmax(b)

2793 4.0

2794

2795 You can use an initial value to compute the maximum of an empty slice, or

2796 to initialize it to a different value:

2797

2798 >>> np.max([[-50], [10]], axis=-1, initial=0)

2799 array([ 0, 10])

2800

2801 Notice that the initial value is used as one of the elements for which the

2802 maximum is determined, unlike for the default argument Python's max

2803 function, which is only used for empty iterables.

2804

2805 >>> np.max([5], initial=6)

2806 6

2807 >>> max([5], default=6)

2808 5

2809 """

2810 return _wrapreduction(a, np.maximum, 'max', axis, None, out,

2811 keepdims=keepdims, initial=initial, where=where)

2812

2813

2814@array_function_dispatch(_max_dispatcher)

2815def amax(a, axis=None, out=None, keepdims=np._NoValue, initial=np._NoValue,

2816 where=np._NoValue):

2817 """

2818 Return the maximum of an array or maximum along an axis.

2819

2820 `amax` is an alias of `~numpy.max`.

2821

2822 See Also

2823 --------

2824 max : alias of this function

2825 ndarray.max : equivalent method

2826 """

2827 return _wrapreduction(a, np.maximum, 'max', axis, None, out,

2828 keepdims=keepdims, initial=initial, where=where)

2829

2830

2831def _min_dispatcher(a, axis=None, out=None, keepdims=None, initial=None,

2832 where=None):

2833 return (a, out)

2834

2835

2836@array_function_dispatch(_min_dispatcher)

2837def min(a, axis=None, out=None, keepdims=np._NoValue, initial=np._NoValue,

2838 where=np._NoValue):

2839 """

2840 Return the minimum of an array or minimum along an axis.

2841

2842 Parameters

2843 ----------

2844 a : array_like

2845 Input data.

2846 axis : None or int or tuple of ints, optional

2847 Axis or axes along which to operate. By default, flattened input is

2848 used.

2849

2850 .. versionadded:: 1.7.0

2851

2852 If this is a tuple of ints, the minimum is selected over multiple axes,

2853 instead of a single axis or all the axes as before.

2854 out : ndarray, optional

2855 Alternative output array in which to place the result. Must

2856 be of the same shape and buffer length as the expected output.

2857 See :ref:`ufuncs-output-type` for more details.

2858

2859 keepdims : bool, optional

2860 If this is set to True, the axes which are reduced are left

2861 in the result as dimensions with size one. With this option,

2862 the result will broadcast correctly against the input array.

2863

2864 If the default value is passed, then `keepdims` will not be

2865 passed through to the ``min`` method of sub-classes of

2866 `ndarray`, however any non-default value will be. If the

2867 sub-class' method does not implement `keepdims` any

2868 exceptions will be raised.

2869

2870 initial : scalar, optional

2871 The maximum value of an output element. Must be present to allow

2872 computation on empty slice. See `~numpy.ufunc.reduce` for details.

2873

2874 .. versionadded:: 1.15.0

2875

2876 where : array_like of bool, optional

2877 Elements to compare for the minimum. See `~numpy.ufunc.reduce`

2878 for details.

2879

2880 .. versionadded:: 1.17.0

2881

2882 Returns

2883 -------

2884 min : ndarray or scalar

2885 Minimum of `a`. If `axis` is None, the result is a scalar value.

2886 If `axis` is an int, the result is an array of dimension

2887 ``a.ndim - 1``. If `axis` is a tuple, the result is an array of

2888 dimension ``a.ndim - len(axis)``.

2889

2890 See Also

2891 --------

2892 amax :

2893 The maximum value of an array along a given axis, propagating any NaNs.

2894 nanmin :

2895 The minimum value of an array along a given axis, ignoring any NaNs.

2896 minimum :

2897 Element-wise minimum of two arrays, propagating any NaNs.

2898 fmin :

2899 Element-wise minimum of two arrays, ignoring any NaNs.

2900 argmin :

2901 Return the indices of the minimum values.

2902

2903 nanmax, maximum, fmax

2904

2905 Notes

2906 -----

2907 NaN values are propagated, that is if at least one item is NaN, the

2908 corresponding min value will be NaN as well. To ignore NaN values

2909 (MATLAB behavior), please use nanmin.

2910

2911 Don't use `~numpy.min` for element-wise comparison of 2 arrays; when

2912 ``a.shape[0]`` is 2, ``minimum(a[0], a[1])`` is faster than

2913 ``min(a, axis=0)``.

2914

2915 Examples

2916 --------

2917 >>> a = np.arange(4).reshape((2,2))

2918 >>> a

2919 array([[0, 1],

2920 [2, 3]])

2921 >>> np.min(a) # Minimum of the flattened array

2922 0

2923 >>> np.min(a, axis=0) # Minima along the first axis

2924 array([0, 1])

2925 >>> np.min(a, axis=1) # Minima along the second axis

2926 array([0, 2])

2927 >>> np.min(a, where=[False, True], initial=10, axis=0)

2928 array([10, 1])

2929

2930 >>> b = np.arange(5, dtype=float)

2931 >>> b[2] = np.NaN

2932 >>> np.min(b)

2933 nan

2934 >>> np.min(b, where=~np.isnan(b), initial=10)

2935 0.0

2936 >>> np.nanmin(b)

2937 0.0

2938

2939 >>> np.min([[-50], [10]], axis=-1, initial=0)

2940 array([-50, 0])

2941

2942 Notice that the initial value is used as one of the elements for which the

2943 minimum is determined, unlike for the default argument Python's max

2944 function, which is only used for empty iterables.

2945

2946 Notice that this isn't the same as Python's ``default`` argument.

2947

2948 >>> np.min([6], initial=5)

2949 5

2950 >>> min([6], default=5)

2951 6

2952 """

2953 return _wrapreduction(a, np.minimum, 'min', axis, None, out,

2954 keepdims=keepdims, initial=initial, where=where)

2955

2956

2957@array_function_dispatch(_min_dispatcher)

2958def amin(a, axis=None, out=None, keepdims=np._NoValue, initial=np._NoValue,

2959 where=np._NoValue):

2960 """

2961 Return the minimum of an array or minimum along an axis.

2962

2963 `amin` is an alias of `~numpy.min`.

2964

2965 See Also

2966 --------

2967 min : alias of this function

2968 ndarray.min : equivalent method

2969 """

2970 return _wrapreduction(a, np.minimum, 'min', axis, None, out,

2971 keepdims=keepdims, initial=initial, where=where)

2972

2973

2974def _prod_dispatcher(a, axis=None, dtype=None, out=None, keepdims=None,

2975 initial=None, where=None):

2976 return (a, out)

2977

2978

2979@array_function_dispatch(_prod_dispatcher)

2980def prod(a, axis=None, dtype=None, out=None, keepdims=np._NoValue,

2981 initial=np._NoValue, where=np._NoValue):

2982 """

2983 Return the product of array elements over a given axis.

2984

2985 Parameters

2986 ----------

2987 a : array_like

2988 Input data.

2989 axis : None or int or tuple of ints, optional

2990 Axis or axes along which a product is performed. The default,

2991 axis=None, will calculate the product of all the elements in the

2992 input array. If axis is negative it counts from the last to the

2993 first axis.

2994

2995 .. versionadded:: 1.7.0

2996

2997 If axis is a tuple of ints, a product is performed on all of the

2998 axes specified in the tuple instead of a single axis or all the

2999 axes as before.

3000 dtype : dtype, optional

3001 The type of the returned array, as well as of the accumulator in

3002 which the elements are multiplied. The dtype of `a` is used by

3003 default unless `a` has an integer dtype of less precision than the

3004 default platform integer. In that case, if `a` is signed then the

3005 platform integer is used while if `a` is unsigned then an unsigned

3006 integer of the same precision as the platform integer is used.

3007 out : ndarray, optional

3008 Alternative output array in which to place the result. It must have

3009 the same shape as the expected output, but the type of the output

3010 values will be cast if necessary.

3011 keepdims : bool, optional

3012 If this is set to True, the axes which are reduced are left in the

3013 result as dimensions with size one. With this option, the result

3014 will broadcast correctly against the input array.

3015

3016 If the default value is passed, then `keepdims` will not be

3017 passed through to the `prod` method of sub-classes of

3018 `ndarray`, however any non-default value will be. If the

3019 sub-class' method does not implement `keepdims` any

3020 exceptions will be raised.

3021 initial : scalar, optional

3022 The starting value for this product. See `~numpy.ufunc.reduce` for details.

3023

3024 .. versionadded:: 1.15.0

3025

3026 where : array_like of bool, optional

3027 Elements to include in the product. See `~numpy.ufunc.reduce` for details.

3028

3029 .. versionadded:: 1.17.0

3030

3031 Returns

3032 -------

3033 product_along_axis : ndarray, see `dtype` parameter above.

3034 An array shaped as `a` but with the specified axis removed.

3035 Returns a reference to `out` if specified.

3036

3037 See Also

3038 --------

3039 ndarray.prod : equivalent method

3040 :ref:`ufuncs-output-type`

3041

3042 Notes

3043 -----

3044 Arithmetic is modular when using integer types, and no error is

3045 raised on overflow. That means that, on a 32-bit platform:

3046

3047 >>> x = np.array([536870910, 536870910, 536870910, 536870910])

3048 >>> np.prod(x)

3049 16 # may vary

3050

3051 The product of an empty array is the neutral element 1:

3052

3053 >>> np.prod([])

3054 1.0

3055

3056 Examples

3057 --------

3058 By default, calculate the product of all elements:

3059

3060 >>> np.prod([1.,2.])

3061 2.0

3062

3063 Even when the input array is two-dimensional:

3064

3065 >>> a = np.array([[1., 2.], [3., 4.]])

3066 >>> np.prod(a)

3067 24.0

3068

3069 But we can also specify the axis over which to multiply:

3070

3071 >>> np.prod(a, axis=1)

3072 array([ 2., 12.])

3073 >>> np.prod(a, axis=0)

3074 array([3., 8.])

3075

3076 Or select specific elements to include:

3077

3078 >>> np.prod([1., np.nan, 3.], where=[True, False, True])

3079 3.0

3080

3081 If the type of `x` is unsigned, then the output type is

3082 the unsigned platform integer:

3083

3084 >>> x = np.array([1, 2, 3], dtype=np.uint8)

3085 >>> np.prod(x).dtype == np.uint

3086 True

3087

3088 If `x` is of a signed integer type, then the output type

3089 is the default platform integer:

3090

3091 >>> x = np.array([1, 2, 3], dtype=np.int8)

3092 >>> np.prod(x).dtype == int

3093 True

3094

3095 You can also start the product with a value other than one:

3096

3097 >>> np.prod([1, 2], initial=5)

3098 10

3099 """

3100 return _wrapreduction(a, np.multiply, 'prod', axis, dtype, out,

3101 keepdims=keepdims, initial=initial, where=where)

3102

3103

3104def _cumprod_dispatcher(a, axis=None, dtype=None, out=None):

3105 return (a, out)

3106

3107

3108@array_function_dispatch(_cumprod_dispatcher)

3109def cumprod(a, axis=None, dtype=None, out=None):

3110 """

3111 Return the cumulative product of elements along a given axis.

3112

3113 Parameters

3114 ----------

3115 a : array_like

3116 Input array.

3117 axis : int, optional

3118 Axis along which the cumulative product is computed. By default

3119 the input is flattened.

3120 dtype : dtype, optional

3121 Type of the returned array, as well as of the accumulator in which

3122 the elements are multiplied. If *dtype* is not specified, it

3123 defaults to the dtype of `a`, unless `a` has an integer dtype with

3124 a precision less than that of the default platform integer. In

3125 that case, the default platform integer is used instead.

3126 out : ndarray, optional

3127 Alternative output array in which to place the result. It must

3128 have the same shape and buffer length as the expected output

3129 but the type of the resulting values will be cast if necessary.

3130

3131 Returns

3132 -------

3133 cumprod : ndarray

3134 A new array holding the result is returned unless `out` is

3135 specified, in which case a reference to out is returned.

3136

3137 See Also

3138 --------

3139 :ref:`ufuncs-output-type`

3140

3141 Notes

3142 -----

3143 Arithmetic is modular when using integer types, and no error is

3144 raised on overflow.

3145

3146 Examples

3147 --------

3148 >>> a = np.array([1,2,3])

3149 >>> np.cumprod(a) # intermediate results 1, 1*2

3150 ... # total product 1*2*3 = 6

3151 array([1, 2, 6])

3152 >>> a = np.array([[1, 2, 3], [4, 5, 6]])

3153 >>> np.cumprod(a, dtype=float) # specify type of output

3154 array([ 1., 2., 6., 24., 120., 720.])

3155

3156 The cumulative product for each column (i.e., over the rows) of `a`:

3157

3158 >>> np.cumprod(a, axis=0)

3159 array([[ 1, 2, 3],

3160 [ 4, 10, 18]])

3161

3162 The cumulative product for each row (i.e. over the columns) of `a`:

3163

3164 >>> np.cumprod(a,axis=1)

3165 array([[ 1, 2, 6],

3166 [ 4, 20, 120]])

3167

3168 """

3169 return _wrapfunc(a, 'cumprod', axis=axis, dtype=dtype, out=out)

3170

3171

3172def _ndim_dispatcher(a):

3173 return (a,)

3174

3175

3176@array_function_dispatch(_ndim_dispatcher)

3177def ndim(a):

3178 """

3179 Return the number of dimensions of an array.

3180

3181 Parameters

3182 ----------

3183 a : array_like

3184 Input array. If it is not already an ndarray, a conversion is

3185 attempted.

3186

3187 Returns

3188 -------

3189 number_of_dimensions : int

3190 The number of dimensions in `a`. Scalars are zero-dimensional.

3191

3192 See Also

3193 --------

3194 ndarray.ndim : equivalent method

3195 shape : dimensions of array

3196 ndarray.shape : dimensions of array

3197

3198 Examples

3199 --------

3200 >>> np.ndim([[1,2,3],[4,5,6]])

3201 2

3202 >>> np.ndim(np.array([[1,2,3],[4,5,6]]))

3203 2

3204 >>> np.ndim(1)

3205 0

3206

3207 """

3208 try:

3209 return a.ndim

3210 except AttributeError:

3211 return asarray(a).ndim

3212

3213

3214def _size_dispatcher(a, axis=None):

3215 return (a,)

3216

3217

3218@array_function_dispatch(_size_dispatcher)

3219def size(a, axis=None):

3220 """

3221 Return the number of elements along a given axis.

3222

3223 Parameters

3224 ----------

3225 a : array_like

3226 Input data.

3227 axis : int, optional

3228 Axis along which the elements are counted. By default, give

3229 the total number of elements.

3230

3231 Returns

3232 -------

3233 element_count : int

3234 Number of elements along the specified axis.

3235

3236 See Also

3237 --------

3238 shape : dimensions of array

3239 ndarray.shape : dimensions of array

3240 ndarray.size : number of elements in array

3241

3242 Examples

3243 --------

3244 >>> a = np.array([[1,2,3],[4,5,6]])

3245 >>> np.size(a)

3246 6

3247 >>> np.size(a,1)

3248 3

3249 >>> np.size(a,0)

3250 2

3251

3252 """

3253 if axis is None:

3254 try:

3255 return a.size

3256 except AttributeError:

3257 return asarray(a).size

3258 else:

3259 try:

3260 return a.shape[axis]

3261 except AttributeError:

3262 return asarray(a).shape[axis]

3263

3264

3265def _round_dispatcher(a, decimals=None, out=None):

3266 return (a, out)

3267

3268

3269@array_function_dispatch(_round_dispatcher)

3270def round(a, decimals=0, out=None):

3271 """

3272 Evenly round to the given number of decimals.

3273

3274 Parameters

3275 ----------

3276 a : array_like

3277 Input data.

3278 decimals : int, optional

3279 Number of decimal places to round to (default: 0). If

3280 decimals is negative, it specifies the number of positions to

3281 the left of the decimal point.

3282 out : ndarray, optional

3283 Alternative output array in which to place the result. It must have

3284 the same shape as the expected output, but the type of the output

3285 values will be cast if necessary. See :ref:`ufuncs-output-type` for more

3286 details.

3287

3288 Returns

3289 -------

3290 rounded_array : ndarray

3291 An array of the same type as `a`, containing the rounded values.

3292 Unless `out` was specified, a new array is created. A reference to

3293 the result is returned.

3294

3295 The real and imaginary parts of complex numbers are rounded

3296 separately. The result of rounding a float is a float.

3297

3298 See Also

3299 --------

3300 ndarray.round : equivalent method

3301 around : an alias for this function

3302 ceil, fix, floor, rint, trunc

3303

3304

3305 Notes

3306 -----

3307 For values exactly halfway between rounded decimal values, NumPy

3308 rounds to the nearest even value. Thus 1.5 and 2.5 round to 2.0,

3309 -0.5 and 0.5 round to 0.0, etc.

3310

3311 ``np.round`` uses a fast but sometimes inexact algorithm to round

3312 floating-point datatypes. For positive `decimals` it is equivalent to

3313 ``np.true_divide(np.rint(a * 10**decimals), 10**decimals)``, which has

3314 error due to the inexact representation of decimal fractions in the IEEE

3315 floating point standard [1]_ and errors introduced when scaling by powers

3316 of ten. For instance, note the extra "1" in the following:

3317

3318 >>> np.round(56294995342131.5, 3)

3319 56294995342131.51

3320

3321 If your goal is to print such values with a fixed number of decimals, it is

3322 preferable to use numpy's float printing routines to limit the number of

3323 printed decimals:

3324

3325 >>> np.format_float_positional(56294995342131.5, precision=3)

3326 '56294995342131.5'

3327

3328 The float printing routines use an accurate but much more computationally

3329 demanding algorithm to compute the number of digits after the decimal

3330 point.

3331

3332 Alternatively, Python's builtin `round` function uses a more accurate

3333 but slower algorithm for 64-bit floating point values:

3334

3335 >>> round(56294995342131.5, 3)

3336 56294995342131.5

3337 >>> np.round(16.055, 2), round(16.055, 2) # equals 16.0549999999999997

3338 (16.06, 16.05)

3339

3340

3341 References

3342 ----------

3343 .. [1] "Lecture Notes on the Status of IEEE 754", William Kahan,

3344 https://people.eecs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF

3345

3346 Examples

3347 --------

3348 >>> np.round([0.37, 1.64])

3349 array([0., 2.])

3350 >>> np.round([0.37, 1.64], decimals=1)

3351 array([0.4, 1.6])

3352 >>> np.round([.5, 1.5, 2.5, 3.5, 4.5]) # rounds to nearest even value

3353 array([0., 2., 2., 4., 4.])

3354 >>> np.round([1,2,3,11], decimals=1) # ndarray of ints is returned

3355 array([ 1, 2, 3, 11])

3356 >>> np.round([1,2,3,11], decimals=-1)

3357 array([ 0, 0, 0, 10])

3358

3359 """

3360 return _wrapfunc(a, 'round', decimals=decimals, out=out)

3361

3362

3363@array_function_dispatch(_round_dispatcher)

3364def around(a, decimals=0, out=None):

3365 """

3366 Round an array to the given number of decimals.

3367

3368 `around` is an alias of `~numpy.round`.

3369

3370 See Also

3371 --------

3372 ndarray.round : equivalent method

3373 round : alias for this function

3374 ceil, fix, floor, rint, trunc

3375

3376 """

3377 return _wrapfunc(a, 'round', decimals=decimals, out=out)

3378

3379

3380def _mean_dispatcher(a, axis=None, dtype=None, out=None, keepdims=None, *,

3381 where=None):

3382 return (a, where, out)

3383

3384

3385@array_function_dispatch(_mean_dispatcher)

3386def mean(a, axis=None, dtype=None, out=None, keepdims=np._NoValue, *,

3387 where=np._NoValue):

3388 """

3389 Compute the arithmetic mean along the specified axis.

3390

3391 Returns the average of the array elements. The average is taken over

3392 the flattened array by default, otherwise over the specified axis.

3393 `float64` intermediate and return values are used for integer inputs.

3394

3395 Parameters

3396 ----------

3397 a : array_like

3398 Array containing numbers whose mean is desired. If `a` is not an

3399 array, a conversion is attempted.

3400 axis : None or int or tuple of ints, optional

3401 Axis or axes along which the means are computed. The default is to

3402 compute the mean of the flattened array.

3403

3404 .. versionadded:: 1.7.0

3405

3406 If this is a tuple of ints, a mean is performed over multiple axes,

3407 instead of a single axis or all the axes as before.

3408 dtype : data-type, optional

3409 Type to use in computing the mean. For integer inputs, the default

3410 is `float64`; for floating point inputs, it is the same as the

3411 input dtype.

3412 out : ndarray, optional

3413 Alternate output array in which to place the result. The default

3414 is ``None``; if provided, it must have the same shape as the

3415 expected output, but the type will be cast if necessary.

3416 See :ref:`ufuncs-output-type` for more details.

3417

3418 keepdims : bool, optional

3419 If this is set to True, the axes which are reduced are left

3420 in the result as dimensions with size one. With this option,

3421 the result will broadcast correctly against the input array.

3422

3423 If the default value is passed, then `keepdims` will not be

3424 passed through to the `mean` method of sub-classes of

3425 `ndarray`, however any non-default value will be. If the

3426 sub-class' method does not implement `keepdims` any

3427 exceptions will be raised.

3428

3429 where : array_like of bool, optional

3430 Elements to include in the mean. See `~numpy.ufunc.reduce` for details.

3431

3432 .. versionadded:: 1.20.0

3433

3434 Returns

3435 -------

3436 m : ndarray, see dtype parameter above

3437 If `out=None`, returns a new array containing the mean values,

3438 otherwise a reference to the output array is returned.

3439

3440 See Also

3441 --------

3442 average : Weighted average

3443 std, var, nanmean, nanstd, nanvar

3444

3445 Notes

3446 -----

3447 The arithmetic mean is the sum of the elements along the axis divided

3448 by the number of elements.

3449

3450 Note that for floating-point input, the mean is computed using the

3451 same precision the input has. Depending on the input data, this can

3452 cause the results to be inaccurate, especially for `float32` (see

3453 example below). Specifying a higher-precision accumulator using the

3454 `dtype` keyword can alleviate this issue.

3455

3456 By default, `float16` results are computed using `float32` intermediates

3457 for extra precision.

3458

3459 Examples

3460 --------

3461 >>> a = np.array([[1, 2], [3, 4]])

3462 >>> np.mean(a)

3463 2.5

3464 >>> np.mean(a, axis=0)

3465 array([2., 3.])

3466 >>> np.mean(a, axis=1)

3467 array([1.5, 3.5])

3468

3469 In single precision, `mean` can be inaccurate:

3470

3471 >>> a = np.zeros((2, 512*512), dtype=np.float32)

3472 >>> a[0, :] = 1.0

3473 >>> a[1, :] = 0.1

3474 >>> np.mean(a)

3475 0.54999924

3476

3477 Computing the mean in float64 is more accurate:

3478

3479 >>> np.mean(a, dtype=np.float64)

3480 0.55000000074505806 # may vary

3481

3482 Specifying a where argument:

3483

3484 >>> a = np.array([[5, 9, 13], [14, 10, 12], [11, 15, 19]])

3485 >>> np.mean(a)

3486 12.0

3487 >>> np.mean(a, where=[[True], [False], [False]])

3488 9.0

3489

3490 """

3491 kwargs = {}

3492 if keepdims is not np._NoValue:

3493 kwargs['keepdims'] = keepdims

3494 if where is not np._NoValue:

3495 kwargs['where'] = where

3496 if type(a) is not mu.ndarray:

3497 try:

3498 mean = a.mean

3499 except AttributeError:

3500 pass

3501 else:

3502 return mean(axis=axis, dtype=dtype, out=out, **kwargs)

3503

3504 return _methods._mean(a, axis=axis, dtype=dtype,

3505 out=out, **kwargs)

3506

3507

3508def _std_dispatcher(a, axis=None, dtype=None, out=None, ddof=None,

3509 keepdims=None, *, where=None):

3510 return (a, where, out)

3511

3512

3513@array_function_dispatch(_std_dispatcher)

3514def std(a, axis=None, dtype=None, out=None, ddof=0, keepdims=np._NoValue, *,

3515 where=np._NoValue):

3516 """

3517 Compute the standard deviation along the specified axis.

3518

3519 Returns the standard deviation, a measure of the spread of a distribution,

3520 of the array elements. The standard deviation is computed for the

3521 flattened array by default, otherwise over the specified axis.

3522

3523 Parameters

3524 ----------

3525 a : array_like

3526 Calculate the standard deviation of these values.

3527 axis : None or int or tuple of ints, optional

3528 Axis or axes along which the standard deviation is computed. The

3529 default is to compute the standard deviation of the flattened array.

3530

3531 .. versionadded:: 1.7.0

3532

3533 If this is a tuple of ints, a standard deviation is performed over

3534 multiple axes, instead of a single axis or all the axes as before.

3535 dtype : dtype, optional

3536 Type to use in computing the standard deviation. For arrays of

3537 integer type the default is float64, for arrays of float types it is

3538 the same as the array type.

3539 out : ndarray, optional

3540 Alternative output array in which to place the result. It must have

3541 the same shape as the expected output but the type (of the calculated

3542 values) will be cast if necessary.

3543 ddof : int, optional

3544 Means Delta Degrees of Freedom. The divisor used in calculations

3545 is ``N - ddof``, where ``N`` represents the number of elements.

3546 By default `ddof` is zero.

3547 keepdims : bool, optional

3548 If this is set to True, the axes which are reduced are left

3549 in the result as dimensions with size one. With this option,

3550 the result will broadcast correctly against the input array.

3551

3552 If the default value is passed, then `keepdims` will not be

3553 passed through to the `std` method of sub-classes of

3554 `ndarray`, however any non-default value will be. If the

3555 sub-class' method does not implement `keepdims` any

3556 exceptions will be raised.

3557

3558 where : array_like of bool, optional

3559 Elements to include in the standard deviation.

3560 See `~numpy.ufunc.reduce` for details.

3561

3562 .. versionadded:: 1.20.0

3563

3564 Returns

3565 -------

3566 standard_deviation : ndarray, see dtype parameter above.

3567 If `out` is None, return a new array containing the standard deviation,

3568 otherwise return a reference to the output array.

3569

3570 See Also

3571 --------

3572 var, mean, nanmean, nanstd, nanvar

3573 :ref:`ufuncs-output-type`

3574

3575 Notes

3576 -----

3577 The standard deviation is the square root of the average of the squared

3578 deviations from the mean, i.e., ``std = sqrt(mean(x))``, where

3579 ``x = abs(a - a.mean())**2``.

3580

3581 The average squared deviation is typically calculated as ``x.sum() / N``,

3582 where ``N = len(x)``. If, however, `ddof` is specified, the divisor

3583 ``N - ddof`` is used instead. In standard statistical practice, ``ddof=1``

3584 provides an unbiased estimator of the variance of the infinite population.

3585 ``ddof=0`` provides a maximum likelihood estimate of the variance for

3586 normally distributed variables. The standard deviation computed in this

3587 function is the square root of the estimated variance, so even with

3588 ``ddof=1``, it will not be an unbiased estimate of the standard deviation

3589 per se.

3590

3591 Note that, for complex numbers, `std` takes the absolute

3592 value before squaring, so that the result is always real and nonnegative.

3593

3594 For floating-point input, the *std* is computed using the same

3595 precision the input has. Depending on the input data, this can cause

3596 the results to be inaccurate, especially for float32 (see example below).

3597 Specifying a higher-accuracy accumulator using the `dtype` keyword can

3598 alleviate this issue.

3599

3600 Examples

3601 --------

3602 >>> a = np.array([[1, 2], [3, 4]])

3603 >>> np.std(a)

3604 1.1180339887498949 # may vary

3605 >>> np.std(a, axis=0)

3606 array([1., 1.])

3607 >>> np.std(a, axis=1)

3608 array([0.5, 0.5])

3609

3610 In single precision, std() can be inaccurate:

3611

3612 >>> a = np.zeros((2, 512*512), dtype=np.float32)

3613 >>> a[0, :] = 1.0

3614 >>> a[1, :] = 0.1

3615 >>> np.std(a)

3616 0.45000005

3617

3618 Computing the standard deviation in float64 is more accurate:

3619

3620 >>> np.std(a, dtype=np.float64)

3621 0.44999999925494177 # may vary

3622

3623 Specifying a where argument:

3624

3625 >>> a = np.array([[14, 8, 11, 10], [7, 9, 10, 11], [10, 15, 5, 10]])

3626 >>> np.std(a)

3627 2.614064523559687 # may vary

3628 >>> np.std(a, where=[[True], [True], [False]])

3629 2.0

3630

3631 """

3632 kwargs = {}

3633 if keepdims is not np._NoValue:

3634 kwargs['keepdims'] = keepdims

3635 if where is not np._NoValue:

3636 kwargs['where'] = where

3637 if type(a) is not mu.ndarray:

3638 try:

3639 std = a.std

3640 except AttributeError:

3641 pass

3642 else:

3643 return std(axis=axis, dtype=dtype, out=out, ddof=ddof, **kwargs)

3644

3645 return _methods._std(a, axis=axis, dtype=dtype, out=out, ddof=ddof,

3646 **kwargs)

3647

3648

3649def _var_dispatcher(a, axis=None, dtype=None, out=None, ddof=None,

3650 keepdims=None, *, where=None):

3651 return (a, where, out)

3652

3653

3654@array_function_dispatch(_var_dispatcher)

3655def var(a, axis=None, dtype=None, out=None, ddof=0, keepdims=np._NoValue, *,

3656 where=np._NoValue):

3657 """

3658 Compute the variance along the specified axis.

3659

3660 Returns the variance of the array elements, a measure of the spread of a

3661 distribution. The variance is computed for the flattened array by

3662 default, otherwise over the specified axis.

3663

3664 Parameters

3665 ----------

3666 a : array_like

3667 Array containing numbers whose variance is desired. If `a` is not an

3668 array, a conversion is attempted.

3669 axis : None or int or tuple of ints, optional

3670 Axis or axes along which the variance is computed. The default is to

3671 compute the variance of the flattened array.

3672

3673 .. versionadded:: 1.7.0

3674

3675 If this is a tuple of ints, a variance is performed over multiple axes,

3676 instead of a single axis or all the axes as before.

3677 dtype : data-type, optional

3678 Type to use in computing the variance. For arrays of integer type

3679 the default is `float64`; for arrays of float types it is the same as

3680 the array type.

3681 out : ndarray, optional

3682 Alternate output array in which to place the result. It must have

3683 the same shape as the expected output, but the type is cast if

3684 necessary.

3685 ddof : int, optional

3686 "Delta Degrees of Freedom": the divisor used in the calculation is

3687 ``N - ddof``, where ``N`` represents the number of elements. By

3688 default `ddof` is zero.

3689 keepdims : bool, optional

3690 If this is set to True, the axes which are reduced are left

3691 in the result as dimensions with size one. With this option,

3692 the result will broadcast correctly against the input array.

3693

3694 If the default value is passed, then `keepdims` will not be

3695 passed through to the `var` method of sub-classes of

3696 `ndarray`, however any non-default value will be. If the

3697 sub-class' method does not implement `keepdims` any

3698 exceptions will be raised.

3699

3700 where : array_like of bool, optional

3701 Elements to include in the variance. See `~numpy.ufunc.reduce` for

3702 details.

3703

3704 .. versionadded:: 1.20.0

3705

3706 Returns

3707 -------

3708 variance : ndarray, see dtype parameter above

3709 If ``out=None``, returns a new array containing the variance;

3710 otherwise, a reference to the output array is returned.

3711

3712 See Also

3713 --------

3714 std, mean, nanmean, nanstd, nanvar

3715 :ref:`ufuncs-output-type`

3716

3717 Notes

3718 -----

3719 The variance is the average of the squared deviations from the mean,

3720 i.e., ``var = mean(x)``, where ``x = abs(a - a.mean())**2``.

3721

3722 The mean is typically calculated as ``x.sum() / N``, where ``N = len(x)``.

3723 If, however, `ddof` is specified, the divisor ``N - ddof`` is used

3724 instead. In standard statistical practice, ``ddof=1`` provides an

3725 unbiased estimator of the variance of a hypothetical infinite population.

3726 ``ddof=0`` provides a maximum likelihood estimate of the variance for

3727 normally distributed variables.

3728

3729 Note that for complex numbers, the absolute value is taken before

3730 squaring, so that the result is always real and nonnegative.

3731

3732 For floating-point input, the variance is computed using the same

3733 precision the input has. Depending on the input data, this can cause

3734 the results to be inaccurate, especially for `float32` (see example

3735 below). Specifying a higher-accuracy accumulator using the ``dtype``

3736 keyword can alleviate this issue.

3737

3738 Examples

3739 --------

3740 >>> a = np.array([[1, 2], [3, 4]])

3741 >>> np.var(a)

3742 1.25

3743 >>> np.var(a, axis=0)

3744 array([1., 1.])

3745 >>> np.var(a, axis=1)

3746 array([0.25, 0.25])

3747

3748 In single precision, var() can be inaccurate:

3749

3750 >>> a = np.zeros((2, 512*512), dtype=np.float32)

3751 >>> a[0, :] = 1.0

3752 >>> a[1, :] = 0.1

3753 >>> np.var(a)

3754 0.20250003

3755

3756 Computing the variance in float64 is more accurate:

3757

3758 >>> np.var(a, dtype=np.float64)

3759 0.20249999932944759 # may vary

3760 >>> ((1-0.55)**2 + (0.1-0.55)**2)/2

3761 0.2025

3762

3763 Specifying a where argument:

3764

3765 >>> a = np.array([[14, 8, 11, 10], [7, 9, 10, 11], [10, 15, 5, 10]])

3766 >>> np.var(a)

3767 6.833333333333333 # may vary

3768 >>> np.var(a, where=[[True], [True], [False]])

3769 4.0

3770

3771 """

3772 kwargs = {}

3773 if keepdims is not np._NoValue:

3774 kwargs['keepdims'] = keepdims

3775 if where is not np._NoValue:

3776 kwargs['where'] = where

3777

3778 if type(a) is not mu.ndarray:

3779 try:

3780 var = a.var

3781

3782 except AttributeError:

3783 pass

3784 else:

3785 return var(axis=axis, dtype=dtype, out=out, ddof=ddof, **kwargs)

3786

3787 return _methods._var(a, axis=axis, dtype=dtype, out=out, ddof=ddof,

3788 **kwargs)

3789

3790

3791# Aliases of other functions. Provided unique docstrings

3792# are for reference purposes only. Wherever possible,

3793# avoid using them.

3794

3795

3796def _round__dispatcher(a, decimals=None, out=None):

3797 # 2023-02-28, 1.25.0

3798 warnings.warn("`round_` is deprecated as of NumPy 1.25.0, and will be "

3799 "removed in NumPy 2.0. Please use `round` instead.",

3800 DeprecationWarning, stacklevel=3)

3801 return (a, out)

3802

3803

3804@array_function_dispatch(_round__dispatcher)

3805def round_(a, decimals=0, out=None):

3806 """

3807 Round an array to the given number of decimals.

3808

3809 `~numpy.round_` is a disrecommended backwards-compatibility

3810 alias of `~numpy.around` and `~numpy.round`.

3811

3812 .. deprecated:: 1.25.0

3813 ``round_`` is deprecated as of NumPy 1.25.0, and will be

3814 removed in NumPy 2.0. Please use `round` instead.

3815

3816 See Also

3817 --------

3818 around : equivalent function; see for details.

3819 """

3820 return around(a, decimals=decimals, out=out)

3821

3822

3823def _product_dispatcher(a, axis=None, dtype=None, out=None, keepdims=None,

3824 initial=None, where=None):

3825 # 2023-03-02, 1.25.0

3826 warnings.warn("`product` is deprecated as of NumPy 1.25.0, and will be "

3827 "removed in NumPy 2.0. Please use `prod` instead.",

3828 DeprecationWarning, stacklevel=3)

3829 return (a, out)

3830

3831

3832@array_function_dispatch(_product_dispatcher, verify=False)

3833def product(*args, **kwargs):

3834 """

3835 Return the product of array elements over a given axis.

3836

3837 .. deprecated:: 1.25.0

3838 ``product`` is deprecated as of NumPy 1.25.0, and will be

3839 removed in NumPy 2.0. Please use `prod` instead.

3840

3841 See Also

3842 --------

3843 prod : equivalent function; see for details.

3844 """

3845 return prod(*args, **kwargs)

3846

3847

3848def _cumproduct_dispatcher(a, axis=None, dtype=None, out=None):

3849 # 2023-03-02, 1.25.0

3850 warnings.warn("`cumproduct` is deprecated as of NumPy 1.25.0, and will be "

3851 "removed in NumPy 2.0. Please use `cumprod` instead.",

3852 DeprecationWarning, stacklevel=3)

3853 return (a, out)

3854

3855

3856@array_function_dispatch(_cumproduct_dispatcher, verify=False)

3857def cumproduct(*args, **kwargs):

3858 """

3859 Return the cumulative product over the given axis.

3860

3861 .. deprecated:: 1.25.0

3862 ``cumproduct`` is deprecated as of NumPy 1.25.0, and will be

3863 removed in NumPy 2.0. Please use `cumprod` instead.

3864

3865 See Also

3866 --------

3867 cumprod : equivalent function; see for details.

3868 """

3869 return cumprod(*args, **kwargs)

3870

3871

3872def _sometrue_dispatcher(a, axis=None, out=None, keepdims=None, *,

3873 where=np._NoValue):

3874 # 2023-03-02, 1.25.0

3875 warnings.warn("`sometrue` is deprecated as of NumPy 1.25.0, and will be "

3876 "removed in NumPy 2.0. Please use `any` instead.",

3877 DeprecationWarning, stacklevel=3)

3878 return (a, where, out)

3879

3880

3881@array_function_dispatch(_sometrue_dispatcher, verify=False)

3882def sometrue(*args, **kwargs):

3883 """

3884 Check whether some values are true.

3885

3886 Refer to `any` for full documentation.

3887

3888 .. deprecated:: 1.25.0

3889 ``sometrue`` is deprecated as of NumPy 1.25.0, and will be

3890 removed in NumPy 2.0. Please use `any` instead.

3891

3892 See Also

3893 --------

3894 any : equivalent function; see for details.

3895 """

3896 return any(*args, **kwargs)

3897

3898

3899def _alltrue_dispatcher(a, axis=None, out=None, keepdims=None, *, where=None):

3900 # 2023-03-02, 1.25.0

3901 warnings.warn("`alltrue` is deprecated as of NumPy 1.25.0, and will be "

3902 "removed in NumPy 2.0. Please use `all` instead.",

3903 DeprecationWarning, stacklevel=3)

3904 return (a, where, out)

3905

3906

3907@array_function_dispatch(_alltrue_dispatcher, verify=False)

3908def alltrue(*args, **kwargs):

3909 """

3910 Check if all elements of input array are true.

3911

3912 .. deprecated:: 1.25.0

3913 ``alltrue`` is deprecated as of NumPy 1.25.0, and will be

3914 removed in NumPy 2.0. Please use `all` instead.

3915

3916 See Also

3917 --------

3918 numpy.all : Equivalent function; see for details.

3919 """

3920 return all(*args, **kwargs)