Merge branch 'main' of github.com:NCAS-CMS/cf-python

Author: davidhassell

Changelog.rst

@@ -3,6 +3,12 @@ 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)
 * Added spherical regridding to discrete sampling geometry destination
   grids (https://github.com/NCAS-CMS/cf-python/issues/716)
 * Added 3-d spherical regridding to `cf.Field.regrids`, and the option
@@ -24,9 +30,25 @@ version 3.16.2
 * Fix bug in `cf.read` when reading UM files that caused LBPROC value
   131072 (Mean over an ensemble of parallel runs) to be ignored
   (https://github.com/NCAS-CMS/cf-python/issues/737)
+* New keyword parameters to `cf.wi`: ``open_lower`` and ``open_upper``
+  (https://github.com/NCAS-CMS/cf-python/issues/740)
 * 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

@@ -80,6 +80,13 @@
         Whether `esmpy` logging is enabled or not is determined by
         `cf.regrid_logging`. If it is enabled then logging takes place
         after every call. By default logging is disabled.""",
+    # subspace halos
+    "{{subspace halos}}": """If a halo is defined via a positional argument, then each
+        subspaced axis will be extended to include that many extra
+        elements at each "side" of the axis. The number of extra
+        elements will be automatically reduced if including the full
+        amount defined by the halo would extend the subspace beyond
+        the axis limits.""",
     # ----------------------------------------------------------------
     # Method description substitutions (3 levels of indentation)
     # ----------------------------------------------------------------
@@ -613,6 +620,42 @@
     "{{to_size: `int`, optional}}": """to_size: `int`, optional
                 Pad the axis after so that the new axis has the given
                 size.""",
+    # subspace config options
+    "{{config: optional}}": """config: optional
+                Configure the subspace by specifying the mode of
+                operation (``mode``) and any halo to be added to the
+                subspaced axes (``halo``), with positional arguments
+                in the format ``mode``, or ``halo``, or ``mode,
+                halo``, or with no positional arguments at all.
+
+                A mode of operation is given as a `str`, and a halo as
+                a non-negative `int` (or any object that can be
+                converted to one):
+
+                ==============  ======================================
+                *mode*          Description
+                ==============  ======================================
+                Not provided    If no positional arguments are
+                                provided then assume the
+                                ``'compress'`` mode of operation with
+                                no halo added to the subspaced axes.
+
+                ``mode``        Define the mode of operation with no
+                                halo added to the subspaced axes.
+
+                ``mode, halo``  Define a mode of operation, as well as
+                                a halo to be added to the subspaced
+                                axes.
+
+                ``halo``        Assume the ``'compress'`` mode of
+                                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)
     # ----------------------------------------------------------------
@@ -663,4 +706,49 @@
                 The removed CFA-netCDF file name substitution. If the
                 substitution was not defined then an empty dictionary
                 is returned.""",
+    # subspace valid modes Field
+    "{{subspace valid modes Field}}": """Valid modes are:
+
+                * ``'compress'`` This is the default.
+                     Unselected locations are removed to create the
+                     subspace. If the result is not hyperrectangular
+                     then the minimum amount of unselected locations
+                     required to make it so will also be specially
+                     selected. Missing data is inserted at the
+                     specially selected locations, unless a halo has
+                     been defined (of any size, including 0).
+
+                * ``'envelope'``
+                     The subspace is the smallest hyperrectangular
+                     subspace that contains all of the selected
+                     locations. Missing data is inserted at unselected
+                     locations within the envelope, unless a halo has
+                     been defined (of any size, including 0).
+
+                * ``'full'``
+                     The subspace has the same domain as the original
+                     construct. Missing data is inserted at unselected
+                     locations, unless a halo has been defined (of any
+                     size, including 0).
+
+                .. note:: Setting a halo size of `0` differs from not
+                          not defining a halo at all. The shape of the
+                          returned field will always be the same, but
+                          in the former case missing data will not be
+                          inserted at unselected locations (if any)
+                          within the output domain.""",
+    # subspace valid modes Domain
+    "{{subspace valid modes Domain}}": """Valid modes are:
+
+                * ``'compress'`` This is the default.
+                     Unselected locations are removed to create the
+                     subspace. If the result is not hyperrectangular
+                     then the minimum amount of unselected locations
+                     required to make it so will also be specially
+                     selected.
+
+                * ``'envelope'``
+                     The subspace is the smallest hyperrectangular
+                     subspace that contains all of the selected
+                     locations.""",
 }