3599 lines
113 KiB
Python
3599 lines
113 KiB
Python
"""Module containing non-deprecated functions borrowed from Numeric.
|
|
|
|
"""
|
|
from __future__ import division, absolute_import, print_function
|
|
|
|
import functools
|
|
import types
|
|
import warnings
|
|
|
|
import numpy as np
|
|
from .. import VisibleDeprecationWarning
|
|
from . import multiarray as mu
|
|
from . import overrides
|
|
from . import umath as um
|
|
from . import numerictypes as nt
|
|
from ._asarray import asarray, array, asanyarray
|
|
from .multiarray import concatenate
|
|
from . import _methods
|
|
|
|
_dt_ = nt.sctype2char
|
|
|
|
# functions that are methods
|
|
__all__ = [
|
|
'alen', 'all', 'alltrue', 'amax', 'amin', 'any', 'argmax',
|
|
'argmin', 'argpartition', 'argsort', 'around', 'choose', 'clip',
|
|
'compress', 'cumprod', 'cumproduct', 'cumsum', 'diagonal', 'mean',
|
|
'ndim', 'nonzero', 'partition', 'prod', 'product', 'ptp', 'put',
|
|
'rank', 'ravel', 'repeat', 'reshape', 'resize', 'round_',
|
|
'searchsorted', 'shape', 'size', 'sometrue', 'sort', 'squeeze',
|
|
'std', 'sum', 'swapaxes', 'take', 'trace', 'transpose', 'var',
|
|
]
|
|
|
|
_gentype = types.GeneratorType
|
|
# save away Python sum
|
|
_sum_ = sum
|
|
|
|
array_function_dispatch = functools.partial(
|
|
overrides.array_function_dispatch, module='numpy')
|
|
|
|
|
|
# functions that are now methods
|
|
def _wrapit(obj, method, *args, **kwds):
|
|
try:
|
|
wrap = obj.__array_wrap__
|
|
except AttributeError:
|
|
wrap = None
|
|
result = getattr(asarray(obj), method)(*args, **kwds)
|
|
if wrap:
|
|
if not isinstance(result, mu.ndarray):
|
|
result = asarray(result)
|
|
result = wrap(result)
|
|
return result
|
|
|
|
|
|
def _wrapfunc(obj, method, *args, **kwds):
|
|
bound = getattr(obj, method, None)
|
|
if bound is None:
|
|
return _wrapit(obj, method, *args, **kwds)
|
|
|
|
try:
|
|
return bound(*args, **kwds)
|
|
except TypeError:
|
|
# A TypeError occurs if the object does have such a method in its
|
|
# class, but its signature is not identical to that of NumPy's. This
|
|
# situation has occurred in the case of a downstream library like
|
|
# 'pandas'.
|
|
#
|
|
# Call _wrapit from within the except clause to ensure a potential
|
|
# exception has a traceback chain.
|
|
return _wrapit(obj, method, *args, **kwds)
|
|
|
|
|
|
def _wrapreduction(obj, ufunc, method, axis, dtype, out, **kwargs):
|
|
passkwargs = {k: v for k, v in kwargs.items()
|
|
if v is not np._NoValue}
|
|
|
|
if type(obj) is not mu.ndarray:
|
|
try:
|
|
reduction = getattr(obj, method)
|
|
except AttributeError:
|
|
pass
|
|
else:
|
|
# This branch is needed for reductions like any which don't
|
|
# support a dtype.
|
|
if dtype is not None:
|
|
return reduction(axis=axis, dtype=dtype, out=out, **passkwargs)
|
|
else:
|
|
return reduction(axis=axis, out=out, **passkwargs)
|
|
|
|
return ufunc.reduce(obj, axis, dtype, out, **passkwargs)
|
|
|
|
|
|
def _take_dispatcher(a, indices, axis=None, out=None, mode=None):
|
|
return (a, out)
|
|
|
|
|
|
@array_function_dispatch(_take_dispatcher)
|
|
def take(a, indices, axis=None, out=None, mode='raise'):
|
|
"""
|
|
Take elements from an array along an axis.
|
|
|
|
When axis is not None, this function does the same thing as "fancy"
|
|
indexing (indexing arrays using arrays); however, it can be easier to use
|
|
if you need elements along a given axis. A call such as
|
|
``np.take(arr, indices, axis=3)`` is equivalent to
|
|
``arr[:,:,:,indices,...]``.
|
|
|
|
Explained without fancy indexing, this is equivalent to the following use
|
|
of `ndindex`, which sets each of ``ii``, ``jj``, and ``kk`` to a tuple of
|
|
indices::
|
|
|
|
Ni, Nk = a.shape[:axis], a.shape[axis+1:]
|
|
Nj = indices.shape
|
|
for ii in ndindex(Ni):
|
|
for jj in ndindex(Nj):
|
|
for kk in ndindex(Nk):
|
|
out[ii + jj + kk] = a[ii + (indices[jj],) + kk]
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like (Ni..., M, Nk...)
|
|
The source array.
|
|
indices : array_like (Nj...)
|
|
The indices of the values to extract.
|
|
|
|
.. versionadded:: 1.8.0
|
|
|
|
Also allow scalars for indices.
|
|
axis : int, optional
|
|
The axis over which to select values. By default, the flattened
|
|
input array is used.
|
|
out : ndarray, optional (Ni..., Nj..., Nk...)
|
|
If provided, the result will be placed in this array. It should
|
|
be of the appropriate shape and dtype. Note that `out` is always
|
|
buffered if `mode='raise'`; use other modes for better performance.
|
|
mode : {'raise', 'wrap', 'clip'}, optional
|
|
Specifies how out-of-bounds indices will behave.
|
|
|
|
* 'raise' -- raise an error (default)
|
|
* 'wrap' -- wrap around
|
|
* 'clip' -- clip to the range
|
|
|
|
'clip' mode means that all indices that are too large are replaced
|
|
by the index that addresses the last element along that axis. Note
|
|
that this disables indexing with negative numbers.
|
|
|
|
Returns
|
|
-------
|
|
out : ndarray (Ni..., Nj..., Nk...)
|
|
The returned array has the same type as `a`.
|
|
|
|
See Also
|
|
--------
|
|
compress : Take elements using a boolean mask
|
|
ndarray.take : equivalent method
|
|
take_along_axis : Take elements by matching the array and the index arrays
|
|
|
|
Notes
|
|
-----
|
|
|
|
By eliminating the inner loop in the description above, and using `s_` to
|
|
build simple slice objects, `take` can be expressed in terms of applying
|
|
fancy indexing to each 1-d slice::
|
|
|
|
Ni, Nk = a.shape[:axis], a.shape[axis+1:]
|
|
for ii in ndindex(Ni):
|
|
for kk in ndindex(Nj):
|
|
out[ii + s_[...,] + kk] = a[ii + s_[:,] + kk][indices]
|
|
|
|
For this reason, it is equivalent to (but faster than) the following use
|
|
of `apply_along_axis`::
|
|
|
|
out = np.apply_along_axis(lambda a_1d: a_1d[indices], axis, a)
|
|
|
|
Examples
|
|
--------
|
|
>>> a = [4, 3, 5, 7, 6, 8]
|
|
>>> indices = [0, 1, 4]
|
|
>>> np.take(a, indices)
|
|
array([4, 3, 6])
|
|
|
|
In this example if `a` is an ndarray, "fancy" indexing can be used.
|
|
|
|
>>> a = np.array(a)
|
|
>>> a[indices]
|
|
array([4, 3, 6])
|
|
|
|
If `indices` is not one dimensional, the output also has these dimensions.
|
|
|
|
>>> np.take(a, [[0, 1], [2, 3]])
|
|
array([[4, 3],
|
|
[5, 7]])
|
|
"""
|
|
return _wrapfunc(a, 'take', indices, axis=axis, out=out, mode=mode)
|
|
|
|
|
|
def _reshape_dispatcher(a, newshape, order=None):
|
|
return (a,)
|
|
|
|
|
|
# not deprecated --- copy if necessary, view otherwise
|
|
@array_function_dispatch(_reshape_dispatcher)
|
|
def reshape(a, newshape, order='C'):
|
|
"""
|
|
Gives a new shape to an array without changing its data.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Array to be reshaped.
|
|
newshape : int or tuple of ints
|
|
The new shape should be compatible with the original shape. If
|
|
an integer, then the result will be a 1-D array of that length.
|
|
One shape dimension can be -1. In this case, the value is
|
|
inferred from the length of the array and remaining dimensions.
|
|
order : {'C', 'F', 'A'}, optional
|
|
Read the elements of `a` using this index order, and place the
|
|
elements into the reshaped array using this index order. 'C'
|
|
means to read / write the elements using C-like index order,
|
|
with the last axis index changing fastest, back to the first
|
|
axis index changing slowest. 'F' means to read / write the
|
|
elements using Fortran-like index order, with the first index
|
|
changing fastest, and the last index changing slowest. Note that
|
|
the 'C' and 'F' options take no account of the memory layout of
|
|
the underlying array, and only refer to the order of indexing.
|
|
'A' means to read / write the elements in Fortran-like index
|
|
order if `a` is Fortran *contiguous* in memory, C-like order
|
|
otherwise.
|
|
|
|
Returns
|
|
-------
|
|
reshaped_array : ndarray
|
|
This will be a new view object if possible; otherwise, it will
|
|
be a copy. Note there is no guarantee of the *memory layout* (C- or
|
|
Fortran- contiguous) of the returned array.
|
|
|
|
See Also
|
|
--------
|
|
ndarray.reshape : Equivalent method.
|
|
|
|
Notes
|
|
-----
|
|
It is not always possible to change the shape of an array without
|
|
copying the data. If you want an error to be raised when the data is copied,
|
|
you should assign the new shape to the shape attribute of the array::
|
|
|
|
>>> a = np.zeros((10, 2))
|
|
|
|
# A transpose makes the array non-contiguous
|
|
>>> b = a.T
|
|
|
|
# Taking a view makes it possible to modify the shape without modifying
|
|
# the initial object.
|
|
>>> c = b.view()
|
|
>>> c.shape = (20)
|
|
Traceback (most recent call last):
|
|
...
|
|
AttributeError: incompatible shape for a non-contiguous array
|
|
|
|
The `order` keyword gives the index ordering both for *fetching* the values
|
|
from `a`, and then *placing* the values into the output array.
|
|
For example, let's say you have an array:
|
|
|
|
>>> a = np.arange(6).reshape((3, 2))
|
|
>>> a
|
|
array([[0, 1],
|
|
[2, 3],
|
|
[4, 5]])
|
|
|
|
You can think of reshaping as first raveling the array (using the given
|
|
index order), then inserting the elements from the raveled array into the
|
|
new array using the same kind of index ordering as was used for the
|
|
raveling.
|
|
|
|
>>> np.reshape(a, (2, 3)) # C-like index ordering
|
|
array([[0, 1, 2],
|
|
[3, 4, 5]])
|
|
>>> np.reshape(np.ravel(a), (2, 3)) # equivalent to C ravel then C reshape
|
|
array([[0, 1, 2],
|
|
[3, 4, 5]])
|
|
>>> np.reshape(a, (2, 3), order='F') # Fortran-like index ordering
|
|
array([[0, 4, 3],
|
|
[2, 1, 5]])
|
|
>>> np.reshape(np.ravel(a, order='F'), (2, 3), order='F')
|
|
array([[0, 4, 3],
|
|
[2, 1, 5]])
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.array([[1,2,3], [4,5,6]])
|
|
>>> np.reshape(a, 6)
|
|
array([1, 2, 3, 4, 5, 6])
|
|
>>> np.reshape(a, 6, order='F')
|
|
array([1, 4, 2, 5, 3, 6])
|
|
|
|
>>> np.reshape(a, (3,-1)) # the unspecified value is inferred to be 2
|
|
array([[1, 2],
|
|
[3, 4],
|
|
[5, 6]])
|
|
"""
|
|
return _wrapfunc(a, 'reshape', newshape, order=order)
|
|
|
|
|
|
def _choose_dispatcher(a, choices, out=None, mode=None):
|
|
yield a
|
|
for c in choices:
|
|
yield c
|
|
yield out
|
|
|
|
|
|
@array_function_dispatch(_choose_dispatcher)
|
|
def choose(a, choices, out=None, mode='raise'):
|
|
"""
|
|
Construct an array from an index array and a set of arrays to choose from.
|
|
|
|
First of all, if confused or uncertain, definitely look at the Examples -
|
|
in its full generality, this function is less simple than it might
|
|
seem from the following code description (below ndi =
|
|
`numpy.lib.index_tricks`):
|
|
|
|
``np.choose(a,c) == np.array([c[a[I]][I] for I in ndi.ndindex(a.shape)])``.
|
|
|
|
But this omits some subtleties. Here is a fully general summary:
|
|
|
|
Given an "index" array (`a`) of integers and a sequence of `n` arrays
|
|
(`choices`), `a` and each choice array are first broadcast, as necessary,
|
|
to arrays of a common shape; calling these *Ba* and *Bchoices[i], i =
|
|
0,...,n-1* we have that, necessarily, ``Ba.shape == Bchoices[i].shape``
|
|
for each `i`. Then, a new array with shape ``Ba.shape`` is created as
|
|
follows:
|
|
|
|
* if ``mode=raise`` (the default), then, first of all, each element of
|
|
`a` (and thus `Ba`) must be in the range `[0, n-1]`; now, suppose that
|
|
`i` (in that range) is the value at the `(j0, j1, ..., jm)` position
|
|
in `Ba` - then the value at the same position in the new array is the
|
|
value in `Bchoices[i]` at that same position;
|
|
|
|
* if ``mode=wrap``, values in `a` (and thus `Ba`) may be any (signed)
|
|
integer; modular arithmetic is used to map integers outside the range
|
|
`[0, n-1]` back into that range; and then the new array is constructed
|
|
as above;
|
|
|
|
* if ``mode=clip``, values in `a` (and thus `Ba`) may be any (signed)
|
|
integer; negative integers are mapped to 0; values greater than `n-1`
|
|
are mapped to `n-1`; and then the new array is constructed as above.
|
|
|
|
Parameters
|
|
----------
|
|
a : int array
|
|
This array must contain integers in `[0, n-1]`, where `n` is the number
|
|
of choices, unless ``mode=wrap`` or ``mode=clip``, in which cases any
|
|
integers are permissible.
|
|
choices : sequence of arrays
|
|
Choice arrays. `a` and all of the choices must be broadcastable to the
|
|
same shape. If `choices` is itself an array (not recommended), then
|
|
its outermost dimension (i.e., the one corresponding to
|
|
``choices.shape[0]``) is taken as defining the "sequence".
|
|
out : array, optional
|
|
If provided, the result will be inserted into this array. It should
|
|
be of the appropriate shape and dtype. Note that `out` is always
|
|
buffered if `mode='raise'`; use other modes for better performance.
|
|
mode : {'raise' (default), 'wrap', 'clip'}, optional
|
|
Specifies how indices outside `[0, n-1]` will be treated:
|
|
|
|
* 'raise' : an exception is raised
|
|
* 'wrap' : value becomes value mod `n`
|
|
* 'clip' : values < 0 are mapped to 0, values > n-1 are mapped to n-1
|
|
|
|
Returns
|
|
-------
|
|
merged_array : array
|
|
The merged result.
|
|
|
|
Raises
|
|
------
|
|
ValueError: shape mismatch
|
|
If `a` and each choice array are not all broadcastable to the same
|
|
shape.
|
|
|
|
See Also
|
|
--------
|
|
ndarray.choose : equivalent method
|
|
|
|
Notes
|
|
-----
|
|
To reduce the chance of misinterpretation, even though the following
|
|
"abuse" is nominally supported, `choices` should neither be, nor be
|
|
thought of as, a single array, i.e., the outermost sequence-like container
|
|
should be either a list or a tuple.
|
|
|
|
Examples
|
|
--------
|
|
|
|
>>> choices = [[0, 1, 2, 3], [10, 11, 12, 13],
|
|
... [20, 21, 22, 23], [30, 31, 32, 33]]
|
|
>>> np.choose([2, 3, 1, 0], choices
|
|
... # the first element of the result will be the first element of the
|
|
... # third (2+1) "array" in choices, namely, 20; the second element
|
|
... # will be the second element of the fourth (3+1) choice array, i.e.,
|
|
... # 31, etc.
|
|
... )
|
|
array([20, 31, 12, 3])
|
|
>>> np.choose([2, 4, 1, 0], choices, mode='clip') # 4 goes to 3 (4-1)
|
|
array([20, 31, 12, 3])
|
|
>>> # because there are 4 choice arrays
|
|
>>> np.choose([2, 4, 1, 0], choices, mode='wrap') # 4 goes to (4 mod 4)
|
|
array([20, 1, 12, 3])
|
|
>>> # i.e., 0
|
|
|
|
A couple examples illustrating how choose broadcasts:
|
|
|
|
>>> a = [[1, 0, 1], [0, 1, 0], [1, 0, 1]]
|
|
>>> choices = [-10, 10]
|
|
>>> np.choose(a, choices)
|
|
array([[ 10, -10, 10],
|
|
[-10, 10, -10],
|
|
[ 10, -10, 10]])
|
|
|
|
>>> # With thanks to Anne Archibald
|
|
>>> a = np.array([0, 1]).reshape((2,1,1))
|
|
>>> c1 = np.array([1, 2, 3]).reshape((1,3,1))
|
|
>>> c2 = np.array([-1, -2, -3, -4, -5]).reshape((1,1,5))
|
|
>>> np.choose(a, (c1, c2)) # result is 2x3x5, res[0,:,:]=c1, res[1,:,:]=c2
|
|
array([[[ 1, 1, 1, 1, 1],
|
|
[ 2, 2, 2, 2, 2],
|
|
[ 3, 3, 3, 3, 3]],
|
|
[[-1, -2, -3, -4, -5],
|
|
[-1, -2, -3, -4, -5],
|
|
[-1, -2, -3, -4, -5]]])
|
|
|
|
"""
|
|
return _wrapfunc(a, 'choose', choices, out=out, mode=mode)
|
|
|
|
|
|
def _repeat_dispatcher(a, repeats, axis=None):
|
|
return (a,)
|
|
|
|
|
|
@array_function_dispatch(_repeat_dispatcher)
|
|
def repeat(a, repeats, axis=None):
|
|
"""
|
|
Repeat elements of an array.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input array.
|
|
repeats : int or array of ints
|
|
The number of repetitions for each element. `repeats` is broadcasted
|
|
to fit the shape of the given axis.
|
|
axis : int, optional
|
|
The axis along which to repeat values. By default, use the
|
|
flattened input array, and return a flat output array.
|
|
|
|
Returns
|
|
-------
|
|
repeated_array : ndarray
|
|
Output array which has the same shape as `a`, except along
|
|
the given axis.
|
|
|
|
See Also
|
|
--------
|
|
tile : Tile an array.
|
|
|
|
Examples
|
|
--------
|
|
>>> np.repeat(3, 4)
|
|
array([3, 3, 3, 3])
|
|
>>> x = np.array([[1,2],[3,4]])
|
|
>>> np.repeat(x, 2)
|
|
array([1, 1, 2, 2, 3, 3, 4, 4])
|
|
>>> np.repeat(x, 3, axis=1)
|
|
array([[1, 1, 1, 2, 2, 2],
|
|
[3, 3, 3, 4, 4, 4]])
|
|
>>> np.repeat(x, [1, 2], axis=0)
|
|
array([[1, 2],
|
|
[3, 4],
|
|
[3, 4]])
|
|
|
|
"""
|
|
return _wrapfunc(a, 'repeat', repeats, axis=axis)
|
|
|
|
|
|
def _put_dispatcher(a, ind, v, mode=None):
|
|
return (a, ind, v)
|
|
|
|
|
|
@array_function_dispatch(_put_dispatcher)
|
|
def put(a, ind, v, mode='raise'):
|
|
"""
|
|
Replaces specified elements of an array with given values.
|
|
|
|
The indexing works on the flattened target array. `put` is roughly
|
|
equivalent to:
|
|
|
|
::
|
|
|
|
a.flat[ind] = v
|
|
|
|
Parameters
|
|
----------
|
|
a : ndarray
|
|
Target array.
|
|
ind : array_like
|
|
Target indices, interpreted as integers.
|
|
v : array_like
|
|
Values to place in `a` at target indices. If `v` is shorter than
|
|
`ind` it will be repeated as necessary.
|
|
mode : {'raise', 'wrap', 'clip'}, optional
|
|
Specifies how out-of-bounds indices will behave.
|
|
|
|
* 'raise' -- raise an error (default)
|
|
* 'wrap' -- wrap around
|
|
* 'clip' -- clip to the range
|
|
|
|
'clip' mode means that all indices that are too large are replaced
|
|
by the index that addresses the last element along that axis. Note
|
|
that this disables indexing with negative numbers. In 'raise' mode,
|
|
if an exception occurs the target array may still be modified.
|
|
|
|
See Also
|
|
--------
|
|
putmask, place
|
|
put_along_axis : Put elements by matching the array and the index arrays
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.arange(5)
|
|
>>> np.put(a, [0, 2], [-44, -55])
|
|
>>> a
|
|
array([-44, 1, -55, 3, 4])
|
|
|
|
>>> a = np.arange(5)
|
|
>>> np.put(a, 22, -5, mode='clip')
|
|
>>> a
|
|
array([ 0, 1, 2, 3, -5])
|
|
|
|
"""
|
|
try:
|
|
put = a.put
|
|
except AttributeError:
|
|
raise TypeError("argument 1 must be numpy.ndarray, "
|
|
"not {name}".format(name=type(a).__name__))
|
|
|
|
return put(ind, v, mode=mode)
|
|
|
|
|
|
def _swapaxes_dispatcher(a, axis1, axis2):
|
|
return (a,)
|
|
|
|
|
|
@array_function_dispatch(_swapaxes_dispatcher)
|
|
def swapaxes(a, axis1, axis2):
|
|
"""
|
|
Interchange two axes of an array.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input array.
|
|
axis1 : int
|
|
First axis.
|
|
axis2 : int
|
|
Second axis.
|
|
|
|
Returns
|
|
-------
|
|
a_swapped : ndarray
|
|
For NumPy >= 1.10.0, if `a` is an ndarray, then a view of `a` is
|
|
returned; otherwise a new array is created. For earlier NumPy
|
|
versions a view of `a` is returned only if the order of the
|
|
axes is changed, otherwise the input array is returned.
|
|
|
|
Examples
|
|
--------
|
|
>>> x = np.array([[1,2,3]])
|
|
>>> np.swapaxes(x,0,1)
|
|
array([[1],
|
|
[2],
|
|
[3]])
|
|
|
|
>>> x = np.array([[[0,1],[2,3]],[[4,5],[6,7]]])
|
|
>>> x
|
|
array([[[0, 1],
|
|
[2, 3]],
|
|
[[4, 5],
|
|
[6, 7]]])
|
|
|
|
>>> np.swapaxes(x,0,2)
|
|
array([[[0, 4],
|
|
[2, 6]],
|
|
[[1, 5],
|
|
[3, 7]]])
|
|
|
|
"""
|
|
return _wrapfunc(a, 'swapaxes', axis1, axis2)
|
|
|
|
|
|
def _transpose_dispatcher(a, axes=None):
|
|
return (a,)
|
|
|
|
|
|
@array_function_dispatch(_transpose_dispatcher)
|
|
def transpose(a, axes=None):
|
|
"""
|
|
Permute the dimensions of an array.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input array.
|
|
axes : list of ints, optional
|
|
By default, reverse the dimensions, otherwise permute the axes
|
|
according to the values given.
|
|
|
|
Returns
|
|
-------
|
|
p : ndarray
|
|
`a` with its axes permuted. A view is returned whenever
|
|
possible.
|
|
|
|
See Also
|
|
--------
|
|
moveaxis
|
|
argsort
|
|
|
|
Notes
|
|
-----
|
|
Use `transpose(a, argsort(axes))` to invert the transposition of tensors
|
|
when using the `axes` keyword argument.
|
|
|
|
Transposing a 1-D array returns an unchanged view of the original array.
|
|
|
|
Examples
|
|
--------
|
|
>>> x = np.arange(4).reshape((2,2))
|
|
>>> x
|
|
array([[0, 1],
|
|
[2, 3]])
|
|
|
|
>>> np.transpose(x)
|
|
array([[0, 2],
|
|
[1, 3]])
|
|
|
|
>>> x = np.ones((1, 2, 3))
|
|
>>> np.transpose(x, (1, 0, 2)).shape
|
|
(2, 1, 3)
|
|
|
|
"""
|
|
return _wrapfunc(a, 'transpose', axes)
|
|
|
|
|
|
def _partition_dispatcher(a, kth, axis=None, kind=None, order=None):
|
|
return (a,)
|
|
|
|
|
|
@array_function_dispatch(_partition_dispatcher)
|
|
def partition(a, kth, axis=-1, kind='introselect', order=None):
|
|
"""
|
|
Return a partitioned copy of an array.
|
|
|
|
Creates a copy of the array with its elements rearranged in such a
|
|
way that the value of the element in k-th position is in the
|
|
position it would be in a sorted array. All elements smaller than
|
|
the k-th element are moved before this element and all equal or
|
|
greater are moved behind it. The ordering of the elements in the two
|
|
partitions is undefined.
|
|
|
|
.. versionadded:: 1.8.0
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Array to be sorted.
|
|
kth : int or sequence of ints
|
|
Element index to partition by. The k-th value of the element
|
|
will be in its final sorted position and all smaller elements
|
|
will be moved before it and all equal or greater elements behind
|
|
it. The order of all elements in the partitions is undefined. If
|
|
provided with a sequence of k-th it will partition all elements
|
|
indexed by k-th of them into their sorted position at once.
|
|
axis : int or None, optional
|
|
Axis along which to sort. If None, the array is flattened before
|
|
sorting. The default is -1, which sorts along the last axis.
|
|
kind : {'introselect'}, optional
|
|
Selection algorithm. Default is 'introselect'.
|
|
order : str or list of str, optional
|
|
When `a` is an array with fields defined, this argument
|
|
specifies which fields to compare first, second, etc. A single
|
|
field can be specified as a string. Not all fields need be
|
|
specified, but unspecified fields will still be used, in the
|
|
order in which they come up in the dtype, to break ties.
|
|
|
|
Returns
|
|
-------
|
|
partitioned_array : ndarray
|
|
Array of the same type and shape as `a`.
|
|
|
|
See Also
|
|
--------
|
|
ndarray.partition : Method to sort an array in-place.
|
|
argpartition : Indirect partition.
|
|
sort : Full sorting
|
|
|
|
Notes
|
|
-----
|
|
The various selection algorithms are characterized by their average
|
|
speed, worst case performance, work space size, and whether they are
|
|
stable. A stable sort keeps items with the same key in the same
|
|
relative order. The available algorithms have the following
|
|
properties:
|
|
|
|
================= ======= ============= ============ =======
|
|
kind speed worst case work space stable
|
|
================= ======= ============= ============ =======
|
|
'introselect' 1 O(n) 0 no
|
|
================= ======= ============= ============ =======
|
|
|
|
All the partition algorithms make temporary copies of the data when
|
|
partitioning along any but the last axis. Consequently,
|
|
partitioning along the last axis is faster and uses less space than
|
|
partitioning along any other axis.
|
|
|
|
The sort order for complex numbers is lexicographic. If both the
|
|
real and imaginary parts are non-nan then the order is determined by
|
|
the real parts except when they are equal, in which case the order
|
|
is determined by the imaginary parts.
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.array([3, 4, 2, 1])
|
|
>>> np.partition(a, 3)
|
|
array([2, 1, 3, 4])
|
|
|
|
>>> np.partition(a, (1, 3))
|
|
array([1, 2, 3, 4])
|
|
|
|
"""
|
|
if axis is None:
|
|
# flatten returns (1, N) for np.matrix, so always use the last axis
|
|
a = asanyarray(a).flatten()
|
|
axis = -1
|
|
else:
|
|
a = asanyarray(a).copy(order="K")
|
|
a.partition(kth, axis=axis, kind=kind, order=order)
|
|
return a
|
|
|
|
|
|
def _argpartition_dispatcher(a, kth, axis=None, kind=None, order=None):
|
|
return (a,)
|
|
|
|
|
|
@array_function_dispatch(_argpartition_dispatcher)
|
|
def argpartition(a, kth, axis=-1, kind='introselect', order=None):
|
|
"""
|
|
Perform an indirect partition along the given axis using the
|
|
algorithm specified by the `kind` keyword. It returns an array of
|
|
indices of the same shape as `a` that index data along the given
|
|
axis in partitioned order.
|
|
|
|
.. versionadded:: 1.8.0
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Array to sort.
|
|
kth : int or sequence of ints
|
|
Element index to partition by. The k-th element will be in its
|
|
final sorted position and all smaller elements will be moved
|
|
before it and all larger elements behind it. The order all
|
|
elements in the partitions is undefined. If provided with a
|
|
sequence of k-th it will partition all of them into their sorted
|
|
position at once.
|
|
axis : int or None, optional
|
|
Axis along which to sort. The default is -1 (the last axis). If
|
|
None, the flattened array is used.
|
|
kind : {'introselect'}, optional
|
|
Selection algorithm. Default is 'introselect'
|
|
order : str or list of str, optional
|
|
When `a` is an array with fields defined, this argument
|
|
specifies which fields to compare first, second, etc. A single
|
|
field can be specified as a string, and not all fields need be
|
|
specified, but unspecified fields will still be used, in the
|
|
order in which they come up in the dtype, to break ties.
|
|
|
|
Returns
|
|
-------
|
|
index_array : ndarray, int
|
|
Array of indices that partition `a` along the specified axis.
|
|
If `a` is one-dimensional, ``a[index_array]`` yields a partitioned `a`.
|
|
More generally, ``np.take_along_axis(a, index_array, axis=a)`` always
|
|
yields the partitioned `a`, irrespective of dimensionality.
|
|
|
|
See Also
|
|
--------
|
|
partition : Describes partition algorithms used.
|
|
ndarray.partition : Inplace partition.
|
|
argsort : Full indirect sort
|
|
|
|
Notes
|
|
-----
|
|
See `partition` for notes on the different selection algorithms.
|
|
|
|
Examples
|
|
--------
|
|
One dimensional array:
|
|
|
|
>>> x = np.array([3, 4, 2, 1])
|
|
>>> x[np.argpartition(x, 3)]
|
|
array([2, 1, 3, 4])
|
|
>>> x[np.argpartition(x, (1, 3))]
|
|
array([1, 2, 3, 4])
|
|
|
|
>>> x = [3, 4, 2, 1]
|
|
>>> np.array(x)[np.argpartition(x, 3)]
|
|
array([2, 1, 3, 4])
|
|
|
|
"""
|
|
return _wrapfunc(a, 'argpartition', kth, axis=axis, kind=kind, order=order)
|
|
|
|
|
|
def _sort_dispatcher(a, axis=None, kind=None, order=None):
|
|
return (a,)
|
|
|
|
|
|
@array_function_dispatch(_sort_dispatcher)
|
|
def sort(a, axis=-1, kind=None, order=None):
|
|
"""
|
|
Return a sorted copy of an array.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Array to be sorted.
|
|
axis : int or None, optional
|
|
Axis along which to sort. If None, the array is flattened before
|
|
sorting. The default is -1, which sorts along the last axis.
|
|
kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, optional
|
|
Sorting algorithm. The default is 'quicksort'. Note that both 'stable'
|
|
and 'mergesort' use timsort or radix sort under the covers and, in general,
|
|
the actual implementation will vary with data type. The 'mergesort' option
|
|
is retained for backwards compatibility.
|
|
|
|
.. versionchanged:: 1.15.0.
|
|
The 'stable' option was added.
|
|
|
|
order : str or list of str, optional
|
|
When `a` is an array with fields defined, this argument specifies
|
|
which fields to compare first, second, etc. A single field can
|
|
be specified as a string, and not all fields need be specified,
|
|
but unspecified fields will still be used, in the order in which
|
|
they come up in the dtype, to break ties.
|
|
|
|
Returns
|
|
-------
|
|
sorted_array : ndarray
|
|
Array of the same type and shape as `a`.
|
|
|
|
See Also
|
|
--------
|
|
ndarray.sort : Method to sort an array in-place.
|
|
argsort : Indirect sort.
|
|
lexsort : Indirect stable sort on multiple keys.
|
|
searchsorted : Find elements in a sorted array.
|
|
partition : Partial sort.
|
|
|
|
Notes
|
|
-----
|
|
The various sorting algorithms are characterized by their average speed,
|
|
worst case performance, work space size, and whether they are stable. A
|
|
stable sort keeps items with the same key in the same relative
|
|
order. The four algorithms implemented in NumPy have the following
|
|
properties:
|
|
|
|
=========== ======= ============= ============ ========
|
|
kind speed worst case work space stable
|
|
=========== ======= ============= ============ ========
|
|
'quicksort' 1 O(n^2) 0 no
|
|
'heapsort' 3 O(n*log(n)) 0 no
|
|
'mergesort' 2 O(n*log(n)) ~n/2 yes
|
|
'timsort' 2 O(n*log(n)) ~n/2 yes
|
|
=========== ======= ============= ============ ========
|
|
|
|
.. note:: The datatype determines which of 'mergesort' or 'timsort'
|
|
is actually used, even if 'mergesort' is specified. User selection
|
|
at a finer scale is not currently available.
|
|
|
|
All the sort algorithms make temporary copies of the data when
|
|
sorting along any but the last axis. Consequently, sorting along
|
|
the last axis is faster and uses less space than sorting along
|
|
any other axis.
|
|
|
|
The sort order for complex numbers is lexicographic. If both the real
|
|
and imaginary parts are non-nan then the order is determined by the
|
|
real parts except when they are equal, in which case the order is
|
|
determined by the imaginary parts.
|
|
|
|
Previous to numpy 1.4.0 sorting real and complex arrays containing nan
|
|
values led to undefined behaviour. In numpy versions >= 1.4.0 nan
|
|
values are sorted to the end. The extended sort order is:
|
|
|
|
* Real: [R, nan]
|
|
* Complex: [R + Rj, R + nanj, nan + Rj, nan + nanj]
|
|
|
|
where R is a non-nan real value. Complex values with the same nan
|
|
placements are sorted according to the non-nan part if it exists.
|
|
Non-nan values are sorted as before.
|
|
|
|
.. versionadded:: 1.12.0
|
|
|
|
quicksort has been changed to an introsort which will switch
|
|
heapsort when it does not make enough progress. This makes its
|
|
worst case O(n*log(n)).
|
|
|
|
'stable' automatically choses the best stable sorting algorithm
|
|
for the data type being sorted. It, along with 'mergesort' is
|
|
currently mapped to timsort or radix sort depending on the
|
|
data type. API forward compatibility currently limits the
|
|
ability to select the implementation and it is hardwired for the different
|
|
data types.
|
|
|
|
.. versionadded:: 1.17.0
|
|
|
|
Timsort is added for better performance on already or nearly
|
|
sorted data. On random data timsort is almost identical to
|
|
mergesort. It is now used for stable sort while quicksort is still the
|
|
default sort if none is chosen. For details of timsort, refer to
|
|
`CPython listsort.txt <https://github.com/python/cpython/blob/3.7/Objects/listsort.txt>`_.
|
|
'mergesort' and 'stable' are mapped to radix sort for integer data types. Radix sort is an
|
|
O(n) sort instead of O(n log n).
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.array([[1,4],[3,1]])
|
|
>>> np.sort(a) # sort along the last axis
|
|
array([[1, 4],
|
|
[1, 3]])
|
|
>>> np.sort(a, axis=None) # sort the flattened array
|
|
array([1, 1, 3, 4])
|
|
>>> np.sort(a, axis=0) # sort along the first axis
|
|
array([[1, 1],
|
|
[3, 4]])
|
|
|
|
Use the `order` keyword to specify a field to use when sorting a
|
|
structured array:
|
|
|
|
>>> dtype = [('name', 'S10'), ('height', float), ('age', int)]
|
|
>>> values = [('Arthur', 1.8, 41), ('Lancelot', 1.9, 38),
|
|
... ('Galahad', 1.7, 38)]
|
|
>>> a = np.array(values, dtype=dtype) # create a structured array
|
|
>>> np.sort(a, order='height') # doctest: +SKIP
|
|
array([('Galahad', 1.7, 38), ('Arthur', 1.8, 41),
|
|
('Lancelot', 1.8999999999999999, 38)],
|
|
dtype=[('name', '|S10'), ('height', '<f8'), ('age', '<i4')])
|
|
|
|
Sort by age, then height if ages are equal:
|
|
|
|
>>> np.sort(a, order=['age', 'height']) # doctest: +SKIP
|
|
array([('Galahad', 1.7, 38), ('Lancelot', 1.8999999999999999, 38),
|
|
('Arthur', 1.8, 41)],
|
|
dtype=[('name', '|S10'), ('height', '<f8'), ('age', '<i4')])
|
|
|
|
"""
|
|
if axis is None:
|
|
# flatten returns (1, N) for np.matrix, so always use the last axis
|
|
a = asanyarray(a).flatten()
|
|
axis = -1
|
|
else:
|
|
a = asanyarray(a).copy(order="K")
|
|
a.sort(axis=axis, kind=kind, order=order)
|
|
return a
|
|
|
|
|
|
def _argsort_dispatcher(a, axis=None, kind=None, order=None):
|
|
return (a,)
|
|
|
|
|
|
@array_function_dispatch(_argsort_dispatcher)
|
|
def argsort(a, axis=-1, kind=None, order=None):
|
|
"""
|
|
Returns the indices that would sort an array.
|
|
|
|
Perform an indirect sort along the given axis using the algorithm specified
|
|
by the `kind` keyword. It returns an array of indices of the same shape as
|
|
`a` that index data along the given axis in sorted order.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Array to sort.
|
|
axis : int or None, optional
|
|
Axis along which to sort. The default is -1 (the last axis). If None,
|
|
the flattened array is used.
|
|
kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, optional
|
|
Sorting algorithm. The default is 'quicksort'. Note that both 'stable'
|
|
and 'mergesort' use timsort under the covers and, in general, the
|
|
actual implementation will vary with data type. The 'mergesort' option
|
|
is retained for backwards compatibility.
|
|
|
|
.. versionchanged:: 1.15.0.
|
|
The 'stable' option was added.
|
|
order : str or list of str, optional
|
|
When `a` is an array with fields defined, this argument specifies
|
|
which fields to compare first, second, etc. A single field can
|
|
be specified as a string, and not all fields need be specified,
|
|
but unspecified fields will still be used, in the order in which
|
|
they come up in the dtype, to break ties.
|
|
|
|
Returns
|
|
-------
|
|
index_array : ndarray, int
|
|
Array of indices that sort `a` along the specified `axis`.
|
|
If `a` is one-dimensional, ``a[index_array]`` yields a sorted `a`.
|
|
More generally, ``np.take_along_axis(a, index_array, axis=axis)``
|
|
always yields the sorted `a`, irrespective of dimensionality.
|
|
|
|
See Also
|
|
--------
|
|
sort : Describes sorting algorithms used.
|
|
lexsort : Indirect stable sort with multiple keys.
|
|
ndarray.sort : Inplace sort.
|
|
argpartition : Indirect partial sort.
|
|
|
|
Notes
|
|
-----
|
|
See `sort` for notes on the different sorting algorithms.
|
|
|
|
As of NumPy 1.4.0 `argsort` works with real/complex arrays containing
|
|
nan values. The enhanced sort order is documented in `sort`.
|
|
|
|
Examples
|
|
--------
|
|
One dimensional array:
|
|
|
|
>>> x = np.array([3, 1, 2])
|
|
>>> np.argsort(x)
|
|
array([1, 2, 0])
|
|
|
|
Two-dimensional array:
|
|
|
|
>>> x = np.array([[0, 3], [2, 2]])
|
|
>>> x
|
|
array([[0, 3],
|
|
[2, 2]])
|
|
|
|
>>> ind = np.argsort(x, axis=0) # sorts along first axis (down)
|
|
>>> ind
|
|
array([[0, 1],
|
|
[1, 0]])
|
|
>>> np.take_along_axis(x, ind, axis=0) # same as np.sort(x, axis=0)
|
|
array([[0, 2],
|
|
[2, 3]])
|
|
|
|
>>> ind = np.argsort(x, axis=1) # sorts along last axis (across)
|
|
>>> ind
|
|
array([[0, 1],
|
|
[0, 1]])
|
|
>>> np.take_along_axis(x, ind, axis=1) # same as np.sort(x, axis=1)
|
|
array([[0, 3],
|
|
[2, 2]])
|
|
|
|
Indices of the sorted elements of a N-dimensional array:
|
|
|
|
>>> ind = np.unravel_index(np.argsort(x, axis=None), x.shape)
|
|
>>> ind
|
|
(array([0, 1, 1, 0]), array([0, 0, 1, 1]))
|
|
>>> x[ind] # same as np.sort(x, axis=None)
|
|
array([0, 2, 2, 3])
|
|
|
|
Sorting with keys:
|
|
|
|
>>> x = np.array([(1, 0), (0, 1)], dtype=[('x', '<i4'), ('y', '<i4')])
|
|
>>> x
|
|
array([(1, 0), (0, 1)],
|
|
dtype=[('x', '<i4'), ('y', '<i4')])
|
|
|
|
>>> np.argsort(x, order=('x','y'))
|
|
array([1, 0])
|
|
|
|
>>> np.argsort(x, order=('y','x'))
|
|
array([0, 1])
|
|
|
|
"""
|
|
return _wrapfunc(a, 'argsort', axis=axis, kind=kind, order=order)
|
|
|
|
|
|
def _argmax_dispatcher(a, axis=None, out=None):
|
|
return (a, out)
|
|
|
|
|
|
@array_function_dispatch(_argmax_dispatcher)
|
|
def argmax(a, axis=None, out=None):
|
|
"""
|
|
Returns the indices of the maximum values along an axis.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input array.
|
|
axis : int, optional
|
|
By default, the index is into the flattened array, otherwise
|
|
along the specified axis.
|
|
out : array, optional
|
|
If provided, the result will be inserted into this array. It should
|
|
be of the appropriate shape and dtype.
|
|
|
|
Returns
|
|
-------
|
|
index_array : ndarray of ints
|
|
Array of indices into the array. It has the same shape as `a.shape`
|
|
with the dimension along `axis` removed.
|
|
|
|
See Also
|
|
--------
|
|
ndarray.argmax, argmin
|
|
amax : The maximum value along a given axis.
|
|
unravel_index : Convert a flat index into an index tuple.
|
|
|
|
Notes
|
|
-----
|
|
In case of multiple occurrences of the maximum values, the indices
|
|
corresponding to the first occurrence are returned.
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.arange(6).reshape(2,3) + 10
|
|
>>> a
|
|
array([[10, 11, 12],
|
|
[13, 14, 15]])
|
|
>>> np.argmax(a)
|
|
5
|
|
>>> np.argmax(a, axis=0)
|
|
array([1, 1, 1])
|
|
>>> np.argmax(a, axis=1)
|
|
array([2, 2])
|
|
|
|
Indexes of the maximal elements of a N-dimensional array:
|
|
|
|
>>> ind = np.unravel_index(np.argmax(a, axis=None), a.shape)
|
|
>>> ind
|
|
(1, 2)
|
|
>>> a[ind]
|
|
15
|
|
|
|
>>> b = np.arange(6)
|
|
>>> b[1] = 5
|
|
>>> b
|
|
array([0, 5, 2, 3, 4, 5])
|
|
>>> np.argmax(b) # Only the first occurrence is returned.
|
|
1
|
|
|
|
"""
|
|
return _wrapfunc(a, 'argmax', axis=axis, out=out)
|
|
|
|
|
|
def _argmin_dispatcher(a, axis=None, out=None):
|
|
return (a, out)
|
|
|
|
|
|
@array_function_dispatch(_argmin_dispatcher)
|
|
def argmin(a, axis=None, out=None):
|
|
"""
|
|
Returns the indices of the minimum values along an axis.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input array.
|
|
axis : int, optional
|
|
By default, the index is into the flattened array, otherwise
|
|
along the specified axis.
|
|
out : array, optional
|
|
If provided, the result will be inserted into this array. It should
|
|
be of the appropriate shape and dtype.
|
|
|
|
Returns
|
|
-------
|
|
index_array : ndarray of ints
|
|
Array of indices into the array. It has the same shape as `a.shape`
|
|
with the dimension along `axis` removed.
|
|
|
|
See Also
|
|
--------
|
|
ndarray.argmin, argmax
|
|
amin : The minimum value along a given axis.
|
|
unravel_index : Convert a flat index into an index tuple.
|
|
|
|
Notes
|
|
-----
|
|
In case of multiple occurrences of the minimum values, the indices
|
|
corresponding to the first occurrence are returned.
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.arange(6).reshape(2,3) + 10
|
|
>>> a
|
|
array([[10, 11, 12],
|
|
[13, 14, 15]])
|
|
>>> np.argmin(a)
|
|
0
|
|
>>> np.argmin(a, axis=0)
|
|
array([0, 0, 0])
|
|
>>> np.argmin(a, axis=1)
|
|
array([0, 0])
|
|
|
|
Indices of the minimum elements of a N-dimensional array:
|
|
|
|
>>> ind = np.unravel_index(np.argmin(a, axis=None), a.shape)
|
|
>>> ind
|
|
(0, 0)
|
|
>>> a[ind]
|
|
10
|
|
|
|
>>> b = np.arange(6) + 10
|
|
>>> b[4] = 10
|
|
>>> b
|
|
array([10, 11, 12, 13, 10, 15])
|
|
>>> np.argmin(b) # Only the first occurrence is returned.
|
|
0
|
|
|
|
"""
|
|
return _wrapfunc(a, 'argmin', axis=axis, out=out)
|
|
|
|
|
|
def _searchsorted_dispatcher(a, v, side=None, sorter=None):
|
|
return (a, v, sorter)
|
|
|
|
|
|
@array_function_dispatch(_searchsorted_dispatcher)
|
|
def searchsorted(a, v, side='left', sorter=None):
|
|
"""
|
|
Find indices where elements should be inserted to maintain order.
|
|
|
|
Find the indices into a sorted array `a` such that, if the
|
|
corresponding elements in `v` were inserted before the indices, the
|
|
order of `a` would be preserved.
|
|
|
|
Assuming that `a` is sorted:
|
|
|
|
====== ============================
|
|
`side` returned index `i` satisfies
|
|
====== ============================
|
|
left ``a[i-1] < v <= a[i]``
|
|
right ``a[i-1] <= v < a[i]``
|
|
====== ============================
|
|
|
|
Parameters
|
|
----------
|
|
a : 1-D array_like
|
|
Input array. If `sorter` is None, then it must be sorted in
|
|
ascending order, otherwise `sorter` must be an array of indices
|
|
that sort it.
|
|
v : array_like
|
|
Values to insert into `a`.
|
|
side : {'left', 'right'}, optional
|
|
If 'left', the index of the first suitable location found is given.
|
|
If 'right', return the last such index. If there is no suitable
|
|
index, return either 0 or N (where N is the length of `a`).
|
|
sorter : 1-D array_like, optional
|
|
Optional array of integer indices that sort array a into ascending
|
|
order. They are typically the result of argsort.
|
|
|
|
.. versionadded:: 1.7.0
|
|
|
|
Returns
|
|
-------
|
|
indices : array of ints
|
|
Array of insertion points with the same shape as `v`.
|
|
|
|
See Also
|
|
--------
|
|
sort : Return a sorted copy of an array.
|
|
histogram : Produce histogram from 1-D data.
|
|
|
|
Notes
|
|
-----
|
|
Binary search is used to find the required insertion points.
|
|
|
|
As of NumPy 1.4.0 `searchsorted` works with real/complex arrays containing
|
|
`nan` values. The enhanced sort order is documented in `sort`.
|
|
|
|
This function uses the same algorithm as the builtin python `bisect.bisect_left`
|
|
(``side='left'``) and `bisect.bisect_right` (``side='right'``) functions,
|
|
which is also vectorized in the `v` argument.
|
|
|
|
Examples
|
|
--------
|
|
>>> np.searchsorted([1,2,3,4,5], 3)
|
|
2
|
|
>>> np.searchsorted([1,2,3,4,5], 3, side='right')
|
|
3
|
|
>>> np.searchsorted([1,2,3,4,5], [-10, 10, 2, 3])
|
|
array([0, 5, 1, 2])
|
|
|
|
"""
|
|
return _wrapfunc(a, 'searchsorted', v, side=side, sorter=sorter)
|
|
|
|
|
|
def _resize_dispatcher(a, new_shape):
|
|
return (a,)
|
|
|
|
|
|
@array_function_dispatch(_resize_dispatcher)
|
|
def resize(a, new_shape):
|
|
"""
|
|
Return a new array with the specified shape.
|
|
|
|
If the new array is larger than the original array, then the new
|
|
array is filled with repeated copies of `a`. Note that this behavior
|
|
is different from a.resize(new_shape) which fills with zeros instead
|
|
of repeated copies of `a`.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Array to be resized.
|
|
|
|
new_shape : int or tuple of int
|
|
Shape of resized array.
|
|
|
|
Returns
|
|
-------
|
|
reshaped_array : ndarray
|
|
The new array is formed from the data in the old array, repeated
|
|
if necessary to fill out the required number of elements. The
|
|
data are repeated in the order that they are stored in memory.
|
|
|
|
See Also
|
|
--------
|
|
ndarray.resize : resize an array in-place.
|
|
|
|
Notes
|
|
-----
|
|
Warning: This functionality does **not** consider axes separately,
|
|
i.e. it does not apply interpolation/extrapolation.
|
|
It fills the return array with the required number of elements, taken
|
|
from `a` as they are laid out in memory, disregarding strides and axes.
|
|
(This is in case the new shape is smaller. For larger, see above.)
|
|
This functionality is therefore not suitable to resize images,
|
|
or data where each axis represents a separate and distinct entity.
|
|
|
|
Examples
|
|
--------
|
|
>>> a=np.array([[0,1],[2,3]])
|
|
>>> np.resize(a,(2,3))
|
|
array([[0, 1, 2],
|
|
[3, 0, 1]])
|
|
>>> np.resize(a,(1,4))
|
|
array([[0, 1, 2, 3]])
|
|
>>> np.resize(a,(2,4))
|
|
array([[0, 1, 2, 3],
|
|
[0, 1, 2, 3]])
|
|
|
|
"""
|
|
if isinstance(new_shape, (int, nt.integer)):
|
|
new_shape = (new_shape,)
|
|
a = ravel(a)
|
|
Na = len(a)
|
|
total_size = um.multiply.reduce(new_shape)
|
|
if Na == 0 or total_size == 0:
|
|
return mu.zeros(new_shape, a.dtype)
|
|
|
|
n_copies = int(total_size / Na)
|
|
extra = total_size % Na
|
|
|
|
if extra != 0:
|
|
n_copies = n_copies + 1
|
|
extra = Na - extra
|
|
|
|
a = concatenate((a,) * n_copies)
|
|
if extra > 0:
|
|
a = a[:-extra]
|
|
|
|
return reshape(a, new_shape)
|
|
|
|
|
|
def _squeeze_dispatcher(a, axis=None):
|
|
return (a,)
|
|
|
|
|
|
@array_function_dispatch(_squeeze_dispatcher)
|
|
def squeeze(a, axis=None):
|
|
"""
|
|
Remove single-dimensional entries from the shape of an array.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input data.
|
|
axis : None or int or tuple of ints, optional
|
|
.. versionadded:: 1.7.0
|
|
|
|
Selects a subset of the single-dimensional entries in the
|
|
shape. If an axis is selected with shape entry greater than
|
|
one, an error is raised.
|
|
|
|
Returns
|
|
-------
|
|
squeezed : ndarray
|
|
The input array, but with all or a subset of the
|
|
dimensions of length 1 removed. This is always `a` itself
|
|
or a view into `a`.
|
|
|
|
Raises
|
|
------
|
|
ValueError
|
|
If `axis` is not `None`, and an axis being squeezed is not of length 1
|
|
|
|
See Also
|
|
--------
|
|
expand_dims : The inverse operation, adding singleton dimensions
|
|
reshape : Insert, remove, and combine dimensions, and resize existing ones
|
|
|
|
Examples
|
|
--------
|
|
>>> x = np.array([[[0], [1], [2]]])
|
|
>>> x.shape
|
|
(1, 3, 1)
|
|
>>> np.squeeze(x).shape
|
|
(3,)
|
|
>>> np.squeeze(x, axis=0).shape
|
|
(3, 1)
|
|
>>> np.squeeze(x, axis=1).shape
|
|
Traceback (most recent call last):
|
|
...
|
|
ValueError: cannot select an axis to squeeze out which has size not equal to one
|
|
>>> np.squeeze(x, axis=2).shape
|
|
(1, 3)
|
|
|
|
"""
|
|
try:
|
|
squeeze = a.squeeze
|
|
except AttributeError:
|
|
return _wrapit(a, 'squeeze', axis=axis)
|
|
if axis is None:
|
|
return squeeze()
|
|
else:
|
|
return squeeze(axis=axis)
|
|
|
|
|
|
def _diagonal_dispatcher(a, offset=None, axis1=None, axis2=None):
|
|
return (a,)
|
|
|
|
|
|
@array_function_dispatch(_diagonal_dispatcher)
|
|
def diagonal(a, offset=0, axis1=0, axis2=1):
|
|
"""
|
|
Return specified diagonals.
|
|
|
|
If `a` is 2-D, returns the diagonal of `a` with the given offset,
|
|
i.e., the collection of elements of the form ``a[i, i+offset]``. If
|
|
`a` has more than two dimensions, then the axes specified by `axis1`
|
|
and `axis2` are used to determine the 2-D sub-array whose diagonal is
|
|
returned. The shape of the resulting array can be determined by
|
|
removing `axis1` and `axis2` and appending an index to the right equal
|
|
to the size of the resulting diagonals.
|
|
|
|
In versions of NumPy prior to 1.7, this function always returned a new,
|
|
independent array containing a copy of the values in the diagonal.
|
|
|
|
In NumPy 1.7 and 1.8, it continues to return a copy of the diagonal,
|
|
but depending on this fact is deprecated. Writing to the resulting
|
|
array continues to work as it used to, but a FutureWarning is issued.
|
|
|
|
Starting in NumPy 1.9 it returns a read-only view on the original array.
|
|
Attempting to write to the resulting array will produce an error.
|
|
|
|
In some future release, it will return a read/write view and writing to
|
|
the returned array will alter your original array. The returned array
|
|
will have the same type as the input array.
|
|
|
|
If you don't write to the array returned by this function, then you can
|
|
just ignore all of the above.
|
|
|
|
If you depend on the current behavior, then we suggest copying the
|
|
returned array explicitly, i.e., use ``np.diagonal(a).copy()`` instead
|
|
of just ``np.diagonal(a)``. This will work with both past and future
|
|
versions of NumPy.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Array from which the diagonals are taken.
|
|
offset : int, optional
|
|
Offset of the diagonal from the main diagonal. Can be positive or
|
|
negative. Defaults to main diagonal (0).
|
|
axis1 : int, optional
|
|
Axis to be used as the first axis of the 2-D sub-arrays from which
|
|
the diagonals should be taken. Defaults to first axis (0).
|
|
axis2 : int, optional
|
|
Axis to be used as the second axis of the 2-D sub-arrays from
|
|
which the diagonals should be taken. Defaults to second axis (1).
|
|
|
|
Returns
|
|
-------
|
|
array_of_diagonals : ndarray
|
|
If `a` is 2-D, then a 1-D array containing the diagonal and of the
|
|
same type as `a` is returned unless `a` is a `matrix`, in which case
|
|
a 1-D array rather than a (2-D) `matrix` is returned in order to
|
|
maintain backward compatibility.
|
|
|
|
If ``a.ndim > 2``, then the dimensions specified by `axis1` and `axis2`
|
|
are removed, and a new axis inserted at the end corresponding to the
|
|
diagonal.
|
|
|
|
Raises
|
|
------
|
|
ValueError
|
|
If the dimension of `a` is less than 2.
|
|
|
|
See Also
|
|
--------
|
|
diag : MATLAB work-a-like for 1-D and 2-D arrays.
|
|
diagflat : Create diagonal arrays.
|
|
trace : Sum along diagonals.
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.arange(4).reshape(2,2)
|
|
>>> a
|
|
array([[0, 1],
|
|
[2, 3]])
|
|
>>> a.diagonal()
|
|
array([0, 3])
|
|
>>> a.diagonal(1)
|
|
array([1])
|
|
|
|
A 3-D example:
|
|
|
|
>>> a = np.arange(8).reshape(2,2,2); a
|
|
array([[[0, 1],
|
|
[2, 3]],
|
|
[[4, 5],
|
|
[6, 7]]])
|
|
>>> a.diagonal(0, # Main diagonals of two arrays created by skipping
|
|
... 0, # across the outer(left)-most axis last and
|
|
... 1) # the "middle" (row) axis first.
|
|
array([[0, 6],
|
|
[1, 7]])
|
|
|
|
The sub-arrays whose main diagonals we just obtained; note that each
|
|
corresponds to fixing the right-most (column) axis, and that the
|
|
diagonals are "packed" in rows.
|
|
|
|
>>> a[:,:,0] # main diagonal is [0 6]
|
|
array([[0, 2],
|
|
[4, 6]])
|
|
>>> a[:,:,1] # main diagonal is [1 7]
|
|
array([[1, 3],
|
|
[5, 7]])
|
|
|
|
The anti-diagonal can be obtained by reversing the order of elements
|
|
using either `numpy.flipud` or `numpy.fliplr`.
|
|
|
|
>>> a = np.arange(9).reshape(3, 3)
|
|
>>> a
|
|
array([[0, 1, 2],
|
|
[3, 4, 5],
|
|
[6, 7, 8]])
|
|
>>> np.fliplr(a).diagonal() # Horizontal flip
|
|
array([2, 4, 6])
|
|
>>> np.flipud(a).diagonal() # Vertical flip
|
|
array([6, 4, 2])
|
|
|
|
Note that the order in which the diagonal is retrieved varies depending
|
|
on the flip function.
|
|
"""
|
|
if isinstance(a, np.matrix):
|
|
# Make diagonal of matrix 1-D to preserve backward compatibility.
|
|
return asarray(a).diagonal(offset=offset, axis1=axis1, axis2=axis2)
|
|
else:
|
|
return asanyarray(a).diagonal(offset=offset, axis1=axis1, axis2=axis2)
|
|
|
|
|
|
def _trace_dispatcher(
|
|
a, offset=None, axis1=None, axis2=None, dtype=None, out=None):
|
|
return (a, out)
|
|
|
|
|
|
@array_function_dispatch(_trace_dispatcher)
|
|
def trace(a, offset=0, axis1=0, axis2=1, dtype=None, out=None):
|
|
"""
|
|
Return the sum along diagonals of the array.
|
|
|
|
If `a` is 2-D, the sum along its diagonal with the given offset
|
|
is returned, i.e., the sum of elements ``a[i,i+offset]`` for all i.
|
|
|
|
If `a` has more than two dimensions, then the axes specified by axis1 and
|
|
axis2 are used to determine the 2-D sub-arrays whose traces are returned.
|
|
The shape of the resulting array is the same as that of `a` with `axis1`
|
|
and `axis2` removed.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input array, from which the diagonals are taken.
|
|
offset : int, optional
|
|
Offset of the diagonal from the main diagonal. Can be both positive
|
|
and negative. Defaults to 0.
|
|
axis1, axis2 : int, optional
|
|
Axes to be used as the first and second axis of the 2-D sub-arrays
|
|
from which the diagonals should be taken. Defaults are the first two
|
|
axes of `a`.
|
|
dtype : dtype, optional
|
|
Determines the data-type of the returned array and of the accumulator
|
|
where the elements are summed. If dtype has the value None and `a` is
|
|
of integer type of precision less than the default integer
|
|
precision, then the default integer precision is used. Otherwise,
|
|
the precision is the same as that of `a`.
|
|
out : ndarray, optional
|
|
Array into which the output is placed. Its type is preserved and
|
|
it must be of the right shape to hold the output.
|
|
|
|
Returns
|
|
-------
|
|
sum_along_diagonals : ndarray
|
|
If `a` is 2-D, the sum along the diagonal is returned. If `a` has
|
|
larger dimensions, then an array of sums along diagonals is returned.
|
|
|
|
See Also
|
|
--------
|
|
diag, diagonal, diagflat
|
|
|
|
Examples
|
|
--------
|
|
>>> np.trace(np.eye(3))
|
|
3.0
|
|
>>> a = np.arange(8).reshape((2,2,2))
|
|
>>> np.trace(a)
|
|
array([6, 8])
|
|
|
|
>>> a = np.arange(24).reshape((2,2,2,3))
|
|
>>> np.trace(a).shape
|
|
(2, 3)
|
|
|
|
"""
|
|
if isinstance(a, np.matrix):
|
|
# Get trace of matrix via an array to preserve backward compatibility.
|
|
return asarray(a).trace(offset=offset, axis1=axis1, axis2=axis2, dtype=dtype, out=out)
|
|
else:
|
|
return asanyarray(a).trace(offset=offset, axis1=axis1, axis2=axis2, dtype=dtype, out=out)
|
|
|
|
|
|
def _ravel_dispatcher(a, order=None):
|
|
return (a,)
|
|
|
|
|
|
@array_function_dispatch(_ravel_dispatcher)
|
|
def ravel(a, order='C'):
|
|
"""Return a contiguous flattened array.
|
|
|
|
A 1-D array, containing the elements of the input, is returned. A copy is
|
|
made only if needed.
|
|
|
|
As of NumPy 1.10, the returned array will have the same type as the input
|
|
array. (for example, a masked array will be returned for a masked array
|
|
input)
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input array. The elements in `a` are read in the order specified by
|
|
`order`, and packed as a 1-D array.
|
|
order : {'C','F', 'A', 'K'}, optional
|
|
|
|
The elements of `a` are read using this index order. 'C' means
|
|
to index the elements in row-major, C-style order,
|
|
with the last axis index changing fastest, back to the first
|
|
axis index changing slowest. 'F' means to index the elements
|
|
in column-major, Fortran-style order, with the
|
|
first index changing fastest, and the last index changing
|
|
slowest. Note that the 'C' and 'F' options take no account of
|
|
the memory layout of the underlying array, and only refer to
|
|
the order of axis indexing. 'A' means to read the elements in
|
|
Fortran-like index order if `a` is Fortran *contiguous* in
|
|
memory, C-like order otherwise. 'K' means to read the
|
|
elements in the order they occur in memory, except for
|
|
reversing the data when strides are negative. By default, 'C'
|
|
index order is used.
|
|
|
|
Returns
|
|
-------
|
|
y : array_like
|
|
y is an array of the same subtype as `a`, with shape ``(a.size,)``.
|
|
Note that matrices are special cased for backward compatibility, if `a`
|
|
is a matrix, then y is a 1-D ndarray.
|
|
|
|
See Also
|
|
--------
|
|
ndarray.flat : 1-D iterator over an array.
|
|
ndarray.flatten : 1-D array copy of the elements of an array
|
|
in row-major order.
|
|
ndarray.reshape : Change the shape of an array without changing its data.
|
|
|
|
Notes
|
|
-----
|
|
In row-major, C-style order, in two dimensions, the row index
|
|
varies the slowest, and the column index the quickest. This can
|
|
be generalized to multiple dimensions, where row-major order
|
|
implies that the index along the first axis varies slowest, and
|
|
the index along the last quickest. The opposite holds for
|
|
column-major, Fortran-style index ordering.
|
|
|
|
When a view is desired in as many cases as possible, ``arr.reshape(-1)``
|
|
may be preferable.
|
|
|
|
Examples
|
|
--------
|
|
It is equivalent to ``reshape(-1, order=order)``.
|
|
|
|
>>> x = np.array([[1, 2, 3], [4, 5, 6]])
|
|
>>> np.ravel(x)
|
|
array([1, 2, 3, 4, 5, 6])
|
|
|
|
>>> x.reshape(-1)
|
|
array([1, 2, 3, 4, 5, 6])
|
|
|
|
>>> np.ravel(x, order='F')
|
|
array([1, 4, 2, 5, 3, 6])
|
|
|
|
When ``order`` is 'A', it will preserve the array's 'C' or 'F' ordering:
|
|
|
|
>>> np.ravel(x.T)
|
|
array([1, 4, 2, 5, 3, 6])
|
|
>>> np.ravel(x.T, order='A')
|
|
array([1, 2, 3, 4, 5, 6])
|
|
|
|
When ``order`` is 'K', it will preserve orderings that are neither 'C'
|
|
nor 'F', but won't reverse axes:
|
|
|
|
>>> a = np.arange(3)[::-1]; a
|
|
array([2, 1, 0])
|
|
>>> a.ravel(order='C')
|
|
array([2, 1, 0])
|
|
>>> a.ravel(order='K')
|
|
array([2, 1, 0])
|
|
|
|
>>> a = np.arange(12).reshape(2,3,2).swapaxes(1,2); a
|
|
array([[[ 0, 2, 4],
|
|
[ 1, 3, 5]],
|
|
[[ 6, 8, 10],
|
|
[ 7, 9, 11]]])
|
|
>>> a.ravel(order='C')
|
|
array([ 0, 2, 4, 1, 3, 5, 6, 8, 10, 7, 9, 11])
|
|
>>> a.ravel(order='K')
|
|
array([ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
|
|
|
|
"""
|
|
if isinstance(a, np.matrix):
|
|
return asarray(a).ravel(order=order)
|
|
else:
|
|
return asanyarray(a).ravel(order=order)
|
|
|
|
|
|
def _nonzero_dispatcher(a):
|
|
return (a,)
|
|
|
|
|
|
@array_function_dispatch(_nonzero_dispatcher)
|
|
def nonzero(a):
|
|
"""
|
|
Return the indices of the elements that are non-zero.
|
|
|
|
Returns a tuple of arrays, one for each dimension of `a`,
|
|
containing the indices of the non-zero elements in that
|
|
dimension. The values in `a` are always tested and returned in
|
|
row-major, C-style order.
|
|
|
|
To group the indices by element, rather than dimension, use `argwhere`,
|
|
which returns a row for each non-zero element.
|
|
|
|
.. note::
|
|
When called on a zero-d array or scalar, ``nonzero(a)`` is treated
|
|
as ``nonzero(atleast1d(a))``.
|
|
|
|
..deprecated:: 1.17.0
|
|
Use `atleast1d` explicitly if this behavior is deliberate.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input array.
|
|
|
|
Returns
|
|
-------
|
|
tuple_of_arrays : tuple
|
|
Indices of elements that are non-zero.
|
|
|
|
See Also
|
|
--------
|
|
flatnonzero :
|
|
Return indices that are non-zero in the flattened version of the input
|
|
array.
|
|
ndarray.nonzero :
|
|
Equivalent ndarray method.
|
|
count_nonzero :
|
|
Counts the number of non-zero elements in the input array.
|
|
|
|
Notes
|
|
-----
|
|
While the nonzero values can be obtained with ``a[nonzero(a)]``, it is
|
|
recommended to use ``x[x.astype(bool)]`` or ``x[x != 0]`` instead, which
|
|
will correctly handle 0-d arrays.
|
|
|
|
Examples
|
|
--------
|
|
>>> x = np.array([[3, 0, 0], [0, 4, 0], [5, 6, 0]])
|
|
>>> x
|
|
array([[3, 0, 0],
|
|
[0, 4, 0],
|
|
[5, 6, 0]])
|
|
>>> np.nonzero(x)
|
|
(array([0, 1, 2, 2]), array([0, 1, 0, 1]))
|
|
|
|
>>> x[np.nonzero(x)]
|
|
array([3, 4, 5, 6])
|
|
>>> np.transpose(np.nonzero(x))
|
|
array([[0, 0],
|
|
[1, 1],
|
|
[2, 0],
|
|
[2, 1]])
|
|
|
|
A common use for ``nonzero`` is to find the indices of an array, where
|
|
a condition is True. Given an array `a`, the condition `a` > 3 is a
|
|
boolean array and since False is interpreted as 0, np.nonzero(a > 3)
|
|
yields the indices of the `a` where the condition is true.
|
|
|
|
>>> a = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
|
|
>>> a > 3
|
|
array([[False, False, False],
|
|
[ True, True, True],
|
|
[ True, True, True]])
|
|
>>> np.nonzero(a > 3)
|
|
(array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))
|
|
|
|
Using this result to index `a` is equivalent to using the mask directly:
|
|
|
|
>>> a[np.nonzero(a > 3)]
|
|
array([4, 5, 6, 7, 8, 9])
|
|
>>> a[a > 3] # prefer this spelling
|
|
array([4, 5, 6, 7, 8, 9])
|
|
|
|
``nonzero`` can also be called as a method of the array.
|
|
|
|
>>> (a > 3).nonzero()
|
|
(array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))
|
|
|
|
"""
|
|
return _wrapfunc(a, 'nonzero')
|
|
|
|
|
|
def _shape_dispatcher(a):
|
|
return (a,)
|
|
|
|
|
|
@array_function_dispatch(_shape_dispatcher)
|
|
def shape(a):
|
|
"""
|
|
Return the shape of an array.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input array.
|
|
|
|
Returns
|
|
-------
|
|
shape : tuple of ints
|
|
The elements of the shape tuple give the lengths of the
|
|
corresponding array dimensions.
|
|
|
|
See Also
|
|
--------
|
|
alen
|
|
ndarray.shape : Equivalent array method.
|
|
|
|
Examples
|
|
--------
|
|
>>> np.shape(np.eye(3))
|
|
(3, 3)
|
|
>>> np.shape([[1, 2]])
|
|
(1, 2)
|
|
>>> np.shape([0])
|
|
(1,)
|
|
>>> np.shape(0)
|
|
()
|
|
|
|
>>> a = np.array([(1, 2), (3, 4)], dtype=[('x', 'i4'), ('y', 'i4')])
|
|
>>> np.shape(a)
|
|
(2,)
|
|
>>> a.shape
|
|
(2,)
|
|
|
|
"""
|
|
try:
|
|
result = a.shape
|
|
except AttributeError:
|
|
result = asarray(a).shape
|
|
return result
|
|
|
|
|
|
def _compress_dispatcher(condition, a, axis=None, out=None):
|
|
return (condition, a, out)
|
|
|
|
|
|
@array_function_dispatch(_compress_dispatcher)
|
|
def compress(condition, a, axis=None, out=None):
|
|
"""
|
|
Return selected slices of an array along given axis.
|
|
|
|
When working along a given axis, a slice along that axis is returned in
|
|
`output` for each index where `condition` evaluates to True. When
|
|
working on a 1-D array, `compress` is equivalent to `extract`.
|
|
|
|
Parameters
|
|
----------
|
|
condition : 1-D array of bools
|
|
Array that selects which entries to return. If len(condition)
|
|
is less than the size of `a` along the given axis, then output is
|
|
truncated to the length of the condition array.
|
|
a : array_like
|
|
Array from which to extract a part.
|
|
axis : int, optional
|
|
Axis along which to take slices. If None (default), work on the
|
|
flattened array.
|
|
out : ndarray, optional
|
|
Output array. Its type is preserved and it must be of the right
|
|
shape to hold the output.
|
|
|
|
Returns
|
|
-------
|
|
compressed_array : ndarray
|
|
A copy of `a` without the slices along axis for which `condition`
|
|
is false.
|
|
|
|
See Also
|
|
--------
|
|
take, choose, diag, diagonal, select
|
|
ndarray.compress : Equivalent method in ndarray
|
|
np.extract: Equivalent method when working on 1-D arrays
|
|
numpy.doc.ufuncs : Section "Output arguments"
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.array([[1, 2], [3, 4], [5, 6]])
|
|
>>> a
|
|
array([[1, 2],
|
|
[3, 4],
|
|
[5, 6]])
|
|
>>> np.compress([0, 1], a, axis=0)
|
|
array([[3, 4]])
|
|
>>> np.compress([False, True, True], a, axis=0)
|
|
array([[3, 4],
|
|
[5, 6]])
|
|
>>> np.compress([False, True], a, axis=1)
|
|
array([[2],
|
|
[4],
|
|
[6]])
|
|
|
|
Working on the flattened array does not return slices along an axis but
|
|
selects elements.
|
|
|
|
>>> np.compress([False, True], a)
|
|
array([2])
|
|
|
|
"""
|
|
return _wrapfunc(a, 'compress', condition, axis=axis, out=out)
|
|
|
|
|
|
def _clip_dispatcher(a, a_min, a_max, out=None, **kwargs):
|
|
return (a, a_min, a_max)
|
|
|
|
|
|
@array_function_dispatch(_clip_dispatcher)
|
|
def clip(a, a_min, a_max, out=None, **kwargs):
|
|
"""
|
|
Clip (limit) the values in an array.
|
|
|
|
Given an interval, values outside the interval are clipped to
|
|
the interval edges. For example, if an interval of ``[0, 1]``
|
|
is specified, values smaller than 0 become 0, and values larger
|
|
than 1 become 1.
|
|
|
|
Equivalent to but faster than ``np.maximum(a_min, np.minimum(a, a_max))``.
|
|
No check is performed to ensure ``a_min < a_max``.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Array containing elements to clip.
|
|
a_min : scalar or array_like or `None`
|
|
Minimum value. If `None`, clipping is not performed on lower
|
|
interval edge. Not more than one of `a_min` and `a_max` may be
|
|
`None`.
|
|
a_max : scalar or array_like or `None`
|
|
Maximum value. If `None`, clipping is not performed on upper
|
|
interval edge. Not more than one of `a_min` and `a_max` may be
|
|
`None`. If `a_min` or `a_max` are array_like, then the three
|
|
arrays will be broadcasted to match their shapes.
|
|
out : ndarray, optional
|
|
The results will be placed in this array. It may be the input
|
|
array for in-place clipping. `out` must be of the right shape
|
|
to hold the output. Its type is preserved.
|
|
**kwargs
|
|
For other keyword-only arguments, see the
|
|
:ref:`ufunc docs <ufuncs.kwargs>`.
|
|
|
|
.. versionadded:: 1.17.0
|
|
|
|
Returns
|
|
-------
|
|
clipped_array : ndarray
|
|
An array with the elements of `a`, but where values
|
|
< `a_min` are replaced with `a_min`, and those > `a_max`
|
|
with `a_max`.
|
|
|
|
See Also
|
|
--------
|
|
numpy.doc.ufuncs : Section "Output arguments"
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.arange(10)
|
|
>>> np.clip(a, 1, 8)
|
|
array([1, 1, 2, 3, 4, 5, 6, 7, 8, 8])
|
|
>>> a
|
|
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
|
|
>>> np.clip(a, 3, 6, out=a)
|
|
array([3, 3, 3, 3, 4, 5, 6, 6, 6, 6])
|
|
>>> a = np.arange(10)
|
|
>>> a
|
|
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
|
|
>>> np.clip(a, [3, 4, 1, 1, 1, 4, 4, 4, 4, 4], 8)
|
|
array([3, 4, 2, 3, 4, 5, 6, 7, 8, 8])
|
|
|
|
"""
|
|
return _wrapfunc(a, 'clip', a_min, a_max, out=out, **kwargs)
|
|
|
|
|
|
def _sum_dispatcher(a, axis=None, dtype=None, out=None, keepdims=None,
|
|
initial=None, where=None):
|
|
return (a, out)
|
|
|
|
|
|
@array_function_dispatch(_sum_dispatcher)
|
|
def sum(a, axis=None, dtype=None, out=None, keepdims=np._NoValue,
|
|
initial=np._NoValue, where=np._NoValue):
|
|
"""
|
|
Sum of array elements over a given axis.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Elements to sum.
|
|
axis : None or int or tuple of ints, optional
|
|
Axis or axes along which a sum is performed. The default,
|
|
axis=None, will sum all of the elements of the input array. If
|
|
axis is negative it counts from the last to the first axis.
|
|
|
|
.. versionadded:: 1.7.0
|
|
|
|
If axis is a tuple of ints, a sum is performed on all of the axes
|
|
specified in the tuple instead of a single axis or all the axes as
|
|
before.
|
|
dtype : dtype, optional
|
|
The type of the returned array and of the accumulator in which the
|
|
elements are summed. The dtype of `a` is used by default unless `a`
|
|
has an integer dtype of less precision than the default platform
|
|
integer. In that case, if `a` is signed then the platform integer
|
|
is used while if `a` is unsigned then an unsigned integer of the
|
|
same precision as the platform integer is used.
|
|
out : ndarray, optional
|
|
Alternative output array in which to place the result. It must have
|
|
the same shape as the expected output, but the type of the output
|
|
values will be cast if necessary.
|
|
keepdims : bool, optional
|
|
If this is set to True, the axes which are reduced are left
|
|
in the result as dimensions with size one. With this option,
|
|
the result will broadcast correctly against the input array.
|
|
|
|
If the default value is passed, then `keepdims` will not be
|
|
passed through to the `sum` method of sub-classes of
|
|
`ndarray`, however any non-default value will be. If the
|
|
sub-class' method does not implement `keepdims` any
|
|
exceptions will be raised.
|
|
initial : scalar, optional
|
|
Starting value for the sum. See `~numpy.ufunc.reduce` for details.
|
|
|
|
.. versionadded:: 1.15.0
|
|
|
|
where : array_like of bool, optional
|
|
Elements to include in the sum. See `~numpy.ufunc.reduce` for details.
|
|
|
|
.. versionadded:: 1.17.0
|
|
|
|
Returns
|
|
-------
|
|
sum_along_axis : ndarray
|
|
An array with the same shape as `a`, with the specified
|
|
axis removed. If `a` is a 0-d array, or if `axis` is None, a scalar
|
|
is returned. If an output array is specified, a reference to
|
|
`out` is returned.
|
|
|
|
See Also
|
|
--------
|
|
ndarray.sum : Equivalent method.
|
|
|
|
add.reduce : Equivalent functionality of `add`.
|
|
|
|
cumsum : Cumulative sum of array elements.
|
|
|
|
trapz : Integration of array values using the composite trapezoidal rule.
|
|
|
|
mean, average
|
|
|
|
Notes
|
|
-----
|
|
Arithmetic is modular when using integer types, and no error is
|
|
raised on overflow.
|
|
|
|
The sum of an empty array is the neutral element 0:
|
|
|
|
>>> np.sum([])
|
|
0.0
|
|
|
|
For floating point numbers the numerical precision of sum (and
|
|
``np.add.reduce``) is in general limited by directly adding each number
|
|
individually to the result causing rounding errors in every step.
|
|
However, often numpy will use a numerically better approach (partial
|
|
pairwise summation) leading to improved precision in many use-cases.
|
|
This improved precision is always provided when no ``axis`` is given.
|
|
When ``axis`` is given, it will depend on which axis is summed.
|
|
Technically, to provide the best speed possible, the improved precision
|
|
is only used when the summation is along the fast axis in memory.
|
|
Note that the exact precision may vary depending on other parameters.
|
|
In contrast to NumPy, Python's ``math.fsum`` function uses a slower but
|
|
more precise approach to summation.
|
|
Especially when summing a large number of lower precision floating point
|
|
numbers, such as ``float32``, numerical errors can become significant.
|
|
In such cases it can be advisable to use `dtype="float64"` to use a higher
|
|
precision for the output.
|
|
|
|
Examples
|
|
--------
|
|
>>> np.sum([0.5, 1.5])
|
|
2.0
|
|
>>> np.sum([0.5, 0.7, 0.2, 1.5], dtype=np.int32)
|
|
1
|
|
>>> np.sum([[0, 1], [0, 5]])
|
|
6
|
|
>>> np.sum([[0, 1], [0, 5]], axis=0)
|
|
array([0, 6])
|
|
>>> np.sum([[0, 1], [0, 5]], axis=1)
|
|
array([1, 5])
|
|
>>> np.sum([[0, 1], [np.nan, 5]], where=[False, True], axis=1)
|
|
array([1., 5.])
|
|
|
|
If the accumulator is too small, overflow occurs:
|
|
|
|
>>> np.ones(128, dtype=np.int8).sum(dtype=np.int8)
|
|
-128
|
|
|
|
You can also start the sum with a value other than zero:
|
|
|
|
>>> np.sum([10], initial=5)
|
|
15
|
|
"""
|
|
if isinstance(a, _gentype):
|
|
# 2018-02-25, 1.15.0
|
|
warnings.warn(
|
|
"Calling np.sum(generator) is deprecated, and in the future will give a different result. "
|
|
"Use np.sum(np.fromiter(generator)) or the python sum builtin instead.",
|
|
DeprecationWarning, stacklevel=3)
|
|
|
|
res = _sum_(a)
|
|
if out is not None:
|
|
out[...] = res
|
|
return out
|
|
return res
|
|
|
|
return _wrapreduction(a, np.add, 'sum', axis, dtype, out, keepdims=keepdims,
|
|
initial=initial, where=where)
|
|
|
|
|
|
def _any_dispatcher(a, axis=None, out=None, keepdims=None):
|
|
return (a, out)
|
|
|
|
|
|
@array_function_dispatch(_any_dispatcher)
|
|
def any(a, axis=None, out=None, keepdims=np._NoValue):
|
|
"""
|
|
Test whether any array element along a given axis evaluates to True.
|
|
|
|
Returns single boolean unless `axis` is not ``None``
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input array or object that can be converted to an array.
|
|
axis : None or int or tuple of ints, optional
|
|
Axis or axes along which a logical OR reduction is performed.
|
|
The default (`axis` = `None`) is to perform a logical OR over all
|
|
the dimensions of the input array. `axis` may be negative, in
|
|
which case it counts from the last to the first axis.
|
|
|
|
.. versionadded:: 1.7.0
|
|
|
|
If this is a tuple of ints, a reduction is performed on multiple
|
|
axes, instead of a single axis or all the axes as before.
|
|
out : ndarray, optional
|
|
Alternate output array in which to place the result. It must have
|
|
the same shape as the expected output and its type is preserved
|
|
(e.g., if it is of type float, then it will remain so, returning
|
|
1.0 for True and 0.0 for False, regardless of the type of `a`).
|
|
See `doc.ufuncs` (Section "Output arguments") for details.
|
|
|
|
keepdims : bool, optional
|
|
If this is set to True, the axes which are reduced are left
|
|
in the result as dimensions with size one. With this option,
|
|
the result will broadcast correctly against the input array.
|
|
|
|
If the default value is passed, then `keepdims` will not be
|
|
passed through to the `any` method of sub-classes of
|
|
`ndarray`, however any non-default value will be. If the
|
|
sub-class' method does not implement `keepdims` any
|
|
exceptions will be raised.
|
|
|
|
Returns
|
|
-------
|
|
any : bool or ndarray
|
|
A new boolean or `ndarray` is returned unless `out` is specified,
|
|
in which case a reference to `out` is returned.
|
|
|
|
See Also
|
|
--------
|
|
ndarray.any : equivalent method
|
|
|
|
all : Test whether all elements along a given axis evaluate to True.
|
|
|
|
Notes
|
|
-----
|
|
Not a Number (NaN), positive infinity and negative infinity evaluate
|
|
to `True` because these are not equal to zero.
|
|
|
|
Examples
|
|
--------
|
|
>>> np.any([[True, False], [True, True]])
|
|
True
|
|
|
|
>>> np.any([[True, False], [False, False]], axis=0)
|
|
array([ True, False])
|
|
|
|
>>> np.any([-1, 0, 5])
|
|
True
|
|
|
|
>>> np.any(np.nan)
|
|
True
|
|
|
|
>>> o=np.array(False)
|
|
>>> z=np.any([-1, 4, 5], out=o)
|
|
>>> z, o
|
|
(array(True), array(True))
|
|
>>> # Check now that z is a reference to o
|
|
>>> z is o
|
|
True
|
|
>>> id(z), id(o) # identity of z and o # doctest: +SKIP
|
|
(191614240, 191614240)
|
|
|
|
"""
|
|
return _wrapreduction(a, np.logical_or, 'any', axis, None, out, keepdims=keepdims)
|
|
|
|
|
|
def _all_dispatcher(a, axis=None, out=None, keepdims=None):
|
|
return (a, out)
|
|
|
|
|
|
@array_function_dispatch(_all_dispatcher)
|
|
def all(a, axis=None, out=None, keepdims=np._NoValue):
|
|
"""
|
|
Test whether all array elements along a given axis evaluate to True.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input array or object that can be converted to an array.
|
|
axis : None or int or tuple of ints, optional
|
|
Axis or axes along which a logical AND reduction is performed.
|
|
The default (`axis` = `None`) is to perform a logical AND over all
|
|
the dimensions of the input array. `axis` may be negative, in
|
|
which case it counts from the last to the first axis.
|
|
|
|
.. versionadded:: 1.7.0
|
|
|
|
If this is a tuple of ints, a reduction is performed on multiple
|
|
axes, instead of a single axis or all the axes as before.
|
|
out : ndarray, optional
|
|
Alternate output array in which to place the result.
|
|
It must have the same shape as the expected output and its
|
|
type is preserved (e.g., if ``dtype(out)`` is float, the result
|
|
will consist of 0.0's and 1.0's). See `doc.ufuncs` (Section
|
|
"Output arguments") for more details.
|
|
|
|
keepdims : bool, optional
|
|
If this is set to True, the axes which are reduced are left
|
|
in the result as dimensions with size one. With this option,
|
|
the result will broadcast correctly against the input array.
|
|
|
|
If the default value is passed, then `keepdims` will not be
|
|
passed through to the `all` method of sub-classes of
|
|
`ndarray`, however any non-default value will be. If the
|
|
sub-class' method does not implement `keepdims` any
|
|
exceptions will be raised.
|
|
|
|
Returns
|
|
-------
|
|
all : ndarray, bool
|
|
A new boolean or array is returned unless `out` is specified,
|
|
in which case a reference to `out` is returned.
|
|
|
|
See Also
|
|
--------
|
|
ndarray.all : equivalent method
|
|
|
|
any : Test whether any element along a given axis evaluates to True.
|
|
|
|
Notes
|
|
-----
|
|
Not a Number (NaN), positive infinity and negative infinity
|
|
evaluate to `True` because these are not equal to zero.
|
|
|
|
Examples
|
|
--------
|
|
>>> np.all([[True,False],[True,True]])
|
|
False
|
|
|
|
>>> np.all([[True,False],[True,True]], axis=0)
|
|
array([ True, False])
|
|
|
|
>>> np.all([-1, 4, 5])
|
|
True
|
|
|
|
>>> np.all([1.0, np.nan])
|
|
True
|
|
|
|
>>> o=np.array(False)
|
|
>>> z=np.all([-1, 4, 5], out=o)
|
|
>>> id(z), id(o), z
|
|
(28293632, 28293632, array(True)) # may vary
|
|
|
|
"""
|
|
return _wrapreduction(a, np.logical_and, 'all', axis, None, out, keepdims=keepdims)
|
|
|
|
|
|
def _cumsum_dispatcher(a, axis=None, dtype=None, out=None):
|
|
return (a, out)
|
|
|
|
|
|
@array_function_dispatch(_cumsum_dispatcher)
|
|
def cumsum(a, axis=None, dtype=None, out=None):
|
|
"""
|
|
Return the cumulative sum of the elements along a given axis.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input array.
|
|
axis : int, optional
|
|
Axis along which the cumulative sum is computed. The default
|
|
(None) is to compute the cumsum over the flattened array.
|
|
dtype : dtype, optional
|
|
Type of the returned array and of the accumulator in which the
|
|
elements are summed. If `dtype` is not specified, it defaults
|
|
to the dtype of `a`, unless `a` has an integer dtype with a
|
|
precision less than that of the default platform integer. In
|
|
that case, the default platform integer is used.
|
|
out : ndarray, optional
|
|
Alternative output array in which to place the result. It must
|
|
have the same shape and buffer length as the expected output
|
|
but the type will be cast if necessary. See `doc.ufuncs`
|
|
(Section "Output arguments") for more details.
|
|
|
|
Returns
|
|
-------
|
|
cumsum_along_axis : ndarray.
|
|
A new array holding the result is returned unless `out` is
|
|
specified, in which case a reference to `out` is returned. The
|
|
result has the same size as `a`, and the same shape as `a` if
|
|
`axis` is not None or `a` is a 1-d array.
|
|
|
|
|
|
See Also
|
|
--------
|
|
sum : Sum array elements.
|
|
|
|
trapz : Integration of array values using the composite trapezoidal rule.
|
|
|
|
diff : Calculate the n-th discrete difference along given axis.
|
|
|
|
Notes
|
|
-----
|
|
Arithmetic is modular when using integer types, and no error is
|
|
raised on overflow.
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.array([[1,2,3], [4,5,6]])
|
|
>>> a
|
|
array([[1, 2, 3],
|
|
[4, 5, 6]])
|
|
>>> np.cumsum(a)
|
|
array([ 1, 3, 6, 10, 15, 21])
|
|
>>> np.cumsum(a, dtype=float) # specifies type of output value(s)
|
|
array([ 1., 3., 6., 10., 15., 21.])
|
|
|
|
>>> np.cumsum(a,axis=0) # sum over rows for each of the 3 columns
|
|
array([[1, 2, 3],
|
|
[5, 7, 9]])
|
|
>>> np.cumsum(a,axis=1) # sum over columns for each of the 2 rows
|
|
array([[ 1, 3, 6],
|
|
[ 4, 9, 15]])
|
|
|
|
"""
|
|
return _wrapfunc(a, 'cumsum', axis=axis, dtype=dtype, out=out)
|
|
|
|
|
|
def _ptp_dispatcher(a, axis=None, out=None, keepdims=None):
|
|
return (a, out)
|
|
|
|
|
|
@array_function_dispatch(_ptp_dispatcher)
|
|
def ptp(a, axis=None, out=None, keepdims=np._NoValue):
|
|
"""
|
|
Range of values (maximum - minimum) along an axis.
|
|
|
|
The name of the function comes from the acronym for 'peak to peak'.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input values.
|
|
axis : None or int or tuple of ints, optional
|
|
Axis along which to find the peaks. By default, flatten the
|
|
array. `axis` may be negative, in
|
|
which case it counts from the last to the first axis.
|
|
|
|
.. versionadded:: 1.15.0
|
|
|
|
If this is a tuple of ints, a reduction is performed on multiple
|
|
axes, instead of a single axis or all the axes as before.
|
|
out : array_like
|
|
Alternative output array in which to place the result. It must
|
|
have the same shape and buffer length as the expected output,
|
|
but the type of the output values will be cast if necessary.
|
|
|
|
keepdims : bool, optional
|
|
If this is set to True, the axes which are reduced are left
|
|
in the result as dimensions with size one. With this option,
|
|
the result will broadcast correctly against the input array.
|
|
|
|
If the default value is passed, then `keepdims` will not be
|
|
passed through to the `ptp` method of sub-classes of
|
|
`ndarray`, however any non-default value will be. If the
|
|
sub-class' method does not implement `keepdims` any
|
|
exceptions will be raised.
|
|
|
|
Returns
|
|
-------
|
|
ptp : ndarray
|
|
A new array holding the result, unless `out` was
|
|
specified, in which case a reference to `out` is returned.
|
|
|
|
Examples
|
|
--------
|
|
>>> x = np.arange(4).reshape((2,2))
|
|
>>> x
|
|
array([[0, 1],
|
|
[2, 3]])
|
|
|
|
>>> np.ptp(x, axis=0)
|
|
array([2, 2])
|
|
|
|
>>> np.ptp(x, axis=1)
|
|
array([1, 1])
|
|
|
|
"""
|
|
kwargs = {}
|
|
if keepdims is not np._NoValue:
|
|
kwargs['keepdims'] = keepdims
|
|
if type(a) is not mu.ndarray:
|
|
try:
|
|
ptp = a.ptp
|
|
except AttributeError:
|
|
pass
|
|
else:
|
|
return ptp(axis=axis, out=out, **kwargs)
|
|
return _methods._ptp(a, axis=axis, out=out, **kwargs)
|
|
|
|
|
|
def _amax_dispatcher(a, axis=None, out=None, keepdims=None, initial=None,
|
|
where=None):
|
|
return (a, out)
|
|
|
|
|
|
@array_function_dispatch(_amax_dispatcher)
|
|
def amax(a, axis=None, out=None, keepdims=np._NoValue, initial=np._NoValue,
|
|
where=np._NoValue):
|
|
"""
|
|
Return the maximum of an array or maximum along an axis.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input data.
|
|
axis : None or int or tuple of ints, optional
|
|
Axis or axes along which to operate. By default, flattened input is
|
|
used.
|
|
|
|
.. versionadded:: 1.7.0
|
|
|
|
If this is a tuple of ints, the maximum is selected over multiple axes,
|
|
instead of a single axis or all the axes as before.
|
|
out : ndarray, optional
|
|
Alternative output array in which to place the result. Must
|
|
be of the same shape and buffer length as the expected output.
|
|
See `doc.ufuncs` (Section "Output arguments") for more details.
|
|
|
|
keepdims : bool, optional
|
|
If this is set to True, the axes which are reduced are left
|
|
in the result as dimensions with size one. With this option,
|
|
the result will broadcast correctly against the input array.
|
|
|
|
If the default value is passed, then `keepdims` will not be
|
|
passed through to the `amax` method of sub-classes of
|
|
`ndarray`, however any non-default value will be. If the
|
|
sub-class' method does not implement `keepdims` any
|
|
exceptions will be raised.
|
|
|
|
initial : scalar, optional
|
|
The minimum value of an output element. Must be present to allow
|
|
computation on empty slice. See `~numpy.ufunc.reduce` for details.
|
|
|
|
.. versionadded:: 1.15.0
|
|
|
|
where : array_like of bool, optional
|
|
Elements to compare for the maximum. See `~numpy.ufunc.reduce`
|
|
for details.
|
|
|
|
.. versionadded:: 1.17.0
|
|
|
|
Returns
|
|
-------
|
|
amax : ndarray or scalar
|
|
Maximum of `a`. If `axis` is None, the result is a scalar value.
|
|
If `axis` is given, the result is an array of dimension
|
|
``a.ndim - 1``.
|
|
|
|
See Also
|
|
--------
|
|
amin :
|
|
The minimum value of an array along a given axis, propagating any NaNs.
|
|
nanmax :
|
|
The maximum value of an array along a given axis, ignoring any NaNs.
|
|
maximum :
|
|
Element-wise maximum of two arrays, propagating any NaNs.
|
|
fmax :
|
|
Element-wise maximum of two arrays, ignoring any NaNs.
|
|
argmax :
|
|
Return the indices of the maximum values.
|
|
|
|
nanmin, minimum, fmin
|
|
|
|
Notes
|
|
-----
|
|
NaN values are propagated, that is if at least one item is NaN, the
|
|
corresponding max value will be NaN as well. To ignore NaN values
|
|
(MATLAB behavior), please use nanmax.
|
|
|
|
Don't use `amax` for element-wise comparison of 2 arrays; when
|
|
``a.shape[0]`` is 2, ``maximum(a[0], a[1])`` is faster than
|
|
``amax(a, axis=0)``.
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.arange(4).reshape((2,2))
|
|
>>> a
|
|
array([[0, 1],
|
|
[2, 3]])
|
|
>>> np.amax(a) # Maximum of the flattened array
|
|
3
|
|
>>> np.amax(a, axis=0) # Maxima along the first axis
|
|
array([2, 3])
|
|
>>> np.amax(a, axis=1) # Maxima along the second axis
|
|
array([1, 3])
|
|
>>> np.amax(a, where=[False, True], initial=-1, axis=0)
|
|
array([-1, 3])
|
|
>>> b = np.arange(5, dtype=float)
|
|
>>> b[2] = np.NaN
|
|
>>> np.amax(b)
|
|
nan
|
|
>>> np.amax(b, where=~np.isnan(b), initial=-1)
|
|
4.0
|
|
>>> np.nanmax(b)
|
|
4.0
|
|
|
|
You can use an initial value to compute the maximum of an empty slice, or
|
|
to initialize it to a different value:
|
|
|
|
>>> np.max([[-50], [10]], axis=-1, initial=0)
|
|
array([ 0, 10])
|
|
|
|
Notice that the initial value is used as one of the elements for which the
|
|
maximum is determined, unlike for the default argument Python's max
|
|
function, which is only used for empty iterables.
|
|
|
|
>>> np.max([5], initial=6)
|
|
6
|
|
>>> max([5], default=6)
|
|
5
|
|
"""
|
|
return _wrapreduction(a, np.maximum, 'max', axis, None, out,
|
|
keepdims=keepdims, initial=initial, where=where)
|
|
|
|
|
|
def _amin_dispatcher(a, axis=None, out=None, keepdims=None, initial=None,
|
|
where=None):
|
|
return (a, out)
|
|
|
|
|
|
@array_function_dispatch(_amin_dispatcher)
|
|
def amin(a, axis=None, out=None, keepdims=np._NoValue, initial=np._NoValue,
|
|
where=np._NoValue):
|
|
"""
|
|
Return the minimum of an array or minimum along an axis.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input data.
|
|
axis : None or int or tuple of ints, optional
|
|
Axis or axes along which to operate. By default, flattened input is
|
|
used.
|
|
|
|
.. versionadded:: 1.7.0
|
|
|
|
If this is a tuple of ints, the minimum is selected over multiple axes,
|
|
instead of a single axis or all the axes as before.
|
|
out : ndarray, optional
|
|
Alternative output array in which to place the result. Must
|
|
be of the same shape and buffer length as the expected output.
|
|
See `doc.ufuncs` (Section "Output arguments") for more details.
|
|
|
|
keepdims : bool, optional
|
|
If this is set to True, the axes which are reduced are left
|
|
in the result as dimensions with size one. With this option,
|
|
the result will broadcast correctly against the input array.
|
|
|
|
If the default value is passed, then `keepdims` will not be
|
|
passed through to the `amin` method of sub-classes of
|
|
`ndarray`, however any non-default value will be. If the
|
|
sub-class' method does not implement `keepdims` any
|
|
exceptions will be raised.
|
|
|
|
initial : scalar, optional
|
|
The maximum value of an output element. Must be present to allow
|
|
computation on empty slice. See `~numpy.ufunc.reduce` for details.
|
|
|
|
.. versionadded:: 1.15.0
|
|
|
|
where : array_like of bool, optional
|
|
Elements to compare for the minimum. See `~numpy.ufunc.reduce`
|
|
for details.
|
|
|
|
.. versionadded:: 1.17.0
|
|
|
|
Returns
|
|
-------
|
|
amin : ndarray or scalar
|
|
Minimum of `a`. If `axis` is None, the result is a scalar value.
|
|
If `axis` is given, the result is an array of dimension
|
|
``a.ndim - 1``.
|
|
|
|
See Also
|
|
--------
|
|
amax :
|
|
The maximum value of an array along a given axis, propagating any NaNs.
|
|
nanmin :
|
|
The minimum value of an array along a given axis, ignoring any NaNs.
|
|
minimum :
|
|
Element-wise minimum of two arrays, propagating any NaNs.
|
|
fmin :
|
|
Element-wise minimum of two arrays, ignoring any NaNs.
|
|
argmin :
|
|
Return the indices of the minimum values.
|
|
|
|
nanmax, maximum, fmax
|
|
|
|
Notes
|
|
-----
|
|
NaN values are propagated, that is if at least one item is NaN, the
|
|
corresponding min value will be NaN as well. To ignore NaN values
|
|
(MATLAB behavior), please use nanmin.
|
|
|
|
Don't use `amin` for element-wise comparison of 2 arrays; when
|
|
``a.shape[0]`` is 2, ``minimum(a[0], a[1])`` is faster than
|
|
``amin(a, axis=0)``.
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.arange(4).reshape((2,2))
|
|
>>> a
|
|
array([[0, 1],
|
|
[2, 3]])
|
|
>>> np.amin(a) # Minimum of the flattened array
|
|
0
|
|
>>> np.amin(a, axis=0) # Minima along the first axis
|
|
array([0, 1])
|
|
>>> np.amin(a, axis=1) # Minima along the second axis
|
|
array([0, 2])
|
|
>>> np.amin(a, where=[False, True], initial=10, axis=0)
|
|
array([10, 1])
|
|
|
|
>>> b = np.arange(5, dtype=float)
|
|
>>> b[2] = np.NaN
|
|
>>> np.amin(b)
|
|
nan
|
|
>>> np.amin(b, where=~np.isnan(b), initial=10)
|
|
0.0
|
|
>>> np.nanmin(b)
|
|
0.0
|
|
|
|
>>> np.min([[-50], [10]], axis=-1, initial=0)
|
|
array([-50, 0])
|
|
|
|
Notice that the initial value is used as one of the elements for which the
|
|
minimum is determined, unlike for the default argument Python's max
|
|
function, which is only used for empty iterables.
|
|
|
|
Notice that this isn't the same as Python's ``default`` argument.
|
|
|
|
>>> np.min([6], initial=5)
|
|
5
|
|
>>> min([6], default=5)
|
|
6
|
|
"""
|
|
return _wrapreduction(a, np.minimum, 'min', axis, None, out,
|
|
keepdims=keepdims, initial=initial, where=where)
|
|
|
|
|
|
def _alen_dispathcer(a):
|
|
return (a,)
|
|
|
|
|
|
@array_function_dispatch(_alen_dispathcer)
|
|
def alen(a):
|
|
"""
|
|
Return the length of the first dimension of the input array.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input array.
|
|
|
|
Returns
|
|
-------
|
|
alen : int
|
|
Length of the first dimension of `a`.
|
|
|
|
See Also
|
|
--------
|
|
shape, size
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.zeros((7,4,5))
|
|
>>> a.shape[0]
|
|
7
|
|
>>> np.alen(a)
|
|
7
|
|
|
|
"""
|
|
try:
|
|
return len(a)
|
|
except TypeError:
|
|
return len(array(a, ndmin=1))
|
|
|
|
|
|
def _prod_dispatcher(a, axis=None, dtype=None, out=None, keepdims=None,
|
|
initial=None, where=None):
|
|
return (a, out)
|
|
|
|
|
|
@array_function_dispatch(_prod_dispatcher)
|
|
def prod(a, axis=None, dtype=None, out=None, keepdims=np._NoValue,
|
|
initial=np._NoValue, where=np._NoValue):
|
|
"""
|
|
Return the product of array elements over a given axis.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input data.
|
|
axis : None or int or tuple of ints, optional
|
|
Axis or axes along which a product is performed. The default,
|
|
axis=None, will calculate the product of all the elements in the
|
|
input array. If axis is negative it counts from the last to the
|
|
first axis.
|
|
|
|
.. versionadded:: 1.7.0
|
|
|
|
If axis is a tuple of ints, a product is performed on all of the
|
|
axes specified in the tuple instead of a single axis or all the
|
|
axes as before.
|
|
dtype : dtype, optional
|
|
The type of the returned array, as well as of the accumulator in
|
|
which the elements are multiplied. The dtype of `a` is used by
|
|
default unless `a` has an integer dtype of less precision than the
|
|
default platform integer. In that case, if `a` is signed then the
|
|
platform integer is used while if `a` is unsigned then an unsigned
|
|
integer of the same precision as the platform integer is used.
|
|
out : ndarray, optional
|
|
Alternative output array in which to place the result. It must have
|
|
the same shape as the expected output, but the type of the output
|
|
values will be cast if necessary.
|
|
keepdims : bool, optional
|
|
If this is set to True, the axes which are reduced are left in the
|
|
result as dimensions with size one. With this option, the result
|
|
will broadcast correctly against the input array.
|
|
|
|
If the default value is passed, then `keepdims` will not be
|
|
passed through to the `prod` method of sub-classes of
|
|
`ndarray`, however any non-default value will be. If the
|
|
sub-class' method does not implement `keepdims` any
|
|
exceptions will be raised.
|
|
initial : scalar, optional
|
|
The starting value for this product. See `~numpy.ufunc.reduce` for details.
|
|
|
|
.. versionadded:: 1.15.0
|
|
|
|
where : array_like of bool, optional
|
|
Elements to include in the product. See `~numpy.ufunc.reduce` for details.
|
|
|
|
.. versionadded:: 1.17.0
|
|
|
|
Returns
|
|
-------
|
|
product_along_axis : ndarray, see `dtype` parameter above.
|
|
An array shaped as `a` but with the specified axis removed.
|
|
Returns a reference to `out` if specified.
|
|
|
|
See Also
|
|
--------
|
|
ndarray.prod : equivalent method
|
|
numpy.doc.ufuncs : Section "Output arguments"
|
|
|
|
Notes
|
|
-----
|
|
Arithmetic is modular when using integer types, and no error is
|
|
raised on overflow. That means that, on a 32-bit platform:
|
|
|
|
>>> x = np.array([536870910, 536870910, 536870910, 536870910])
|
|
>>> np.prod(x)
|
|
16 # may vary
|
|
|
|
The product of an empty array is the neutral element 1:
|
|
|
|
>>> np.prod([])
|
|
1.0
|
|
|
|
Examples
|
|
--------
|
|
By default, calculate the product of all elements:
|
|
|
|
>>> np.prod([1.,2.])
|
|
2.0
|
|
|
|
Even when the input array is two-dimensional:
|
|
|
|
>>> np.prod([[1.,2.],[3.,4.]])
|
|
24.0
|
|
|
|
But we can also specify the axis over which to multiply:
|
|
|
|
>>> np.prod([[1.,2.],[3.,4.]], axis=1)
|
|
array([ 2., 12.])
|
|
|
|
Or select specific elements to include:
|
|
|
|
>>> np.prod([1., np.nan, 3.], where=[True, False, True])
|
|
3.0
|
|
|
|
If the type of `x` is unsigned, then the output type is
|
|
the unsigned platform integer:
|
|
|
|
>>> x = np.array([1, 2, 3], dtype=np.uint8)
|
|
>>> np.prod(x).dtype == np.uint
|
|
True
|
|
|
|
If `x` is of a signed integer type, then the output type
|
|
is the default platform integer:
|
|
|
|
>>> x = np.array([1, 2, 3], dtype=np.int8)
|
|
>>> np.prod(x).dtype == int
|
|
True
|
|
|
|
You can also start the product with a value other than one:
|
|
|
|
>>> np.prod([1, 2], initial=5)
|
|
10
|
|
"""
|
|
return _wrapreduction(a, np.multiply, 'prod', axis, dtype, out,
|
|
keepdims=keepdims, initial=initial, where=where)
|
|
|
|
|
|
def _cumprod_dispatcher(a, axis=None, dtype=None, out=None):
|
|
return (a, out)
|
|
|
|
|
|
@array_function_dispatch(_cumprod_dispatcher)
|
|
def cumprod(a, axis=None, dtype=None, out=None):
|
|
"""
|
|
Return the cumulative product of elements along a given axis.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input array.
|
|
axis : int, optional
|
|
Axis along which the cumulative product is computed. By default
|
|
the input is flattened.
|
|
dtype : dtype, optional
|
|
Type of the returned array, as well as of the accumulator in which
|
|
the elements are multiplied. If *dtype* is not specified, it
|
|
defaults to the dtype of `a`, unless `a` has an integer dtype with
|
|
a precision less than that of the default platform integer. In
|
|
that case, the default platform integer is used instead.
|
|
out : ndarray, optional
|
|
Alternative output array in which to place the result. It must
|
|
have the same shape and buffer length as the expected output
|
|
but the type of the resulting values will be cast if necessary.
|
|
|
|
Returns
|
|
-------
|
|
cumprod : ndarray
|
|
A new array holding the result is returned unless `out` is
|
|
specified, in which case a reference to out is returned.
|
|
|
|
See Also
|
|
--------
|
|
numpy.doc.ufuncs : Section "Output arguments"
|
|
|
|
Notes
|
|
-----
|
|
Arithmetic is modular when using integer types, and no error is
|
|
raised on overflow.
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.array([1,2,3])
|
|
>>> np.cumprod(a) # intermediate results 1, 1*2
|
|
... # total product 1*2*3 = 6
|
|
array([1, 2, 6])
|
|
>>> a = np.array([[1, 2, 3], [4, 5, 6]])
|
|
>>> np.cumprod(a, dtype=float) # specify type of output
|
|
array([ 1., 2., 6., 24., 120., 720.])
|
|
|
|
The cumulative product for each column (i.e., over the rows) of `a`:
|
|
|
|
>>> np.cumprod(a, axis=0)
|
|
array([[ 1, 2, 3],
|
|
[ 4, 10, 18]])
|
|
|
|
The cumulative product for each row (i.e. over the columns) of `a`:
|
|
|
|
>>> np.cumprod(a,axis=1)
|
|
array([[ 1, 2, 6],
|
|
[ 4, 20, 120]])
|
|
|
|
"""
|
|
return _wrapfunc(a, 'cumprod', axis=axis, dtype=dtype, out=out)
|
|
|
|
|
|
def _ndim_dispatcher(a):
|
|
return (a,)
|
|
|
|
|
|
@array_function_dispatch(_ndim_dispatcher)
|
|
def ndim(a):
|
|
"""
|
|
Return the number of dimensions of an array.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input array. If it is not already an ndarray, a conversion is
|
|
attempted.
|
|
|
|
Returns
|
|
-------
|
|
number_of_dimensions : int
|
|
The number of dimensions in `a`. Scalars are zero-dimensional.
|
|
|
|
See Also
|
|
--------
|
|
ndarray.ndim : equivalent method
|
|
shape : dimensions of array
|
|
ndarray.shape : dimensions of array
|
|
|
|
Examples
|
|
--------
|
|
>>> np.ndim([[1,2,3],[4,5,6]])
|
|
2
|
|
>>> np.ndim(np.array([[1,2,3],[4,5,6]]))
|
|
2
|
|
>>> np.ndim(1)
|
|
0
|
|
|
|
"""
|
|
try:
|
|
return a.ndim
|
|
except AttributeError:
|
|
return asarray(a).ndim
|
|
|
|
|
|
def _size_dispatcher(a, axis=None):
|
|
return (a,)
|
|
|
|
|
|
@array_function_dispatch(_size_dispatcher)
|
|
def size(a, axis=None):
|
|
"""
|
|
Return the number of elements along a given axis.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input data.
|
|
axis : int, optional
|
|
Axis along which the elements are counted. By default, give
|
|
the total number of elements.
|
|
|
|
Returns
|
|
-------
|
|
element_count : int
|
|
Number of elements along the specified axis.
|
|
|
|
See Also
|
|
--------
|
|
shape : dimensions of array
|
|
ndarray.shape : dimensions of array
|
|
ndarray.size : number of elements in array
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.array([[1,2,3],[4,5,6]])
|
|
>>> np.size(a)
|
|
6
|
|
>>> np.size(a,1)
|
|
3
|
|
>>> np.size(a,0)
|
|
2
|
|
|
|
"""
|
|
if axis is None:
|
|
try:
|
|
return a.size
|
|
except AttributeError:
|
|
return asarray(a).size
|
|
else:
|
|
try:
|
|
return a.shape[axis]
|
|
except AttributeError:
|
|
return asarray(a).shape[axis]
|
|
|
|
|
|
def _around_dispatcher(a, decimals=None, out=None):
|
|
return (a, out)
|
|
|
|
|
|
@array_function_dispatch(_around_dispatcher)
|
|
def around(a, decimals=0, out=None):
|
|
"""
|
|
Evenly round to the given number of decimals.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Input data.
|
|
decimals : int, optional
|
|
Number of decimal places to round to (default: 0). If
|
|
decimals is negative, it specifies the number of positions to
|
|
the left of the decimal point.
|
|
out : ndarray, optional
|
|
Alternative output array in which to place the result. It must have
|
|
the same shape as the expected output, but the type of the output
|
|
values will be cast if necessary. See `doc.ufuncs` (Section
|
|
"Output arguments") for details.
|
|
|
|
Returns
|
|
-------
|
|
rounded_array : ndarray
|
|
An array of the same type as `a`, containing the rounded values.
|
|
Unless `out` was specified, a new array is created. A reference to
|
|
the result is returned.
|
|
|
|
The real and imaginary parts of complex numbers are rounded
|
|
separately. The result of rounding a float is a float.
|
|
|
|
See Also
|
|
--------
|
|
ndarray.round : equivalent method
|
|
|
|
ceil, fix, floor, rint, trunc
|
|
|
|
|
|
Notes
|
|
-----
|
|
For values exactly halfway between rounded decimal values, NumPy
|
|
rounds to the nearest even value. Thus 1.5 and 2.5 round to 2.0,
|
|
-0.5 and 0.5 round to 0.0, etc. Results may also be surprising due
|
|
to the inexact representation of decimal fractions in the IEEE
|
|
floating point standard [1]_ and errors introduced when scaling
|
|
by powers of ten.
|
|
|
|
References
|
|
----------
|
|
.. [1] "Lecture Notes on the Status of IEEE 754", William Kahan,
|
|
https://people.eecs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF
|
|
.. [2] "How Futile are Mindless Assessments of
|
|
Roundoff in Floating-Point Computation?", William Kahan,
|
|
https://people.eecs.berkeley.edu/~wkahan/Mindless.pdf
|
|
|
|
Examples
|
|
--------
|
|
>>> np.around([0.37, 1.64])
|
|
array([0., 2.])
|
|
>>> np.around([0.37, 1.64], decimals=1)
|
|
array([0.4, 1.6])
|
|
>>> np.around([.5, 1.5, 2.5, 3.5, 4.5]) # rounds to nearest even value
|
|
array([0., 2., 2., 4., 4.])
|
|
>>> np.around([1,2,3,11], decimals=1) # ndarray of ints is returned
|
|
array([ 1, 2, 3, 11])
|
|
>>> np.around([1,2,3,11], decimals=-1)
|
|
array([ 0, 0, 0, 10])
|
|
|
|
"""
|
|
return _wrapfunc(a, 'round', decimals=decimals, out=out)
|
|
|
|
|
|
def _mean_dispatcher(a, axis=None, dtype=None, out=None, keepdims=None):
|
|
return (a, out)
|
|
|
|
|
|
@array_function_dispatch(_mean_dispatcher)
|
|
def mean(a, axis=None, dtype=None, out=None, keepdims=np._NoValue):
|
|
"""
|
|
Compute the arithmetic mean along the specified axis.
|
|
|
|
Returns the average of the array elements. The average is taken over
|
|
the flattened array by default, otherwise over the specified axis.
|
|
`float64` intermediate and return values are used for integer inputs.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Array containing numbers whose mean is desired. If `a` is not an
|
|
array, a conversion is attempted.
|
|
axis : None or int or tuple of ints, optional
|
|
Axis or axes along which the means are computed. The default is to
|
|
compute the mean of the flattened array.
|
|
|
|
.. versionadded:: 1.7.0
|
|
|
|
If this is a tuple of ints, a mean is performed over multiple axes,
|
|
instead of a single axis or all the axes as before.
|
|
dtype : data-type, optional
|
|
Type to use in computing the mean. For integer inputs, the default
|
|
is `float64`; for floating point inputs, it is the same as the
|
|
input dtype.
|
|
out : ndarray, optional
|
|
Alternate output array in which to place the result. The default
|
|
is ``None``; if provided, it must have the same shape as the
|
|
expected output, but the type will be cast if necessary.
|
|
See `doc.ufuncs` for details.
|
|
|
|
keepdims : bool, optional
|
|
If this is set to True, the axes which are reduced are left
|
|
in the result as dimensions with size one. With this option,
|
|
the result will broadcast correctly against the input array.
|
|
|
|
If the default value is passed, then `keepdims` will not be
|
|
passed through to the `mean` method of sub-classes of
|
|
`ndarray`, however any non-default value will be. If the
|
|
sub-class' method does not implement `keepdims` any
|
|
exceptions will be raised.
|
|
|
|
Returns
|
|
-------
|
|
m : ndarray, see dtype parameter above
|
|
If `out=None`, returns a new array containing the mean values,
|
|
otherwise a reference to the output array is returned.
|
|
|
|
See Also
|
|
--------
|
|
average : Weighted average
|
|
std, var, nanmean, nanstd, nanvar
|
|
|
|
Notes
|
|
-----
|
|
The arithmetic mean is the sum of the elements along the axis divided
|
|
by the number of elements.
|
|
|
|
Note that for floating-point input, the mean is computed using the
|
|
same precision the input has. Depending on the input data, this can
|
|
cause the results to be inaccurate, especially for `float32` (see
|
|
example below). Specifying a higher-precision accumulator using the
|
|
`dtype` keyword can alleviate this issue.
|
|
|
|
By default, `float16` results are computed using `float32` intermediates
|
|
for extra precision.
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.array([[1, 2], [3, 4]])
|
|
>>> np.mean(a)
|
|
2.5
|
|
>>> np.mean(a, axis=0)
|
|
array([2., 3.])
|
|
>>> np.mean(a, axis=1)
|
|
array([1.5, 3.5])
|
|
|
|
In single precision, `mean` can be inaccurate:
|
|
|
|
>>> a = np.zeros((2, 512*512), dtype=np.float32)
|
|
>>> a[0, :] = 1.0
|
|
>>> a[1, :] = 0.1
|
|
>>> np.mean(a)
|
|
0.54999924
|
|
|
|
Computing the mean in float64 is more accurate:
|
|
|
|
>>> np.mean(a, dtype=np.float64)
|
|
0.55000000074505806 # may vary
|
|
|
|
"""
|
|
kwargs = {}
|
|
if keepdims is not np._NoValue:
|
|
kwargs['keepdims'] = keepdims
|
|
if type(a) is not mu.ndarray:
|
|
try:
|
|
mean = a.mean
|
|
except AttributeError:
|
|
pass
|
|
else:
|
|
return mean(axis=axis, dtype=dtype, out=out, **kwargs)
|
|
|
|
return _methods._mean(a, axis=axis, dtype=dtype,
|
|
out=out, **kwargs)
|
|
|
|
|
|
def _std_dispatcher(
|
|
a, axis=None, dtype=None, out=None, ddof=None, keepdims=None):
|
|
return (a, out)
|
|
|
|
|
|
@array_function_dispatch(_std_dispatcher)
|
|
def std(a, axis=None, dtype=None, out=None, ddof=0, keepdims=np._NoValue):
|
|
"""
|
|
Compute the standard deviation along the specified axis.
|
|
|
|
Returns the standard deviation, a measure of the spread of a distribution,
|
|
of the array elements. The standard deviation is computed for the
|
|
flattened array by default, otherwise over the specified axis.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Calculate the standard deviation of these values.
|
|
axis : None or int or tuple of ints, optional
|
|
Axis or axes along which the standard deviation is computed. The
|
|
default is to compute the standard deviation of the flattened array.
|
|
|
|
.. versionadded:: 1.7.0
|
|
|
|
If this is a tuple of ints, a standard deviation is performed over
|
|
multiple axes, instead of a single axis or all the axes as before.
|
|
dtype : dtype, optional
|
|
Type to use in computing the standard deviation. For arrays of
|
|
integer type the default is float64, for arrays of float types it is
|
|
the same as the array type.
|
|
out : ndarray, optional
|
|
Alternative output array in which to place the result. It must have
|
|
the same shape as the expected output but the type (of the calculated
|
|
values) will be cast if necessary.
|
|
ddof : int, optional
|
|
Means Delta Degrees of Freedom. The divisor used in calculations
|
|
is ``N - ddof``, where ``N`` represents the number of elements.
|
|
By default `ddof` is zero.
|
|
keepdims : bool, optional
|
|
If this is set to True, the axes which are reduced are left
|
|
in the result as dimensions with size one. With this option,
|
|
the result will broadcast correctly against the input array.
|
|
|
|
If the default value is passed, then `keepdims` will not be
|
|
passed through to the `std` method of sub-classes of
|
|
`ndarray`, however any non-default value will be. If the
|
|
sub-class' method does not implement `keepdims` any
|
|
exceptions will be raised.
|
|
|
|
Returns
|
|
-------
|
|
standard_deviation : ndarray, see dtype parameter above.
|
|
If `out` is None, return a new array containing the standard deviation,
|
|
otherwise return a reference to the output array.
|
|
|
|
See Also
|
|
--------
|
|
var, mean, nanmean, nanstd, nanvar
|
|
numpy.doc.ufuncs : Section "Output arguments"
|
|
|
|
Notes
|
|
-----
|
|
The standard deviation is the square root of the average of the squared
|
|
deviations from the mean, i.e., ``std = sqrt(mean(abs(x - x.mean())**2))``.
|
|
|
|
The average squared deviation is normally calculated as
|
|
``x.sum() / N``, where ``N = len(x)``. If, however, `ddof` is specified,
|
|
the divisor ``N - ddof`` is used instead. In standard statistical
|
|
practice, ``ddof=1`` provides an unbiased estimator of the variance
|
|
of the infinite population. ``ddof=0`` provides a maximum likelihood
|
|
estimate of the variance for normally distributed variables. The
|
|
standard deviation computed in this function is the square root of
|
|
the estimated variance, so even with ``ddof=1``, it will not be an
|
|
unbiased estimate of the standard deviation per se.
|
|
|
|
Note that, for complex numbers, `std` takes the absolute
|
|
value before squaring, so that the result is always real and nonnegative.
|
|
|
|
For floating-point input, the *std* is computed using the same
|
|
precision the input has. Depending on the input data, this can cause
|
|
the results to be inaccurate, especially for float32 (see example below).
|
|
Specifying a higher-accuracy accumulator using the `dtype` keyword can
|
|
alleviate this issue.
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.array([[1, 2], [3, 4]])
|
|
>>> np.std(a)
|
|
1.1180339887498949 # may vary
|
|
>>> np.std(a, axis=0)
|
|
array([1., 1.])
|
|
>>> np.std(a, axis=1)
|
|
array([0.5, 0.5])
|
|
|
|
In single precision, std() can be inaccurate:
|
|
|
|
>>> a = np.zeros((2, 512*512), dtype=np.float32)
|
|
>>> a[0, :] = 1.0
|
|
>>> a[1, :] = 0.1
|
|
>>> np.std(a)
|
|
0.45000005
|
|
|
|
Computing the standard deviation in float64 is more accurate:
|
|
|
|
>>> np.std(a, dtype=np.float64)
|
|
0.44999999925494177 # may vary
|
|
|
|
"""
|
|
kwargs = {}
|
|
if keepdims is not np._NoValue:
|
|
kwargs['keepdims'] = keepdims
|
|
|
|
if type(a) is not mu.ndarray:
|
|
try:
|
|
std = a.std
|
|
except AttributeError:
|
|
pass
|
|
else:
|
|
return std(axis=axis, dtype=dtype, out=out, ddof=ddof, **kwargs)
|
|
|
|
return _methods._std(a, axis=axis, dtype=dtype, out=out, ddof=ddof,
|
|
**kwargs)
|
|
|
|
|
|
def _var_dispatcher(
|
|
a, axis=None, dtype=None, out=None, ddof=None, keepdims=None):
|
|
return (a, out)
|
|
|
|
|
|
@array_function_dispatch(_var_dispatcher)
|
|
def var(a, axis=None, dtype=None, out=None, ddof=0, keepdims=np._NoValue):
|
|
"""
|
|
Compute the variance along the specified axis.
|
|
|
|
Returns the variance of the array elements, a measure of the spread of a
|
|
distribution. The variance is computed for the flattened array by
|
|
default, otherwise over the specified axis.
|
|
|
|
Parameters
|
|
----------
|
|
a : array_like
|
|
Array containing numbers whose variance is desired. If `a` is not an
|
|
array, a conversion is attempted.
|
|
axis : None or int or tuple of ints, optional
|
|
Axis or axes along which the variance is computed. The default is to
|
|
compute the variance of the flattened array.
|
|
|
|
.. versionadded:: 1.7.0
|
|
|
|
If this is a tuple of ints, a variance is performed over multiple axes,
|
|
instead of a single axis or all the axes as before.
|
|
dtype : data-type, optional
|
|
Type to use in computing the variance. For arrays of integer type
|
|
the default is `float32`; for arrays of float types it is the same as
|
|
the array type.
|
|
out : ndarray, optional
|
|
Alternate output array in which to place the result. It must have
|
|
the same shape as the expected output, but the type is cast if
|
|
necessary.
|
|
ddof : int, optional
|
|
"Delta Degrees of Freedom": the divisor used in the calculation is
|
|
``N - ddof``, where ``N`` represents the number of elements. By
|
|
default `ddof` is zero.
|
|
keepdims : bool, optional
|
|
If this is set to True, the axes which are reduced are left
|
|
in the result as dimensions with size one. With this option,
|
|
the result will broadcast correctly against the input array.
|
|
|
|
If the default value is passed, then `keepdims` will not be
|
|
passed through to the `var` method of sub-classes of
|
|
`ndarray`, however any non-default value will be. If the
|
|
sub-class' method does not implement `keepdims` any
|
|
exceptions will be raised.
|
|
|
|
Returns
|
|
-------
|
|
variance : ndarray, see dtype parameter above
|
|
If ``out=None``, returns a new array containing the variance;
|
|
otherwise, a reference to the output array is returned.
|
|
|
|
See Also
|
|
--------
|
|
std, mean, nanmean, nanstd, nanvar
|
|
numpy.doc.ufuncs : Section "Output arguments"
|
|
|
|
Notes
|
|
-----
|
|
The variance is the average of the squared deviations from the mean,
|
|
i.e., ``var = mean(abs(x - x.mean())**2)``.
|
|
|
|
The mean is normally calculated as ``x.sum() / N``, where ``N = len(x)``.
|
|
If, however, `ddof` is specified, the divisor ``N - ddof`` is used
|
|
instead. In standard statistical practice, ``ddof=1`` provides an
|
|
unbiased estimator of the variance of a hypothetical infinite population.
|
|
``ddof=0`` provides a maximum likelihood estimate of the variance for
|
|
normally distributed variables.
|
|
|
|
Note that for complex numbers, the absolute value is taken before
|
|
squaring, so that the result is always real and nonnegative.
|
|
|
|
For floating-point input, the variance is computed using the same
|
|
precision the input has. Depending on the input data, this can cause
|
|
the results to be inaccurate, especially for `float32` (see example
|
|
below). Specifying a higher-accuracy accumulator using the ``dtype``
|
|
keyword can alleviate this issue.
|
|
|
|
Examples
|
|
--------
|
|
>>> a = np.array([[1, 2], [3, 4]])
|
|
>>> np.var(a)
|
|
1.25
|
|
>>> np.var(a, axis=0)
|
|
array([1., 1.])
|
|
>>> np.var(a, axis=1)
|
|
array([0.25, 0.25])
|
|
|
|
In single precision, var() can be inaccurate:
|
|
|
|
>>> a = np.zeros((2, 512*512), dtype=np.float32)
|
|
>>> a[0, :] = 1.0
|
|
>>> a[1, :] = 0.1
|
|
>>> np.var(a)
|
|
0.20250003
|
|
|
|
Computing the variance in float64 is more accurate:
|
|
|
|
>>> np.var(a, dtype=np.float64)
|
|
0.20249999932944759 # may vary
|
|
>>> ((1-0.55)**2 + (0.1-0.55)**2)/2
|
|
0.2025
|
|
|
|
"""
|
|
kwargs = {}
|
|
if keepdims is not np._NoValue:
|
|
kwargs['keepdims'] = keepdims
|
|
|
|
if type(a) is not mu.ndarray:
|
|
try:
|
|
var = a.var
|
|
|
|
except AttributeError:
|
|
pass
|
|
else:
|
|
return var(axis=axis, dtype=dtype, out=out, ddof=ddof, **kwargs)
|
|
|
|
return _methods._var(a, axis=axis, dtype=dtype, out=out, ddof=ddof,
|
|
**kwargs)
|
|
|
|
|
|
# Aliases of other functions. These have their own definitions only so that
|
|
# they can have unique docstrings.
|
|
|
|
@array_function_dispatch(_around_dispatcher)
|
|
def round_(a, decimals=0, out=None):
|
|
"""
|
|
Round an array to the given number of decimals.
|
|
|
|
See Also
|
|
--------
|
|
around : equivalent function; see for details.
|
|
"""
|
|
return around(a, decimals=decimals, out=out)
|
|
|
|
|
|
@array_function_dispatch(_prod_dispatcher, verify=False)
|
|
def product(*args, **kwargs):
|
|
"""
|
|
Return the product of array elements over a given axis.
|
|
|
|
See Also
|
|
--------
|
|
prod : equivalent function; see for details.
|
|
"""
|
|
return prod(*args, **kwargs)
|
|
|
|
|
|
@array_function_dispatch(_cumprod_dispatcher, verify=False)
|
|
def cumproduct(*args, **kwargs):
|
|
"""
|
|
Return the cumulative product over the given axis.
|
|
|
|
See Also
|
|
--------
|
|
cumprod : equivalent function; see for details.
|
|
"""
|
|
return cumprod(*args, **kwargs)
|
|
|
|
|
|
@array_function_dispatch(_any_dispatcher, verify=False)
|
|
def sometrue(*args, **kwargs):
|
|
"""
|
|
Check whether some values are true.
|
|
|
|
Refer to `any` for full documentation.
|
|
|
|
See Also
|
|
--------
|
|
any : equivalent function; see for details.
|
|
"""
|
|
return any(*args, **kwargs)
|
|
|
|
|
|
@array_function_dispatch(_all_dispatcher, verify=False)
|
|
def alltrue(*args, **kwargs):
|
|
"""
|
|
Check if all elements of input array are true.
|
|
|
|
See Also
|
|
--------
|
|
numpy.all : Equivalent function; see for details.
|
|
"""
|
|
return all(*args, **kwargs)
|
|
|
|
|
|
@array_function_dispatch(_ndim_dispatcher)
|
|
def rank(a):
|
|
"""
|
|
Return the number of dimensions of an array.
|
|
|
|
.. note::
|
|
This function is deprecated in NumPy 1.9 to avoid confusion with
|
|
`numpy.linalg.matrix_rank`. The ``ndim`` attribute or function
|
|
should be used instead.
|
|
|
|
See Also
|
|
--------
|
|
ndim : equivalent non-deprecated function
|
|
|
|
Notes
|
|
-----
|
|
In the old Numeric package, `rank` was the term used for the number of
|
|
dimensions, but in NumPy `ndim` is used instead.
|
|
"""
|
|
# 2014-04-12, 1.9
|
|
warnings.warn(
|
|
"`rank` is deprecated; use the `ndim` attribute or function instead. "
|
|
"To find the rank of a matrix see `numpy.linalg.matrix_rank`.",
|
|
VisibleDeprecationWarning, stacklevel=3)
|
|
return ndim(a)
|