|
|
"""Module containing non-deprecated functions borrowed from Numeric. |
|
|
|
|
|
""" |
|
|
from __future__ import division, absolute_import, print_function |
|
|
|
|
|
import types |
|
|
import warnings |
|
|
|
|
|
from .. import VisibleDeprecationWarning |
|
|
from . import multiarray as mu |
|
|
from . import umath as um |
|
|
from . import numerictypes as nt |
|
|
from .numeric import asarray, array, asanyarray, concatenate |
|
|
from . import _methods |
|
|
|
|
|
_dt_ = nt.sctype2char |
|
|
|
|
|
|
|
|
|
|
|
__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', |
|
|
] |
|
|
|
|
|
|
|
|
try: |
|
|
_gentype = types.GeneratorType |
|
|
except AttributeError: |
|
|
_gentype = type(None) |
|
|
|
|
|
|
|
|
_sum_ = sum |
|
|
|
|
|
|
|
|
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 take(a, indices, axis=None, out=None, mode='raise'): |
|
|
""" |
|
|
Take elements from an array along an axis. |
|
|
|
|
|
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. |
|
|
|
|
|
Parameters |
|
|
---------- |
|
|
a : array_like |
|
|
The source array. |
|
|
indices : array_like |
|
|
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 |
|
|
If provided, the result will be placed in this array. It should |
|
|
be of the appropriate shape and dtype. |
|
|
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 |
|
|
------- |
|
|
subarray : ndarray |
|
|
The returned array has the same type as `a`. |
|
|
|
|
|
See Also |
|
|
-------- |
|
|
compress : Take elements using a boolean mask |
|
|
ndarray.take : equivalent method |
|
|
|
|
|
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]]) |
|
|
""" |
|
|
try: |
|
|
take = a.take |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'take', indices, axis, out, mode) |
|
|
return take(indices, axis, out, mode) |
|
|
|
|
|
|
|
|
|
|
|
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 raise if the data is copied, |
|
|
you should assign the new shape to the shape attribute of the array:: |
|
|
|
|
|
>>> a = np.zeros((10, 2)) |
|
|
# A transpose make 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) |
|
|
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]]) |
|
|
""" |
|
|
try: |
|
|
reshape = a.reshape |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'reshape', newshape, order=order) |
|
|
return reshape(newshape, order=order) |
|
|
|
|
|
|
|
|
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. |
|
|
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]]]) |
|
|
|
|
|
""" |
|
|
try: |
|
|
choose = a.choose |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'choose', choices, out=out, mode=mode) |
|
|
return choose(choices, out=out, mode=mode) |
|
|
|
|
|
|
|
|
def repeat(a, repeats, axis=None): |
|
|
""" |
|
|
Repeat elements of an array. |
|
|
|
|
|
Parameters |
|
|
---------- |
|
|
a : array_like |
|
|
Input array. |
|
|
repeats : {int, 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 |
|
|
-------- |
|
|
>>> 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]]) |
|
|
|
|
|
""" |
|
|
try: |
|
|
repeat = a.repeat |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'repeat', repeats, axis) |
|
|
return repeat(repeats, axis) |
|
|
|
|
|
|
|
|
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. |
|
|
|
|
|
See Also |
|
|
-------- |
|
|
putmask, place |
|
|
|
|
|
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]) |
|
|
|
|
|
""" |
|
|
return a.put(ind, v, mode) |
|
|
|
|
|
|
|
|
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 |
|
|
If `a` is an ndarray, then a view of `a` is returned; otherwise |
|
|
a new array is created. |
|
|
|
|
|
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]]]) |
|
|
|
|
|
""" |
|
|
try: |
|
|
swapaxes = a.swapaxes |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'swapaxes', axis1, axis2) |
|
|
return swapaxes(axis1, axis2) |
|
|
|
|
|
|
|
|
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 |
|
|
-------- |
|
|
rollaxis |
|
|
|
|
|
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) |
|
|
|
|
|
""" |
|
|
try: |
|
|
transpose = a.transpose |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'transpose', axes) |
|
|
return transpose(axes) |
|
|
|
|
|
|
|
|
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 kth position is in the position it would be in |
|
|
a sorted array. All elements smaller than the kth 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 kth 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 all elements in the partitions is undefined. |
|
|
If provided with a sequence of kth it will partition all elements |
|
|
indexed by kth 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 : list, optional |
|
|
When `a` is a structured array, this argument specifies which fields |
|
|
to compare first, second, and so on. This list does not need to |
|
|
include all of the fields. |
|
|
|
|
|
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: |
|
|
a = asanyarray(a).flatten() |
|
|
axis = 0 |
|
|
else: |
|
|
a = asanyarray(a).copy(order="K") |
|
|
a.partition(kth, axis=axis, kind=kind, order=order) |
|
|
return a |
|
|
|
|
|
|
|
|
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 kth 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 kth 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 : list, optional |
|
|
When `a` is an array with fields defined, this argument specifies |
|
|
which fields to compare first, second, etc. Not all fields need be |
|
|
specified. |
|
|
|
|
|
Returns |
|
|
------- |
|
|
index_array : ndarray, int |
|
|
Array of indices that partition `a` along the specified axis. |
|
|
In other words, ``a[index_array]`` yields a sorted `a`. |
|
|
|
|
|
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]) |
|
|
|
|
|
""" |
|
|
return a.argpartition(kth, axis, kind=kind, order=order) |
|
|
|
|
|
|
|
|
def sort(a, axis=-1, kind='quicksort', 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'}, optional |
|
|
Sorting algorithm. Default is 'quicksort'. |
|
|
order : list, optional |
|
|
When `a` is a structured array, this argument specifies which fields |
|
|
to compare first, second, and so on. This list does not need to |
|
|
include all of the fields. |
|
|
|
|
|
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 three available algorithms have the following |
|
|
properties: |
|
|
|
|
|
=========== ======= ============= ============ ======= |
|
|
kind speed worst case work space stable |
|
|
=========== ======= ============= ============ ======= |
|
|
'quicksort' 1 O(n^2) 0 no |
|
|
'mergesort' 2 O(n*log(n)) ~n/2 yes |
|
|
'heapsort' 3 O(n*log(n)) 0 no |
|
|
=========== ======= ============= ============ ======= |
|
|
|
|
|
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. |
|
|
|
|
|
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: |
|
|
a = asanyarray(a).flatten() |
|
|
axis = 0 |
|
|
else: |
|
|
a = asanyarray(a).copy(order="K") |
|
|
a.sort(axis, kind, order) |
|
|
return a |
|
|
|
|
|
|
|
|
def argsort(a, axis=-1, kind='quicksort', 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'}, optional |
|
|
Sorting algorithm. |
|
|
order : list, optional |
|
|
When `a` is an array with fields defined, this argument specifies |
|
|
which fields to compare first, second, etc. Not all fields need be |
|
|
specified. |
|
|
|
|
|
Returns |
|
|
------- |
|
|
index_array : ndarray, int |
|
|
Array of indices that sort `a` along the specified axis. |
|
|
In other words, ``a[index_array]`` yields a sorted `a`. |
|
|
|
|
|
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]]) |
|
|
|
|
|
>>> np.argsort(x, axis=0) |
|
|
array([[0, 1], |
|
|
[1, 0]]) |
|
|
|
|
|
>>> np.argsort(x, axis=1) |
|
|
array([[0, 1], |
|
|
[0, 1]]) |
|
|
|
|
|
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]) |
|
|
|
|
|
""" |
|
|
try: |
|
|
argsort = a.argsort |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'argsort', axis, kind, order) |
|
|
return argsort(axis, kind, order) |
|
|
|
|
|
|
|
|
def argmax(a, axis=None): |
|
|
""" |
|
|
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. |
|
|
|
|
|
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) |
|
|
>>> a |
|
|
array([[0, 1, 2], |
|
|
[3, 4, 5]]) |
|
|
>>> np.argmax(a) |
|
|
5 |
|
|
>>> np.argmax(a, axis=0) |
|
|
array([1, 1, 1]) |
|
|
>>> np.argmax(a, axis=1) |
|
|
array([2, 2]) |
|
|
|
|
|
>>> 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 |
|
|
|
|
|
""" |
|
|
try: |
|
|
argmax = a.argmax |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'argmax', axis) |
|
|
return argmax(axis) |
|
|
|
|
|
|
|
|
def argmin(a, axis=None): |
|
|
""" |
|
|
Return the indices of the minimum values along an axis. |
|
|
|
|
|
See Also |
|
|
-------- |
|
|
argmax : Similar function. Please refer to `numpy.argmax` for detailed |
|
|
documentation. |
|
|
|
|
|
""" |
|
|
try: |
|
|
argmin = a.argmin |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'argmin', axis) |
|
|
return argmin(axis) |
|
|
|
|
|
|
|
|
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. |
|
|
|
|
|
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 |
|
|
.. versionadded:: 1.7.0 |
|
|
Optional array of integer indices that sort array a into ascending |
|
|
order. They are typically the result of argsort. |
|
|
|
|
|
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`. |
|
|
|
|
|
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]) |
|
|
|
|
|
""" |
|
|
try: |
|
|
searchsorted = a.searchsorted |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'searchsorted', v, side, sorter) |
|
|
return searchsorted(v, side, sorter) |
|
|
|
|
|
|
|
|
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. |
|
|
|
|
|
Examples |
|
|
-------- |
|
|
>>> a=np.array([[0,1],[2,3]]) |
|
|
>>> 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) |
|
|
if not Na: return mu.zeros(new_shape, a.dtype.char) |
|
|
total_size = um.multiply.reduce(new_shape) |
|
|
n_copies = int(total_size / Na) |
|
|
extra = total_size % Na |
|
|
|
|
|
if total_size == 0: |
|
|
return a[:0] |
|
|
|
|
|
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(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`. |
|
|
|
|
|
Examples |
|
|
-------- |
|
|
>>> x = np.array([[[0], [1], [2]]]) |
|
|
>>> x.shape |
|
|
(1, 3, 1) |
|
|
>>> np.squeeze(x).shape |
|
|
(3,) |
|
|
>>> np.squeeze(x, axis=(2,)).shape |
|
|
(1, 3) |
|
|
|
|
|
""" |
|
|
try: |
|
|
squeeze = a.squeeze |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'squeeze') |
|
|
try: |
|
|
|
|
|
return squeeze(axis=axis) |
|
|
except TypeError: |
|
|
|
|
|
return squeeze() |
|
|
|
|
|
|
|
|
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. |
|
|
|
|
|
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 NumPy 1.10, it will return a read/write view, Writing to the returned |
|
|
array will alter your original 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, a 1-D array containing the diagonal is returned. |
|
|
If the dimension of `a` is larger, then an array of diagonals is |
|
|
returned, "packed" from left-most dimension to right-most (e.g., |
|
|
if `a` is 3-D, then the diagonals are "packed" along rows). |
|
|
|
|
|
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]]) |
|
|
|
|
|
""" |
|
|
return asarray(a).diagonal(offset, axis1, axis2) |
|
|
|
|
|
|
|
|
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) |
|
|
|
|
|
""" |
|
|
return asarray(a).trace(offset, axis1, axis2, dtype, out) |
|
|
|
|
|
def ravel(a, order='C'): |
|
|
""" |
|
|
Return a flattened array. |
|
|
|
|
|
A 1-D array, containing the elements of the input, is returned. A copy is |
|
|
made only if needed. |
|
|
|
|
|
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 C-like order, with the last axis index changing |
|
|
fastest, back to the first axis index changing slowest. 'F' means to |
|
|
index the elements in 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 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 |
|
|
------- |
|
|
1d_array : ndarray |
|
|
Output of the same dtype as `a`, and of shape ``(a.size,)``. |
|
|
|
|
|
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. |
|
|
|
|
|
Notes |
|
|
----- |
|
|
In C-like (row-major) 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 Fortran-like, or column-major, index ordering. |
|
|
|
|
|
Examples |
|
|
-------- |
|
|
It is equivalent to ``reshape(-1, order=order)``. |
|
|
|
|
|
>>> x = np.array([[1, 2, 3], [4, 5, 6]]) |
|
|
>>> print np.ravel(x) |
|
|
[1 2 3 4 5 6] |
|
|
|
|
|
>>> print x.reshape(-1) |
|
|
[1 2 3 4 5 6] |
|
|
|
|
|
>>> print np.ravel(x, order='F') |
|
|
[1 4 2 5 3 6] |
|
|
|
|
|
When ``order`` is 'A', it will preserve the array's 'C' or 'F' ordering: |
|
|
|
|
|
>>> print np.ravel(x.T) |
|
|
[1 4 2 5 3 6] |
|
|
>>> print np.ravel(x.T, order='A') |
|
|
[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]) |
|
|
|
|
|
""" |
|
|
return asarray(a).ravel(order) |
|
|
|
|
|
|
|
|
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 |
|
|
corresponding non-zero values can be obtained with:: |
|
|
|
|
|
a[nonzero(a)] |
|
|
|
|
|
To group the indices by element, rather than dimension, use:: |
|
|
|
|
|
transpose(nonzero(a)) |
|
|
|
|
|
The result of this is always a 2-D array, with a row for |
|
|
each non-zero element. |
|
|
|
|
|
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. |
|
|
|
|
|
Examples |
|
|
-------- |
|
|
>>> x = np.eye(3) |
|
|
>>> x |
|
|
array([[ 1., 0., 0.], |
|
|
[ 0., 1., 0.], |
|
|
[ 0., 0., 1.]]) |
|
|
>>> np.nonzero(x) |
|
|
(array([0, 1, 2]), array([0, 1, 2])) |
|
|
|
|
|
>>> x[np.nonzero(x)] |
|
|
array([ 1., 1., 1.]) |
|
|
>>> np.transpose(np.nonzero(x)) |
|
|
array([[0, 0], |
|
|
[1, 1], |
|
|
[2, 2]]) |
|
|
|
|
|
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]], dtype=bool) |
|
|
>>> np.nonzero(a > 3) |
|
|
(array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2])) |
|
|
|
|
|
The ``nonzero`` method of the boolean array can also be called. |
|
|
|
|
|
>>> (a > 3).nonzero() |
|
|
(array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2])) |
|
|
|
|
|
""" |
|
|
try: |
|
|
nonzero = a.nonzero |
|
|
except AttributeError: |
|
|
res = _wrapit(a, 'nonzero') |
|
|
else: |
|
|
res = nonzero() |
|
|
return res |
|
|
|
|
|
|
|
|
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(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]) |
|
|
|
|
|
""" |
|
|
try: |
|
|
compress = a.compress |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'compress', condition, axis, out) |
|
|
return compress(condition, axis, out) |
|
|
|
|
|
|
|
|
def clip(a, a_min, a_max, out=None): |
|
|
""" |
|
|
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. |
|
|
|
|
|
Parameters |
|
|
---------- |
|
|
a : array_like |
|
|
Array containing elements to clip. |
|
|
a_min : scalar or array_like |
|
|
Minimum value. |
|
|
a_max : scalar or array_like |
|
|
Maximum value. If `a_min` or `a_max` are array_like, then they will |
|
|
be broadcasted to the shape of `a`. |
|
|
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. |
|
|
|
|
|
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]) |
|
|
|
|
|
""" |
|
|
try: |
|
|
clip = a.clip |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'clip', a_min, a_max, out) |
|
|
return clip(a_min, a_max, out) |
|
|
|
|
|
|
|
|
def sum(a, axis=None, dtype=None, out=None, keepdims=False): |
|
|
""" |
|
|
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`) is perform a sum 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 sum is performed on multiple |
|
|
axes, 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. By default, the dtype of `a` is used. |
|
|
An exception is when `a` has an integer type with less precision |
|
|
than the default platform integer. In that case, the default |
|
|
platform integer is used instead. |
|
|
out : ndarray, optional |
|
|
Array into which the output is placed. By default, a new array is |
|
|
created. If `out` is given, it must be of the appropriate shape |
|
|
(the shape of `a` with `axis` removed, i.e., |
|
|
``numpy.delete(a.shape, axis)``). Its type is preserved. 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 original `arr`. |
|
|
|
|
|
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. |
|
|
|
|
|
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. |
|
|
|
|
|
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]) |
|
|
|
|
|
If the accumulator is too small, overflow occurs: |
|
|
|
|
|
>>> np.ones(128, dtype=np.int8).sum(dtype=np.int8) |
|
|
-128 |
|
|
|
|
|
""" |
|
|
if isinstance(a, _gentype): |
|
|
res = _sum_(a) |
|
|
if out is not None: |
|
|
out[...] = res |
|
|
return out |
|
|
return res |
|
|
elif type(a) is not mu.ndarray: |
|
|
try: |
|
|
sum = a.sum |
|
|
except AttributeError: |
|
|
return _methods._sum(a, axis=axis, dtype=dtype, |
|
|
out=out, keepdims=keepdims) |
|
|
|
|
|
return sum(axis=axis, dtype=dtype, out=out) |
|
|
else: |
|
|
return _methods._sum(a, axis=axis, dtype=dtype, |
|
|
out=out, keepdims=keepdims) |
|
|
|
|
|
def product (a, axis=None, dtype=None, out=None, keepdims=False): |
|
|
""" |
|
|
Return the product of array elements over a given axis. |
|
|
|
|
|
See Also |
|
|
-------- |
|
|
prod : equivalent function; see for details. |
|
|
|
|
|
""" |
|
|
return um.multiply.reduce(a, axis=axis, dtype=dtype, out=out, keepdims=keepdims) |
|
|
|
|
|
|
|
|
def sometrue(a, axis=None, out=None, keepdims=False): |
|
|
""" |
|
|
Check whether some values are true. |
|
|
|
|
|
Refer to `any` for full documentation. |
|
|
|
|
|
See Also |
|
|
-------- |
|
|
any : equivalent function |
|
|
|
|
|
""" |
|
|
arr = asanyarray(a) |
|
|
|
|
|
try: |
|
|
return arr.any(axis=axis, out=out, keepdims=keepdims) |
|
|
except TypeError: |
|
|
return arr.any(axis=axis, out=out) |
|
|
|
|
|
def alltrue (a, axis=None, out=None, keepdims=False): |
|
|
""" |
|
|
Check if all elements of input array are true. |
|
|
|
|
|
See Also |
|
|
-------- |
|
|
numpy.all : Equivalent function; see for details. |
|
|
|
|
|
""" |
|
|
arr = asanyarray(a) |
|
|
|
|
|
try: |
|
|
return arr.all(axis=axis, out=out, keepdims=keepdims) |
|
|
except TypeError: |
|
|
return arr.all(axis=axis, out=out) |
|
|
|
|
|
def any(a, axis=None, out=None, keepdims=False): |
|
|
""" |
|
|
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 original `arr`. |
|
|
|
|
|
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], dtype=bool) |
|
|
|
|
|
>>> 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], dtype=bool), array([ True], dtype=bool)) |
|
|
>>> # 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) |
|
|
|
|
|
""" |
|
|
arr = asanyarray(a) |
|
|
|
|
|
try: |
|
|
return arr.any(axis=axis, out=out, keepdims=keepdims) |
|
|
except TypeError: |
|
|
return arr.any(axis=axis, out=out) |
|
|
|
|
|
def all(a, axis=None, out=None, keepdims=False): |
|
|
""" |
|
|
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 original `arr`. |
|
|
|
|
|
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], dtype=bool) |
|
|
|
|
|
>>> 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 # doctest: +SKIP |
|
|
(28293632, 28293632, array([ True], dtype=bool)) |
|
|
|
|
|
""" |
|
|
arr = asanyarray(a) |
|
|
|
|
|
try: |
|
|
return arr.all(axis=axis, out=out, keepdims=keepdims) |
|
|
except TypeError: |
|
|
return arr.all(axis=axis, out=out) |
|
|
|
|
|
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 order 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]]) |
|
|
|
|
|
""" |
|
|
try: |
|
|
cumsum = a.cumsum |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'cumsum', axis, dtype, out) |
|
|
return cumsum(axis, dtype, out) |
|
|
|
|
|
|
|
|
def cumproduct(a, axis=None, dtype=None, out=None): |
|
|
""" |
|
|
Return the cumulative product over the given axis. |
|
|
|
|
|
|
|
|
See Also |
|
|
-------- |
|
|
cumprod : equivalent function; see for details. |
|
|
|
|
|
""" |
|
|
try: |
|
|
cumprod = a.cumprod |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'cumprod', axis, dtype, out) |
|
|
return cumprod(axis, dtype, out) |
|
|
|
|
|
|
|
|
def ptp(a, axis=None, out=None): |
|
|
""" |
|
|
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 : int, optional |
|
|
Axis along which to find the peaks. By default, flatten the |
|
|
array. |
|
|
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. |
|
|
|
|
|
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]) |
|
|
|
|
|
""" |
|
|
try: |
|
|
ptp = a.ptp |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'ptp', axis, out) |
|
|
return ptp(axis, out) |
|
|
|
|
|
|
|
|
def amax(a, axis=None, out=None, keepdims=False): |
|
|
""" |
|
|
Return the maximum of an array or maximum along an axis. |
|
|
|
|
|
Parameters |
|
|
---------- |
|
|
a : array_like |
|
|
Input data. |
|
|
axis : int, optional |
|
|
Axis along which to operate. By default, flattened input is used. |
|
|
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 original `arr`. |
|
|
|
|
|
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]) |
|
|
|
|
|
>>> b = np.arange(5, dtype=np.float) |
|
|
>>> b[2] = np.NaN |
|
|
>>> np.amax(b) |
|
|
nan |
|
|
>>> np.nanmax(b) |
|
|
4.0 |
|
|
|
|
|
""" |
|
|
if type(a) is not mu.ndarray: |
|
|
try: |
|
|
amax = a.max |
|
|
except AttributeError: |
|
|
return _methods._amax(a, axis=axis, |
|
|
out=out, keepdims=keepdims) |
|
|
|
|
|
return amax(axis=axis, out=out) |
|
|
else: |
|
|
return _methods._amax(a, axis=axis, |
|
|
out=out, keepdims=keepdims) |
|
|
|
|
|
def amin(a, axis=None, out=None, keepdims=False): |
|
|
""" |
|
|
Return the minimum of an array or minimum along an axis. |
|
|
|
|
|
Parameters |
|
|
---------- |
|
|
a : array_like |
|
|
Input data. |
|
|
axis : int, optional |
|
|
Axis along which to operate. By default, flattened input is used. |
|
|
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 original `arr`. |
|
|
|
|
|
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]) |
|
|
|
|
|
>>> b = np.arange(5, dtype=np.float) |
|
|
>>> b[2] = np.NaN |
|
|
>>> np.amin(b) |
|
|
nan |
|
|
>>> np.nanmin(b) |
|
|
0.0 |
|
|
|
|
|
""" |
|
|
if type(a) is not mu.ndarray: |
|
|
try: |
|
|
amin = a.min |
|
|
except AttributeError: |
|
|
return _methods._amin(a, axis=axis, |
|
|
out=out, keepdims=keepdims) |
|
|
|
|
|
return amin(axis=axis, out=out) |
|
|
else: |
|
|
return _methods._amin(a, axis=axis, |
|
|
out=out, keepdims=keepdims) |
|
|
|
|
|
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(a, axis=None, dtype=None, out=None, keepdims=False): |
|
|
""" |
|
|
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`) is perform a product 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 product is performed on multiple |
|
|
axes, instead of a single axis or all the axes as before. |
|
|
dtype : data-type, optional |
|
|
The data-type of the returned array, as well as of the accumulator |
|
|
in which the elements are multiplied. By default, if `a` is of |
|
|
integer type, `dtype` is the default platform integer. (Note: if |
|
|
the type of `a` is unsigned, then so is `dtype`.) Otherwise, |
|
|
the dtype is the same as that of `a`. |
|
|
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 original `arr`. |
|
|
|
|
|
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) #random |
|
|
16 |
|
|
|
|
|
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.]) |
|
|
|
|
|
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 == np.int |
|
|
True |
|
|
|
|
|
""" |
|
|
if type(a) is not mu.ndarray: |
|
|
try: |
|
|
prod = a.prod |
|
|
except AttributeError: |
|
|
return _methods._prod(a, axis=axis, dtype=dtype, |
|
|
out=out, keepdims=keepdims) |
|
|
return prod(axis=axis, dtype=dtype, out=out) |
|
|
else: |
|
|
return _methods._prod(a, axis=axis, dtype=dtype, |
|
|
out=out, keepdims=keepdims) |
|
|
|
|
|
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]]) |
|
|
|
|
|
""" |
|
|
try: |
|
|
cumprod = a.cumprod |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'cumprod', axis, dtype, out) |
|
|
return cumprod(axis, dtype, out) |
|
|
|
|
|
|
|
|
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 rank(a): |
|
|
""" |
|
|
Return the number of dimensions of an array. |
|
|
|
|
|
If `a` is not already an array, a conversion is attempted. |
|
|
Scalars are zero dimensional. |
|
|
|
|
|
.. 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. |
|
|
|
|
|
Parameters |
|
|
---------- |
|
|
a : array_like |
|
|
Array whose number of dimensions is desired. If `a` is not an array, |
|
|
a conversion is attempted. |
|
|
|
|
|
Returns |
|
|
------- |
|
|
number_of_dimensions : int |
|
|
The number of dimensions in the array. |
|
|
|
|
|
See Also |
|
|
-------- |
|
|
ndim : equivalent function |
|
|
ndarray.ndim : equivalent property |
|
|
shape : dimensions of array |
|
|
ndarray.shape : dimensions of array |
|
|
|
|
|
Notes |
|
|
----- |
|
|
In the old Numeric package, `rank` was the term used for the number of |
|
|
dimensions, but in Numpy `ndim` is used instead. |
|
|
|
|
|
Examples |
|
|
-------- |
|
|
>>> np.rank([1,2,3]) |
|
|
1 |
|
|
>>> np.rank(np.array([[1,2,3],[4,5,6]])) |
|
|
2 |
|
|
>>> np.rank(1) |
|
|
0 |
|
|
|
|
|
""" |
|
|
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) |
|
|
try: |
|
|
return a.ndim |
|
|
except AttributeError: |
|
|
return asarray(a).ndim |
|
|
|
|
|
|
|
|
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(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, |
|
|
http://www.cs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF |
|
|
.. [2] "How Futile are Mindless Assessments of |
|
|
Roundoff in Floating-Point Computation?", William Kahan, |
|
|
http://www.cs.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]) |
|
|
|
|
|
""" |
|
|
try: |
|
|
round = a.round |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'round', decimals, out) |
|
|
return round(decimals, out) |
|
|
|
|
|
|
|
|
def round_(a, decimals=0, out=None): |
|
|
""" |
|
|
Round an array to the given number of decimals. |
|
|
|
|
|
Refer to `around` for full documentation. |
|
|
|
|
|
See Also |
|
|
-------- |
|
|
around : equivalent function |
|
|
|
|
|
""" |
|
|
try: |
|
|
round = a.round |
|
|
except AttributeError: |
|
|
return _wrapit(a, 'round', decimals, out) |
|
|
return round(decimals, out) |
|
|
|
|
|
|
|
|
def mean(a, axis=None, dtype=None, out=None, keepdims=False): |
|
|
""" |
|
|
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 : int, optional |
|
|
Axis along which the means are computed. The default is to compute |
|
|
the mean of the flattened array. |
|
|
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 original `arr`. |
|
|
|
|
|
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. |
|
|
|
|
|
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.546875 |
|
|
|
|
|
Computing the mean in float64 is more accurate: |
|
|
|
|
|
>>> np.mean(a, dtype=np.float64) |
|
|
0.55000000074505806 |
|
|
|
|
|
""" |
|
|
if type(a) is not mu.ndarray: |
|
|
try: |
|
|
mean = a.mean |
|
|
return mean(axis=axis, dtype=dtype, out=out) |
|
|
except AttributeError: |
|
|
pass |
|
|
|
|
|
return _methods._mean(a, axis=axis, dtype=dtype, |
|
|
out=out, keepdims=keepdims) |
|
|
|
|
|
def std(a, axis=None, dtype=None, out=None, ddof=0, keepdims=False): |
|
|
""" |
|
|
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 : int, optional |
|
|
Axis along which the standard deviation is computed. The default is |
|
|
to compute the standard deviation of the flattened array. |
|
|
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 original `arr`. |
|
|
|
|
|
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 |
|
|
>>> 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.45172946707416706 |
|
|
|
|
|
Computing the standard deviation in float64 is more accurate: |
|
|
|
|
|
>>> np.std(a, dtype=np.float64) |
|
|
0.44999999925552653 |
|
|
|
|
|
""" |
|
|
if type(a) is not mu.ndarray: |
|
|
try: |
|
|
std = a.std |
|
|
return std(axis=axis, dtype=dtype, out=out, ddof=ddof) |
|
|
except AttributeError: |
|
|
pass |
|
|
|
|
|
return _methods._std(a, axis=axis, dtype=dtype, out=out, ddof=ddof, |
|
|
keepdims=keepdims) |
|
|
|
|
|
def var(a, axis=None, dtype=None, out=None, ddof=0, |
|
|
keepdims=False): |
|
|
""" |
|
|
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 : int, optional |
|
|
Axis along which the variance is computed. The default is to compute |
|
|
the variance of the flattened array. |
|
|
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 original `arr`. |
|
|
|
|
|
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.20405951142311096 |
|
|
|
|
|
Computing the variance in float64 is more accurate: |
|
|
|
|
|
>>> np.var(a, dtype=np.float64) |
|
|
0.20249999932997387 |
|
|
>>> ((1-0.55)**2 + (0.1-0.55)**2)/2 |
|
|
0.20250000000000001 |
|
|
|
|
|
""" |
|
|
if type(a) is not mu.ndarray: |
|
|
try: |
|
|
var = a.var |
|
|
return var(axis=axis, dtype=dtype, out=out, ddof=ddof) |
|
|
except AttributeError: |
|
|
pass |
|
|
|
|
|
return _methods._var(a, axis=axis, dtype=dtype, out=out, ddof=ddof, |
|
|
keepdims=keepdims) |
|
|
|
