Upgrade iris.util.mask_cube

docs/src/whatsnew/latest.rst

@@ -76,6 +76,10 @@ This document explains the changes made to Iris for this release
    :func:`iris.plot.fill_between` and :func:`iris.quickplot.fill_between`.
    (:issue:`3493`, :pull:`4647`)
 
+#. `@rcomer`_ and `@bjlittle`_ (reviewer) re-wrote :func:`iris.util.mask_cube`
+   to provide lazy evaluation and greater flexibility with respect to input types.
+   (:issue:`3936`, :pull:`4889`)
+
 
 🐛 Bugs Fixed
 =============
@@ -132,6 +136,9 @@ This document explains the changes made to Iris for this release
    array type.  This prevents masks being lost in some cases and therefore
    resolves :issue:`2987`.  (:pull:`3790`)
 
+#. `@rcomer`_ and `@bjlittle`_ (reviewer) modified :func:`iris.util.mask_cube` so it
+   either works in place or returns a new cube (:issue:`3717`, :pull:`4889`)
+
 
 💣 Incompatible Changes
 =======================
@@ -265,7 +272,7 @@ This document explains the changes made to Iris for this release
 
 #. `@bjlittle`_ and `@trexfeathers`_ (reviewer) added building, testing and
    publishing of ``iris`` PyPI ``sdist`` and binary ``wheels`` as part of
-   our GitHub Continuous-Integration. (:pull`4849`)
+   our GitHub Continuous-Integration. (:pull:`4849`)
 
 .. comment
     Whatsnew author names (@github name) in alphabetical order. Note that,

lib/iris/analysis/maths.py

@@ -774,6 +774,7 @@ def _binary_op_common(
     new_dtype=None,
     dim=None,
     in_place=False,
+    sanitise_metadata=True,
 ):
     """
     Function which shares common code between binary operations.
@@ -792,6 +793,8 @@ def _binary_op_common(
                            coordinate that is not found in `cube`
     in_place             - whether or not to apply the operation in place to
                            `cube` and `cube.data`
+    sanitise_metadata    - whether or not to remove metadata using
+                           _sanitise_metadata function
     """
     from iris.cube import Cube
 
@@ -858,13 +861,15 @@ def unary_func(lhs):
         new_dtype=new_dtype,
         in_place=in_place,
         skeleton_cube=skeleton_cube,
+        sanitise_metadata=sanitise_metadata,
     )
 
     if isinstance(other, Cube):
         # Insert the resultant data from the maths operation
         # within the resolved cube.
         result = resolver.cube(result.core_data(), in_place=in_place)
-        _sanitise_metadata(result, new_unit)
+        if sanitise_metadata:
+            _sanitise_metadata(result, new_unit)
 
     return result
 
@@ -946,6 +951,7 @@ def _math_op_common(
     new_dtype=None,
     in_place=False,
     skeleton_cube=False,
+    sanitise_metadata=True,
 ):
     from iris.cube import Cube
 
@@ -979,7 +985,8 @@ def _math_op_common(
     ):
         new_cube.data = ma.masked_array(0, 1, dtype=new_dtype)
 
-    _sanitise_metadata(new_cube, new_unit)
+    if sanitise_metadata:
+        _sanitise_metadata(new_cube, new_unit)
 
     return new_cube
 

lib/iris/common/metadata.py

@@ -44,8 +44,6 @@
 
 # https://www.unidata.ucar.edu/software/netcdf/docs/netcdf_data_set_components.html#object_name
 
-from ..util import guess_coord_axis
-
 _TOKEN_PARSE = re.compile(r"""^[a-zA-Z0-9][\w\.\+\-@]*$""")
 
 # Configure the logger.
@@ -1413,6 +1411,8 @@ def metadata_filter(
         to only those that matched the given criteria.
 
     """
+    from ..util import guess_coord_axis
+
     name = None
     obj = None
 

lib/iris/tests/__init__.py

@@ -141,6 +141,73 @@ def main():
         unittest.main()
 
 
+def _assert_masked_array(assertion, a, b, strict, **kwargs):
+    # Compare masks.
+    a_mask, b_mask = ma.getmaskarray(a), ma.getmaskarray(b)
+    np.testing.assert_array_equal(a_mask, b_mask)
+
+    if strict:
+        # Compare all data values.
+        assertion(a.data, b.data, **kwargs)
+    else:
+        # Compare only unmasked data values.
+        assertion(
+            ma.compressed(a),
+            ma.compressed(b),
+            **kwargs,
+        )
+
+
+def assert_masked_array_equal(a, b, strict=False):
+    """
+    Check that masked arrays are equal. This requires the
+    unmasked values and masks to be identical.
+
+    Args:
+
+    * a, b (array-like):
+        Two arrays to compare.
+
+    Kwargs:
+
+    * strict (bool):
+        If True, perform a complete mask and data array equality check.
+        If False (default), the data array equality considers only unmasked
+        elements.
+
+    """
+    _assert_masked_array(np.testing.assert_array_equal, a, b, strict)
+
+
+def assert_masked_array_almost_equal(a, b, decimal=6, strict=False):
+    """
+    Check that masked arrays are almost equal. This requires the
+    masks to be identical, and the unmasked values to be almost
+    equal.
+
+    Args:
+
+    * a, b (array-like):
+        Two arrays to compare.
+
+    Kwargs:
+
+    * strict (bool):
+        If True, perform a complete mask and data array equality check.
+        If False (default), the data array equality considers only unmasked
+        elements.
+
+    * decimal (int):
+        Equality tolerance level for
+        :meth:`numpy.testing.assert_array_almost_equal`, with the meaning
+        'abs(desired-actual) < 0.5 * 10**(-decimal)'
+
+    """
+    _assert_masked_array(
+        np.testing.assert_array_almost_equal, a, b, strict, decimal=decimal
+    )
+
+
 class IrisTest_nometa(unittest.TestCase):
     """A subclass of unittest.TestCase which provides Iris specific testing functionality."""
 
@@ -587,72 +654,14 @@ def assertNoWarningsRegexp(self, expected_regexp=""):
         msg = msg.format(expected_regexp, matches)
         self.assertFalse(matches, msg)
 
-    def _assertMaskedArray(self, assertion, a, b, strict, **kwargs):
-        # Compare masks.
-        a_mask, b_mask = ma.getmaskarray(a), ma.getmaskarray(b)
-        np.testing.assert_array_equal(a_mask, b_mask)
-
-        if strict:
-            # Compare all data values.
-            assertion(a.data, b.data, **kwargs)
-        else:
-            # Compare only unmasked data values.
-            assertion(
-                ma.compressed(a),
-                ma.compressed(b),
-                **kwargs,
-            )
-
-    def assertMaskedArrayEqual(self, a, b, strict=False):
-        """
-        Check that masked arrays are equal. This requires the
-        unmasked values and masks to be identical.
-
-        Args:
-
-        * a, b (array-like):
-            Two arrays to compare.
-
-        Kwargs:
-
-        * strict (bool):
-            If True, perform a complete mask and data array equality check.
-            If False (default), the data array equality considers only unmasked
-            elements.
-
-        """
-        self._assertMaskedArray(np.testing.assert_array_equal, a, b, strict)
+    assertMaskedArrayEqual = staticmethod(assert_masked_array_equal)
 
     def assertArrayAlmostEqual(self, a, b, decimal=6):
         np.testing.assert_array_almost_equal(a, b, decimal=decimal)
 
-    def assertMaskedArrayAlmostEqual(self, a, b, decimal=6, strict=False):
-        """
-        Check that masked arrays are almost equal. This requires the
-        masks to be identical, and the unmasked values to be almost
-        equal.
-
-        Args:
-
-        * a, b (array-like):
-            Two arrays to compare.
-
-        Kwargs:
-
-        * strict (bool):
-            If True, perform a complete mask and data array equality check.
-            If False (default), the data array equality considers only unmasked
-            elements.
-
-        * decimal (int):
-            Equality tolerance level for
-            :meth:`numpy.testing.assert_array_almost_equal`, with the meaning
-            'abs(desired-actual) < 0.5 * 10**(-decimal)'
-
-        """
-        self._assertMaskedArray(
-            np.testing.assert_array_almost_equal, a, b, strict, decimal=decimal
-        )
+    assertMaskedArrayAlmostEqual = staticmethod(
+        assert_masked_array_almost_equal
+    )
 
     def assertArrayAllClose(self, a, b, rtol=1.0e-7, atol=1.0e-8, **kwargs):
         """

lib/iris/tests/results/unit/util/mask_cube/TestCubeMask/mask_cube_2d_create_new_dim.cml

@@ -0,0 +1,23 @@
+<?xml version="1.0" ?>
+<cubes xmlns="urn:x-iris:cubeml-0.2">
+  <cube dtype="int32" long_name="thingness" units="1">
+    <coords>
+      <coord datadims="[1]">
+        <dimCoord bounds="[[0, 5],
+		[5, 10],
+		[10, 15]]" id="434cbbd8" long_name="bar" points="[2.5, 7.5, 12.5]" shape="(3,)" units="Unit('1')" value_type="float64"/>
+      </coord>
+      <coord datadims="[0]">
+        <dimCoord id="cc587fe7" long_name="baz" points="[1]" shape="(1,)" units="Unit('unknown')" value_type="int64"/>
+      </coord>
+      <coord datadims="[2]">
+        <dimCoord bounds="[[-15, 0],
+		[0, 15],
+		[15, 30],
+		[30, 45]]" id="b0d35dcf" long_name="foo" points="[-7.5, 7.5, 22.5, 37.5]" shape="(4,)" units="Unit('1')" value_type="float64"/>
+      </coord>
+    </coords>
+    <cellMethods/>
+    <data dtype="int32" shape="(1, 3, 4)" state="loaded"/>
+  </cube>
+</cubes>

lib/iris/tests/results/unit/util/mask_cube/original_cube_full2d_global.cml

@@ -0,0 +1,123 @@
+<?xml version="1.0" ?>
+<cubes xmlns="urn:x-iris:cubeml-0.2">
+  <cube dtype="float64" long_name="test_data" units="unknown">
+    <coords>
+      <coord datadims="[0, 1]">
+        <auxCoord bounds="[[[-75.0, -75.0, -57.2567807439, -51.25],
+		 [-75.0, -75.0, -69.9122998144, -57.2567807439],
+		 [-75.0, -75.0, -81.2290044761, -69.9122998144],
+		 [-75.0, -75.0, -70.8808697668, -81.2290044761],
+		 [-75.0, -75.0, -57.9305320523, -70.8808697668],
+		 [-75.0, -75.0, -51.25, -57.9305320523]],
+
+		[[-51.25, -57.2567807439, -21.7742578897, -13.75],
+		 [-57.2567807439, -69.9122998144,
+		  -35.7623963265, -21.7742578897],
+		 [-69.9122998144, -81.2290044761,
+		  -43.7403643588, -35.7623963265],
+		 [-81.2290044761, -70.8808697668,
+		  -36.6390269341, -43.7403643588],
+		 [-70.8808697668, -57.9305320523,
+		  -22.6232024783, -36.6390269341],
+		 [-57.9305320523, -51.25, -13.75, -22.6232024783]],
+
+		[[-13.75, -21.7742578897, 14.6262783141, 23.75],
+		 [-21.7742578897, -35.7623963265,
+		  0.679347324478, 14.6262783141],
+		 [-35.7623963265, -43.7403643588,
+		  -6.24210578521, 0.679347324478],
+		 [-43.7403643588, -36.6390269341,
+		  -0.118134694909, -6.24210578521],
+		 [-36.6390269341, -22.6232024783, 13.7123678497,
+		  -0.118134694909],
+		 [-22.6232024783, -13.75, 23.75, 13.7123678497]],
+
+		[[23.75, 14.6262783141, 50.4991340056, 61.25],
+		 [14.6262783141, 0.679347324478, 37.1021660611,
+		  50.4991340056],
+		 [0.679347324478, -6.24210578521, 31.2564224569,
+		  37.1021660611],
+		 [-6.24210578521, -3.18012024006, 33.8310998481,
+		  31.2564224569],
+		 [-0.118134694909, 13.7123678497, 49.5342960461,
+		  36.4057772393],
+		 [13.7123678497, 23.75, 61.25, 49.5342960461]],
+
+		[[61.25, 50.4991340056, 75.0, 75.0],
+		 [50.4991340056, 37.1021660611, 75.0, 75.0],
+		 [37.1021660611, 31.2564224569, 75.0, 75.0],
+		 [31.2564224569, 36.4057772393, 75.0, 75.0],
+		 [36.4057772393, 49.5342960461, 75.0, 75.0],
+		 [49.5342960461, 61.25, 75.0, 75.0]]]" id="4a0cb9d8" points="[[-70.7961145738, -74.5203958604, -79.0476747448,
+		 -79.2595436524, -74.8389567751, -70.9599042785],
+		[-34.989963491, -46.3517884836, -59.7214785713,
+		 -60.3401453215, -47.305395869, -35.499215647],
+		[1.97619064066, -10.62625029, -22.8593242282,
+		 -23.3491023719, -11.5954827152, 1.36966775272],
+		[38.9137083852, 25.5310373715, 14.3116992689,
+		 13.9163240699, 24.5854146491, 38.2153388581],
+		[74.197139644, 60.2584740617, 51.3246020373,
+		 51.0162734782, 59.4458301418, 73.2683437807]]" shape="(5, 6)" standard_name="latitude" units="Unit('degrees')" value_type="float64"/>
+      </coord>
+      <coord datadims="[0, 1]">
+        <auxCoord bounds="[[[-60.0, -60.0, -17.2931062095, -60.0],
+		 [-60.0, -60.0, 24.742912764, -17.2931062095],
+		 [-60.0, -60.0, 115.04242743, 24.742912764],
+		 [-60.0, -60.0, -148.197462302, 115.04242743],
+		 [-60.0, -60.0, -105.228875389, -148.197462302],
+		 [-60.0, -60.0, -60.0, -105.228875389]],
+
+		[[-60.0, -17.2931062095, -0.69097717571, -60.0],
+		 [-17.2931062095, 24.742912764, 53.4340192156,
+		  -0.69097717571],
+		 [24.742912764, 115.04242743, 117.724503302,
+		  53.4340192156],
+		 [115.04242743, -148.197462302, -177.360958845,
+		  117.724503302],
+		 [-148.197462302, -105.228875389, -122.73949261,
+		  -177.360958845],
+		 [-105.228875389, -60.0, -60.0, -122.73949261]],
+
+		[[-60.0, -0.69097717571, 8.49948186949, -60.0],
+		 [-0.69097717571, 53.4340192156, 62.9255300111,
+		  8.49948186949],
+		 [53.4340192156, 117.724503302, 118.135773572,
+		  62.9255300111],
+		 [117.724503302, -177.360958845, 173.454869583,
+		  118.135773572],
+		 [-177.360958845, -122.73949261, -132.204171509,
+		  173.454869583],
+		 [-122.73949261, -60.0, -60.0, -132.204171509]],
+
+		[[-60.0, 8.49948186949, 21.9836595677, -60.0],
+		 [8.49948186949, 62.9255300111, 72.5838679662,
+		  21.9836595677],
+		 [62.9255300111, 118.135773572, 118.483358091,
+		  72.5838679662],
+		 [118.135773572, 145.795321578, 141.390970654,
+		  118.483358091],
+		 [173.454869583, -132.204171509, -145.72980597,
+		  164.298583216],
+		 [-132.204171509, -60.0, -60.0, -145.72980597]],
+
+		[[-60.0, 21.9836595677, 120.0, 120.0],
+		 [21.9836595677, 72.5838679662, 120.0, 120.0],
+		 [72.5838679662, 118.483358091, 120.0, 120.0],
+		 [118.483358091, 164.298583216, 120.0, 120.0],
+		 [164.298583216, -145.72980597, 120.0, 120.0],
+		 [-145.72980597, -60.0, 120.0, 120.0]]]" id="62e940e0" points="[[-50.7175447217, -40.9826266898, -46.7402097263,
+		 -71.9376144392, -79.2929666671, -70.1456599595],
+		[-29.866905059, 17.6063897846, 77.9362302481,
+		 157.144794984, -141.037022232, -93.1717032401],
+		[-23.1394301399, 31.0068937913, 87.6986169901,
+		 148.321662383, -154.638587706, -100.505003277],
+		[-16.054306198, 41.2180029662, 92.7605422936,
+		 130.951355974, -164.738414415, -108.105216292],
+		[10.8597790893, 61.7798829479, 100.236123084,
+		 137.284819331, 175.51112189, -135.445943914]]" shape="(5, 6)" standard_name="longitude" units="Unit('degrees')" value_type="float64"/>
+      </coord>
+    </coords>
+    <cellMethods/>
+    <data dtype="float64" shape="(5, 6)" state="loaded"/>
+  </cube>
+</cubes>