Merge branch 'main' into cyclic-sets-domain

Author: sadielbartholomew

Changelog.rst

@@ -3,6 +3,9 @@ version 3.16.2
 
 **2024-04-??**
 
+* New keyword parameter to `cf.Field.regrids` and `cf.Field.regridc`:
+  ``return_esmpy_regrid_operator``
+  (https://github.com/NCAS-CMS/cf-python/issues/766)
 * Allow a halo to be added by `cf.Field.indices` and
   `cf.Field.subspace`
   (https://github.com/NCAS-CMS/cf-python/issues/759)
@@ -32,12 +35,20 @@ version 3.16.2
 * Fix bug in `cf.aggregate` that sometimes put a null transpose
   operation into the Dask graph when one was not needed
   (https://github.com/NCAS-CMS/cf-python/issues/754)
+* Fix bug in `cf.aggregate` that caused a failure when property values
+  were `numpy` arrays with two or more elements
+  (https://github.com/NCAS-CMS/cf-python/issues/764)
+* Fix bug in `cf.aggregate` that didn't correctly handle the
+  "actual_range" CF attribute
+  (https://github.com/NCAS-CMS/cf-python/issues/764)
 * Fix bug whereby `Field.cyclic` is not updated after a
   `Field.del_construct` operation
   (https://github.com/NCAS-CMS/cf-python/issues/758)
 * Fix bug that meant `cyclic()` always returned an empty
   set for domains produced by `cf.Field.domain`
   (https://github.com/NCAS-CMS/cf-python/issues/762)
+* Changed dependency: ``cfunits>=3.3.7``
+* Changed dependency: ``netCDF4>=1.6.5``
 
 ----
 

RELEASE.md

@@ -2,6 +2,17 @@
   heeding the Versioning Strategy (see
   https://ncas-cms.github.io/cf-python/releases.html#versioning-strategy).
 
+* Set the `NEXTVERSION` version marker across the codebase (added in PRs
+  to mark the next version where the exact number/name is not yet decided)
+  by recursively finding all occurences within the `cf` directory and replacing
+  them with the upcoming version name `X.Y.Z` (replace `X`, `Y` and `Z` with
+  appropriate numbers), via running this command in `cf-python` repo root
+  directory (don't run it repo-wide or it will e.g. edit this script!):
+
+  ```console
+  $ find cf/ -type f | xargs sed -i 's/NEXTVERSION/X.Y.Z/g'
+  ```
+
 * Change the version and date in `cf/__init__.py` (`__version__` and
   `__date__` variables)
 

cf/__init__.py

@@ -167,7 +167,7 @@
     )
 
 # Check the version of netCDF4
-_minimum_vn = "1.5.4"
+_minimum_vn = "1.6.5"
 if Version(netCDF4.__version__) < Version(_minimum_vn):
     raise RuntimeError(
         f"Bad netCDF4 version: cf requires netCDF4>={_minimum_vn}. "
@@ -191,7 +191,7 @@
     )
 
 # Check the version of cfunits
-_minimum_vn = "3.3.6"
+_minimum_vn = "3.3.7"
 if Version(cfunits.__version__) < Version(_minimum_vn):
     raise RuntimeError(
         f"Bad cfunits version: cf requires cfunits>={_minimum_vn}. "

cf/aggregate.py

@@ -4852,20 +4852,36 @@ def _aggregate_2_fields(
         value0 = parent0.get_property(prop, None)
         value1 = parent1.get_property(prop, None)
 
+        if prop in ("_FillValue", "missing_value"):
+            continue
+
         if prop in ("valid_min", "valid_max", "valid_range"):
             if not m0.respect_valid:
                 parent0.del_property(prop, None)
 
             continue
 
-        if prop in ("_FillValue", "missing_value"):
+        if prop == "actual_range":
+            try:
+                # Try to extend the actual range to encompass both
+                # value0 and value1
+                actual_range = (
+                    min(value0[0], value1[0]),
+                    max(value0[1], value1[1]),
+                )
+            except (TypeError, IndexError, KeyError):
+                # value0 and/or value1 is not set, or is
+                # non-CF-compliant.
+                parent0.del_property(prop, None)
+            else:
+                parent0.set_property(prop, actual_range)
+
             continue
 
         # Still here?
-        if isinstance(value0, str) or isinstance(value1, str):
-            if value0 == value1:
-                continue
-        elif parent0._equals(value0, value1):
+        if parent0._equals(value0, value1):
+            # Both values are equal, so no need to update the
+            # property.
             continue
 
         if concatenate:
@@ -4876,9 +4892,30 @@ def _aggregate_2_fields(
                     )
                 else:
                     parent0.set_property(prop, f" :AGGREGATED: {value1}")
-        else:
-            if value0 is not None:
-                parent0.del_property(prop)
+        elif value0 is not None:
+            parent0.del_property(prop)
+
+    # Check that actual_range is within the bounds of valid_range, and
+    # delete it if it isn't.
+    actual_range = parent0.get_property("actual_range", None)
+    if actual_range is not None:
+        valid_range = parent0.get_property("valid_range", None)
+        if valid_range is not None:
+            try:
+                if (
+                    actual_range[0] < valid_range[0]
+                    or actual_range[1] > valid_range[1]
+                ):
+                    actual_range = parent0.del_property("actual_range", None)
+                    if actual_range is not None and is_log_level_info(logger):
+                        logger.info(
+                            "Deleted 'actual_range' attribute due to being "
+                            "outside of 'valid_range' attribute limits."
+                        )
+                        
+            except (TypeError, IndexError):
+                # valid_range is non-CF-compliant
+                pass
 
     # Make a note that the parent construct in this _Meta object has
     # already been aggregated

cf/docstring/docstring.py

@@ -651,6 +651,11 @@
                                 operation and define a halo to be
                                 added to the subspaced axes.
                 ==============  ======================================""",
+    # return_esmpy_regrid_operator
+    "{{return_esmpy_regrid_operator: `bool`, optional}}": """return_esmpy_regrid_operator: `bool`, optional
+                If True then do not perform the regridding, rather
+                return the `esmpy.Regrid` instance that defines the
+                regridding operation.""",
     # ----------------------------------------------------------------
     # Method description substitutions (4 levels of indentation)
     # ----------------------------------------------------------------

cf/field.py

@@ -13512,6 +13512,7 @@ def regrids(
         z=None,
         ln_z=None,
         verbose=None,
+        return_esmpy_regrid_operator=False,
         inplace=False,
         i=False,
         _compute_field_mass=None,
@@ -13752,6 +13753,10 @@ def regrids(
 
             {{inplace: `bool`, optional}}
 
+            {{return_esmpy_regrid_operator: `bool`, optional}}
+
+                .. versionadded:: 3.16.2
+
             axis_order: sequence, optional
                 Deprecated at version 3.14.0.
 
@@ -13768,7 +13773,8 @@ def regrids(
             `Field` or `None` or `RegridOperator`
                 The regridded field construct; or `None` if the
                 operation was in-place; or the regridding operator if
-                *return_operator* is True.
+                *return_operator* is True; or the `esmpy.Regrid` operator
+                object if *return_esmpy_regrid_operator* is True.
 
         **Examples**
 
@@ -13843,6 +13849,7 @@ def regrids(
             dst_z=dst_z,
             z=z,
             ln_z=ln_z,
+            return_esmpy_regrid_operator=return_esmpy_regrid_operator,
             inplace=inplace,
         )
 
@@ -13866,6 +13873,7 @@ def regridc(
         dst_z=None,
         z=None,
         ln_z=None,
+        return_esmpy_regrid_operator=False,
         inplace=False,
         i=False,
         _compute_field_mass=None,
@@ -14041,6 +14049,10 @@ def regridc(
 
             {{inplace: `bool`, optional}}
 
+            {{return_esmpy_regrid_operator: `bool`, optional}}
+
+                .. versionadded:: 3.16.2
+
             axis_order: sequence, optional
                 Deprecated at version 3.14.0.
 
@@ -14057,7 +14069,8 @@ def regridc(
             `Field` or `None` or `RegridOperator`
                 The regridded field construct; or `None` if the
                 operation was in-place; or the regridding operator if
-                *return_operator* is True.
+                *return_operator* is True; or the `esmpy.Regrid` operator
+                object if *return_esmpy_regrid_operator* is True.
 
         **Examples**
 
@@ -14131,6 +14144,7 @@ def regridc(
             dst_z=dst_z,
             z=z,
             ln_z=ln_z,
+            return_esmpy_regrid_operator=return_esmpy_regrid_operator,
             inplace=inplace,
         )
 

cf/query.py

@@ -495,7 +495,6 @@ def __str__(self):
         if self.open_lower:
             repr_value = "(" + repr_value[1:]
 
-
         if self.open_upper:
             repr_value = repr_value[:-1] + ")"
 
@@ -1740,15 +1739,15 @@ def wi(
              bound so that value0 is excluded from the
              range. By default the interval is closed
              so that value0 is included.
-             
+
              .. versionadded:: NEXTVERSION
 
         open_upper: `bool`, optional
              If True, open the interval at the upper
              bound so that value1 is excluded from the
              range. By default the interval is closed
              so that value1 is included.
-             
+
              .. versionadded:: NEXTVERSION
 
         units: `str` or `Units`, optional

cf/test/test_aggregate.py

@@ -4,6 +4,8 @@
 import unittest
 import warnings
 
+import numpy as np
+
 faulthandler.enable()  # to debug seg faults and timeouts
 
 import cf
@@ -664,6 +666,77 @@ def test_aggregate_trajectory(self):
             )
         )
 
+    def test_aggregate_actual_range(self):
+        """Test aggregation of actual_range"""
+        f = cf.example_field(0)
+        f.set_property("actual_range", (5, 10))
+        f.set_property("valid_range", (0, 15))
+        f0 = f[:, :2]
+        f1 = f[:, 2:4]
+        f2 = f[:, 4:]
+
+        g = cf.aggregate([f0, f1, f2])
+        self.assertEqual(len(g), 1)
+        self.assertEqual(g[0].get_property("actual_range"), (5, 10))
+
+        f1.set_property("actual_range", [2, 13])
+        g = cf.aggregate([f0, f1, f2])
+        self.assertEqual(len(g), 1)
+        self.assertEqual(g[0].get_property("actual_range"), (2, 13))
+
+        f1.set_property("actual_range", [-2, 17])
+        g = cf.aggregate([f0, f1, f2])
+        self.assertEqual(len(g), 1)
+        self.assertEqual(g[0].get_property("actual_range"), (-2, 17))
+
+        g = cf.aggregate([f0, f1, f2], respect_valid=True)
+        self.assertEqual(len(g), 1)
+        self.assertEqual(g[0].get_property("valid_range"), (0, 15))
+        self.assertFalse(g[0].has_property("actual_range"))
+
+        f1.set_property("actual_range", [0, 15])
+        g = cf.aggregate([f0, f1, f2], respect_valid=True)
+        self.assertEqual(len(g), 1)
+        self.assertEqual(g[0].get_property("valid_range"), (0, 15))
+        self.assertEqual(g[0].get_property("actual_range"), (0, 15))
+
+    def test_aggregate_numpy_array_property(self):
+        """Test aggregation of numpy array-valued properties"""
+        a = np.array([5, 10])
+        f = cf.example_field(0)
+        f.set_property("array", a)
+        f0 = f[:, :2]
+        f1 = f[:, 2:4]
+        f2 = f[:, 4:]
+
+        g = cf.aggregate([f0, f1, f2])
+        self.assertEqual(len(g), 1)
+        self.assertTrue((g[0].get_property("array") == a).all())
+
+        f1.set_property("array", np.array([-5, 20]))
+        g = cf.aggregate([f0, f1, f2])
+        self.assertEqual(len(g), 1)
+        self.assertEqual(
+            g[0].get_property("array"),
+            "[ 5 10] :AGGREGATED: [-5 20] :AGGREGATED: [ 5 10]",
+        )
+
+        f2.set_property("array", np.array([-5, 20]))
+        g = cf.aggregate([f0, f1, f2])
+        self.assertEqual(len(g), 1)
+        self.assertEqual(
+            g[0].get_property("array"),
+            "[ 5 10] :AGGREGATED: [-5 20] :AGGREGATED: [-5 20]",
+        )
+
+        f1.set_property("array", np.array([5, 10]))
+        g = cf.aggregate([f0, f1, f2])
+        self.assertEqual(len(g), 1)
+        self.assertEqual(
+            g[0].get_property("array"),
+            "[ 5 10] :AGGREGATED: [-5 20]",
+        )
+
 
 if __name__ == "__main__":
     print("Run date:", datetime.datetime.now())

cf/test/test_regrid.py

@@ -791,6 +791,25 @@ def test_Field_regrid_weights_file(self):
                 src.regrids(r, method="linear", weights_file=tmpfile)
             )
 
+    @unittest.skipUnless(esmpy_imported, "Requires esmpy/ESMF package.")
+    def test_return_esmpy_regrid_operator(self):
+        """esmpy regrid operator returns esmpy.Regrid in regrids and regridc"""
+        dst = self.dst
+        src = self.src
+
+        opers = src.regrids(
+            dst, method="conservative", return_esmpy_regrid_operator=True
+        )
+        operc = src.regridc(
+            dst,
+            axes=["Y", "X"],
+            method="conservative",
+            return_esmpy_regrid_operator=True,
+        )
+
+        self.assertIsInstance(opers, esmpy.api.regrid.Regrid)
+        self.assertIsInstance(operc, esmpy.api.regrid.Regrid)
+
 
 if __name__ == "__main__":
     print("Run date:", datetime.datetime.now())

docs/source/contributing.rst

@@ -121,6 +121,7 @@ ideas, code, and documentation to the cf library:
 * Jonathan Gregory
 * Klaus Zimmermann
 * Kristian Sebastián
+* Mark Rhodes-Smith
 * Michael Decker
 * Sadie Bartholomew
 * Thibault Hallouin