ENH: Add compressed= argument to ma.ndenumerate

Author: joukewitteveen

doc/release/upcoming_changes/20020.new_function.rst

@@ -1,4 +1,4 @@
 `ndenumerate` specialization for masked arrays
 ----------------------------------------------
 The masked array module now provides the `numpy.ma.ndenumerate` function,
-an alternative to `numpy.ndenumerate` that skips masked values.
+an alternative to `numpy.ndenumerate` that skips masked values by default.

numpy/ma/extras.py

@@ -1520,18 +1520,26 @@ def __init__(self):
 #---- Find unmasked data ---
 #####--------------------------------------------------------------------------
 
-def ndenumerate(a):
+def ndenumerate(a, compressed=True):
     """
     Multidimensional index iterator.
 
-    Return an iterator yielding pairs of array coordinates and values of
-    elements that are not masked.
+    Return an iterator yielding pairs of array coordinates and values,
+    skipping elements that are masked. With `compressed=False`,
+    `ma.masked` is yielded as the value of masked elements. This
+    behavior differs from that of `numpy.ndenumerate`, which yields the
+    value of the underlying data array.
+
+    Notes
+    -----
     .. versionadded:: 1.23.0
-    
+
     Parameters
     ----------
     a : array_like
         An array with (possibly) masked elements.
+    compressed : bool, optional
+        If True (default), masked elements are skipped.
 
     See Also
     --------
@@ -1560,10 +1568,24 @@ def ndenumerate(a):
     (1, 1) 4
     (2, 0) 6
     (2, 2) 8
+
+    >>> for index, x in np.ma.ndenumerate(a, compressed=False):
+    ...     print(index, x)
+    (0, 0) 0
+    (0, 1) 1
+    (0, 2) 2
+    (1, 0) --
+    (1, 1) 4
+    (1, 2) --
+    (2, 0) 6
+    (2, 1) --
+    (2, 2) 8
     """
-    for it, masked in zip(np.ndenumerate(a), getmaskarray(a).flat):
-        if not masked:
+    for it, mask in zip(np.ndenumerate(a), getmaskarray(a).flat):
+        if not mask:
             yield it
+        elif not compressed:
+            yield it[0], masked
 
 
 def flatnotmasked_edges(a):

numpy/ma/extras.pyi

@@ -74,7 +74,7 @@ class mr_class(MAxisConcatenator):
 
 mr_: mr_class
 
-def ndenumerate(a): ...
+def ndenumerate(a, compressed=...): ...
 def flatnotmasked_edges(a): ...
 def notmasked_edges(a, axis=...): ...
 def flatnotmasked_contiguous(a): ...

numpy/ma/tests/test_extras.py

@@ -1658,14 +1658,20 @@ def test_ndenumerate_nomasked(self):
                      list(ndenumerate(ordinary)))
         assert_equal(list(ndenumerate(ordinary)),
                      list(ndenumerate(with_mask)))
+        assert_equal(list(ndenumerate(with_mask)),
+                     list(ndenumerate(with_mask, compressed=False)))
 
     def test_ndenumerate_allmasked(self):
         a = masked_all(())
         b = masked_all((100,))
         c = masked_all((2, 3, 4))
         assert_equal(list(ndenumerate(a)), [])
         assert_equal(list(ndenumerate(b)), [])
+        assert_equal(list(ndenumerate(b, compressed=False)),
+                     list(zip(np.ndindex((100,)), 100 * [masked])))
         assert_equal(list(ndenumerate(c)), [])
+        assert_equal(list(ndenumerate(c, compressed=False)),
+                     list(zip(np.ndindex((2, 3, 4)), 2 * 3 * 4 * [masked])))
 
     def test_ndenumerate_mixedmasked(self):
         a = masked_array(np.arange(12).reshape((3, 4)),
@@ -1675,6 +1681,9 @@ def test_ndenumerate_mixedmasked(self):
         items = [((1, 2), 6),
                  ((2, 0), 8), ((2, 1), 9), ((2, 2), 10), ((2, 3), 11)]
         assert_equal(list(ndenumerate(a)), items)
+        assert_equal(len(list(ndenumerate(a, compressed=False))), a.size)
+        for coordinate, value in ndenumerate(a, compressed=False):
+            assert_equal(a[coordinate], value)
 
 
 class TestStack: