diff options
Diffstat (limited to 'numpy/core/fromnumeric.py')
| -rw-r--r-- | numpy/core/fromnumeric.py | 82 |
1 files changed, 52 insertions, 30 deletions
diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py index efb052bc2..820d6831f 100644 --- a/numpy/core/fromnumeric.py +++ b/numpy/core/fromnumeric.py @@ -10,8 +10,7 @@ from . import multiarray as mu from . import overrides from . import umath as um from . import numerictypes as nt -from ._asarray import asarray, array, asanyarray -from .multiarray import concatenate +from .multiarray import asarray, array, asanyarray, concatenate from . import _methods _dt_ = nt.sctype2char @@ -308,7 +307,7 @@ def _choose_dispatcher(a, choices, out=None, mode=None): @array_function_dispatch(_choose_dispatcher) def choose(a, choices, out=None, mode='raise'): """ - Construct an array from an index array and a set of arrays to choose from. + Construct an array from an index array and a list 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 @@ -319,34 +318,34 @@ def choose(a, choices, out=None, mode='raise'): But this omits some subtleties. Here is a fully general summary: - Given an "index" array (`a`) of integers and a sequence of `n` arrays + 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 + 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='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) + * 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. + * 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. + 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 @@ -355,12 +354,12 @@ def choose(a, choices, out=None, mode='raise'): out : array, optional If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype. Note that `out` is always - buffered if `mode='raise'`; use other modes for better performance. + buffered if ``mode='raise'``; use other modes for better performance. mode : {'raise' (default), 'wrap', 'clip'}, optional - Specifies how indices outside `[0, n-1]` will be treated: + Specifies how indices outside ``[0, n-1]`` will be treated: * 'raise' : an exception is raised - * 'wrap' : value becomes value mod `n` + * 'wrap' : value becomes value mod ``n`` * 'clip' : values < 0 are mapped to 0, values > n-1 are mapped to n-1 Returns @@ -606,6 +605,8 @@ def transpose(a, axes=None): For an array a with two axes, transpose(a) gives the matrix transpose. + Refer to `numpy.ndarray.transpose` for full documentation. + Parameters ---------- a : array_like @@ -625,6 +626,7 @@ def transpose(a, axes=None): See Also -------- + ndarray.transpose : Equivalent method moveaxis argsort @@ -1316,8 +1318,9 @@ def searchsorted(a, v, side='left', sorter=None): Returns ------- - indices : array of ints - Array of insertion points with the same shape as `v`. + indices : int or array of ints + Array of insertion points with the same shape as `v`, + or an integer if `v` is a scalar. See Also -------- @@ -1381,7 +1384,7 @@ def resize(a, new_shape): -------- np.reshape : Reshape an array without changing the total size. np.pad : Enlarge and pad an array. - np.repeat: Repeat elements of an array. + np.repeat : Repeat elements of an array. ndarray.resize : resize an array in-place. Notes @@ -2007,7 +2010,7 @@ def compress(condition, a, axis=None, out=None): -------- take, choose, diag, diagonal, select ndarray.compress : Equivalent method in ndarray - extract: Equivalent method when working on 1-D arrays + extract : Equivalent method when working on 1-D arrays :ref:`ufuncs-output-type` Examples @@ -2084,15 +2087,25 @@ def clip(a, a_min, a_max, out=None, **kwargs): -------- :ref:`ufuncs-output-type` + Notes + ----- + When `a_min` is greater than `a_max`, `clip` returns an + array in which all values are equal to `a_max`, + as shown in the second example. + 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, 1, 8) + array([1, 1, 2, 3, 4, 5, 6, 7, 8, 8]) + >>> np.clip(a, 8, 1) + array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1]) >>> np.clip(a, 3, 6, out=a) array([3, 3, 3, 3, 4, 5, 6, 6, 6, 6]) + >>> 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]) @@ -2475,20 +2488,21 @@ def cumsum(a, axis=None, dtype=None, out=None): result has the same size as `a`, and the same shape as `a` if `axis` is not None or `a` is a 1-d array. - See Also -------- sum : Sum array elements. - trapz : Integration of array values using the composite trapezoidal rule. - - diff : Calculate the n-th discrete difference along given axis. + diff : Calculate the n-th discrete difference along given axis. Notes ----- Arithmetic is modular when using integer types, and no error is raised on overflow. + ``cumsum(a)[-1]`` may not be equal to ``sum(a)`` for floating-point + values since ``sum`` may use a pairwise summation routine, reducing + the roundoff-error. See `sum` for more information. + Examples -------- >>> a = np.array([[1,2,3], [4,5,6]]) @@ -2507,6 +2521,14 @@ def cumsum(a, axis=None, dtype=None, out=None): array([[ 1, 3, 6], [ 4, 9, 15]]) + ``cumsum(b)[-1]`` may not be equal to ``sum(b)`` + + >>> b = np.array([1, 2e-9, 3e-9] * 1000000) + >>> b.cumsum()[-1] + 1000000.0050045159 + >>> b.sum() + 1000000.0050000029 + """ return _wrapfunc(a, 'cumsum', axis=axis, dtype=dtype, out=out) |