nlcpy.ufunc.reduce

ufunc.reduce(self, array, axis=0, dtype=None, out=None, keepdims=False, initial=nlcpy._NoValue, where=True)

Reduces one of the dimension of the input array, by applying ufunc along one axis.

Let a.shape = (N_{0}, ..., N_{i}, ..., N_{M-1}). Then ufunc.reduce(a, axis = i)[k_{0}, ..., k_{i-1}, k_{i+1}, ..., k_{M-1}] = the result of iterating j over range(N_{i}) , cumulatively applying ufunc to each a[k_{0}, ..., k_{i-1}, j, k_{i+1}, ..., k_{M-1}].

For example, nlcpy.add.reduce() is equivalent to nlcpy.sum().

Parameters
arrayarray_like

The array to act on.

axisNone or int or tuple of ints, optional

Axis or axes along which a reduction is performed. The default (axis = 0) is perform a reduction over the first dimension of the input array. axis may be negative, in which case it counts from the last to the first axis. If this is None, a reduction is performed over all the axes. 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. For operations which are either not commutative or not associative, doing a reduction over multiple axes is not well-defined. The ufuncs do no currently raise an exception in this case, but will likely do so in the future.

dtypedtype, optional

The type used to represent the intermediate results. Defaults to the data-type of the output array if this is provided, or the data-type of the input array if no output array is provided.

outndarray, optional

A location into which the result is stored. If not provided or None, a freshly-allocated array is returned.

keepdimsbool, 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 array.

initialscalar, optional

The value with which to start the reduction. If the ufunc has no identity or the dtype is object, this defaults to None - otherwise it defaults to ufunc.identity. If None is given, the first element of the reduction is used, and an error is thrown if the reduction is empty.

wherearray_like of bool, optional

A boolean array which shape is same as shape of array, and selects elements to include in the reduction. Note that for ufuncs like minimum that do not have an identity defined, one has to pass in also initial.

Returns
rndarray

The reduced array. If out was supplied, r is a reference to it.

Restriction

  • If an ndarray is passed to where and where.shape != a.shape, NotImplementedError occurs.

  • If an ndarray is passed to out and out.shape != r.shape, NotImplementedError occurs.

Examples

>>> import nlcpy as vp
>>> vp.multiply.reduce([2,3,5])
array(30)

A multi-dimensional array example:

>>> X = vp.arange(8).reshape((2,2,2))
>>> X
array([[[0, 1],
        [2, 3]],

       [[4, 5],
        [6, 7]]])
>>> vp.add.reduce(X, 0)
array([[ 4,  6],
       [ 8, 10]])
>>> vp.add.reduce(X) # confirm: default axis value is 0
array([[ 4,  6],
       [ 8, 10]])
>>> vp.add.reduce(X, 1)
array([[ 2,  4],
       [10, 12]])
>>> vp.add.reduce(X, 2)
array([[ 1,  5],
       [ 9, 13]])

You can use the initial keyword argument to initialize the reduction with a different value, and where to select specific elements to include:

>>> vp.add.reduce([10], initial=5)
array(15)
>>> vp.add.reduce(vp.ones((2, 2, 2)), axis=(0, 2), initial=10)
array([14., 14.])
>>> a = vp.array([10., vp.nan, 10])
>>> vp.add.reduce(a, where=~vp.isnan(a))
array(20.)

Allows reductions of empty arrays where they would normally fail, i.e. for ufuncs without an identity.

>>> vp.minimum.reduce([], initial=vp.inf)
array(inf)
>>> vp.minimum.reduce([[1., 2.], [3., 4.]], initial=10.)
array([1., 2.])
>>> vp.minimum.reduce([])  
Traceback (most recent call last):
    ...
    ValueError: zero-size array to reduction operation minimum
                which has no identity