numpy · mattip · Jan 4, 2019 · Dec 10, 2017
diff --git a/doc/release/1.17.0-notes.rst b/doc/release/1.17.0-notes.rst
@@ -35,6 +35,15 @@ C API changes
 New Features
 ============
 
+``np.ufunc.reduce`` and related functions now accept a ``where`` mask
+---------------------------------------------------------------------
+``np.ufunc.reduce``, ``np.sum``, ``np.prod``, ``np.min``, ``np.max`` all
+now accept a ``where`` keyword argument, which can be used to tell which
+elements to include in the reduction.  For reductions that do not have an
+identity, it is necessary to also pass in an initial value (e.g.,
+``initial=np.inf`` for ``np.min``).  For instance, the equivalent of
+``nansum`` would be, ``np.sum(a, where=~np.isnan(a))``.
+
 
 Improvements
 ============

diff --git a/numpy/core/_add_newdocs.py b/numpy/core/_add_newdocs.py
@@ -3178,7 +3178,7 @@
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('max',
     """
-    a.max(axis=None, out=None, keepdims=False)
+    a.max(axis=None, out=None, keepdims=False, initial=<no value>, where=True)
 
     Return the maximum along a given axis.
 
@@ -3208,7 +3208,7 @@
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('min',
     """
-    a.min(axis=None, out=None, keepdims=False)
+    a.min(axis=None, out=None, keepdims=False, initial=<no value>, where=True)
 
     Return the minimum along a given axis.
 
@@ -3361,7 +3361,7 @@
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('prod',
     """
-    a.prod(axis=None, dtype=None, out=None, keepdims=False)
+    a.prod(axis=None, dtype=None, out=None, keepdims=False, initial=1, where=True)
 
     Return the product of the array elements over the given axis
 
@@ -3930,7 +3930,7 @@
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('sum',
     """
-    a.sum(axis=None, dtype=None, out=None, keepdims=False)
+    a.sum(axis=None, dtype=None, out=None, keepdims=False, initial=0, where=True)
 
     Return the sum of the array elements over the given axis.
 
@@ -4876,7 +4876,7 @@
 
 add_newdoc('numpy.core', 'ufunc', ('reduce',
     """
-    reduce(a, axis=0, dtype=None, out=None, keepdims=False, initial)
+    reduce(a, axis=0, dtype=None, out=None, keepdims=False, initial=<no value>, where=True)
 
     Reduces `a`'s dimension by one, by applying ufunc along one axis.
 
@@ -4941,6 +4941,14 @@
 
         .. versionadded:: 1.15.0
 
+    where : array_like of bool, optional
+        A boolean array which is broadcasted to match the dimensions
+        of `a`, 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``.
+
+        .. versionadded:: 1.17.0
+
     Returns
     -------
     r : ndarray
@@ -4972,19 +4980,24 @@
     array([[ 1,  5],
            [ 9, 13]])
 
-    You can use the ``initial`` keyword argument to initialize the reduction with a
-    different value.
+    You can use the ``initial`` keyword argument to initialize the reduction
+    with a different value, and ``where`` to select specific elements to include:
 
     >>> np.add.reduce([10], initial=5)
     15
     >>> np.add.reduce(np.ones((2, 2, 2)), axis=(0, 2), initial=10)
     array([14., 14.])
+    >>> a = np.array([10., np.nan, 10])
+    >>> np.add.reduce(a, where=~np.isnan(a))
+    20.0
 
     Allows reductions of empty arrays where they would normally fail, i.e.
     for ufuncs without an identity.
 
     >>> np.minimum.reduce([], initial=np.inf)
     inf
+    >>> np.minimum.reduce([[1., 2.], [3., 4.]], initial=10., where=[True, False])
+    array([ 1., 10.])
     >>> np.minimum.reduce([])
     Traceback (most recent call last):
         ...
@@ -6721,60 +6734,60 @@
 add_newdoc('numpy.core.numerictypes', 'number',
     """
     Abstract base class of all numeric scalar types.
-    
+
     """)
 
 add_newdoc('numpy.core.numerictypes', 'integer',
     """
     Abstract base class of all integer scalar types.
-    
+
     """)
 
 add_newdoc('numpy.core.numerictypes', 'signedinteger',
     """
     Abstract base class of all signed integer scalar types.
-    
+
     """)
 
 add_newdoc('numpy.core.numerictypes', 'unsignedinteger',
     """
     Abstract base class of all unsigned integer scalar types.
-    
+
     """)
 
 add_newdoc('numpy.core.numerictypes', 'inexact',
     """
     Abstract base class of all numeric scalar types with a (potentially)
     inexact representation of the values in its range, such as
     floating-point numbers.
-    
+
     """)
 
 add_newdoc('numpy.core.numerictypes', 'floating',
     """
     Abstract base class of all floating-point scalar types.
-    
+
     """)
 
 add_newdoc('numpy.core.numerictypes', 'complexfloating',
     """
     Abstract base class of all complex number scalar types that are made up of
     floating-point numbers.
-    
+
     """)
 
 add_newdoc('numpy.core.numerictypes', 'flexible',
     """
     Abstract base class of all scalar types without predefined length.
     The actual size of these types depends on the specific `np.dtype`
     instantiation.
-    
+
     """)
 
 add_newdoc('numpy.core.numerictypes', 'character',
     """
     Abstract base class of all character string scalar types.
-    
+
     """)
 
 

diff --git a/numpy/core/_methods.py b/numpy/core/_methods.py
@@ -24,20 +24,20 @@
 # avoid keyword arguments to speed up parsing, saves about 15%-20% for very
 # small reductions
 def _amax(a, axis=None, out=None, keepdims=False,
-          initial=_NoValue):
-    return umr_maximum(a, axis, None, out, keepdims, initial)
+          initial=_NoValue, where=True):
+    return umr_maximum(a, axis, None, out, keepdims, initial, where)
 
 def _amin(a, axis=None, out=None, keepdims=False,
-          initial=_NoValue):
-    return umr_minimum(a, axis, None, out, keepdims, initial)
+          initial=_NoValue, where=True):
+    return umr_minimum(a, axis, None, out, keepdims, initial, where)
 
 def _sum(a, axis=None, dtype=None, out=None, keepdims=False,
-         initial=_NoValue):
-    return umr_sum(a, axis, dtype, out, keepdims, initial)
+         initial=_NoValue, where=True):
+    return umr_sum(a, axis, dtype, out, keepdims, initial, where)
 
 def _prod(a, axis=None, dtype=None, out=None, keepdims=False,
-          initial=_NoValue):
-    return umr_prod(a, axis, dtype, out, keepdims, initial)
+          initial=_NoValue, where=True):
+    return umr_prod(a, axis, dtype, out, keepdims, initial, where)
 
 def _any(a, axis=None, dtype=None, out=None, keepdims=False):
     return umr_any(a, axis, dtype, out, keepdims)