Merge pull request #910 from davidhassell/healpix

Implement HEALPix grids

Author: davidhassell

Changelog.rst

@@ -3,6 +3,21 @@ Version NEXTVERSION
 
 **2026-??-??**
 
+* Support for HEALPix grids
+  (https://github.com/NCAS-CMS/cf-python/issues/909)
+* New HEALPix methods: `cf.Field.healpix_info`,
+  `cf.Field.healpix_decrease_refinement_level`,
+  `cf.Field.healpix_increase_refinement_level`,
+  `cf.Field.healpix_change_indexing_scheme`,
+  `cf.Field.healpix_to_ugrid`, `cf.Domain.create_healpix`
+  (https://github.com/NCAS-CMS/cf-python/issues/909)
+* New method: `cf.Field.create_latlon_coordinates`
+  (https://github.com/NCAS-CMS/cf-python/issues/909)
+* New method: `cf.Data.coarsen`
+  (https://github.com/NCAS-CMS/cf-python/issues/909)
+* New functions: `cf.locate`, `cf.healpix_max_refinement_level`,
+  `cf.healpix_indexing_schemes`
+  (https://github.com/NCAS-CMS/cf-python/issues/909)
 * New keyword to `cf.read`: ``filesystem``
   (https://github.com/NCAS-CMS/cf-python/issues/931)
 * New keyword parameter to `cf.Data.compute`: ``persist``
@@ -24,7 +39,11 @@ Version NEXTVERSION
   (https://github.com/NCAS-CMS/cfdm/issues/391)
 * Fix for subspacing with cyclic `cf.wi` and `cf.wo` arguments
   (https://github.com/NCAS-CMS/cf-python/issues/887)
-* Changed dependency: ``cfdm>=1.13.1.0, <1.13.2.0``
+* New optional dependency: ``healpix>=2025.1``
+* New dependency: ``pyfive>=1.1.1``
+* Changed dependency: ``cfdm>=1.13.?.?, <1.13.?.0``
+
+----
 
 Version 3.19.0
 --------------
@@ -81,8 +100,8 @@ Version 3.18.1
 * Allow multiple conditions for the same axis in `cf.Field.subspace`
   and `cf.Field.indices`
   (https://github.com/NCAS-CMS/cf-python/issues/881)
-* Fix bug in `cf.Field.collapse` that causes a ``ValueError`` to be raised
-  for missing external cell measures data
+* Fix bug in `cf.Field.collapse` that causes a ``ValueError`` to be
+  raised for missing external cell measures data
   (https://github.com/NCAS-CMS/cf-python/issues/885)
 * New dependency: ``distributed>=2025.5.1``
 * Changed dependency: ``cfdm>=1.12.3.0, <1.12.4.0``

README.md

@@ -90,6 +90,7 @@ of its array manipulation and can:
 * write and append field and domain constructs to netCDF and Zarr v3
   datasets on disk, with control over HDF5 internal file metadata,
 * read, create, and manipulate UGRID mesh topologies,
+* read, write, and manipulate HEALPix grids,
 * read, write, and create coordinates defined by geometry cells,
 * read netCDF and CDL datasets containing hierarchical groups,
 * inspect field constructs,
@@ -105,11 +106,12 @@ of its array manipulation and can:
 * manipulate field construct data by arithmetical and trigonometrical
   operations,
 * perform weighted statistical collapses on field constructs,
-  including those with geometry cells and UGRID mesh topologies,
+  including those with geometry cells, UGRID mesh topologies, and
+  HEALPix grids,
 * perform histogram, percentile and binning operations on field
   constructs,
-* regrid structured grid, mesh and DSG field constructs with
-  (multi-)linear, nearest neighbour, first- and second-order
+* regrid structured grid, UGRID, HEALPix, and DSG field constructs
+  with (multi-)linear, nearest neighbour, first- and second-order
   conservative and higher order patch recovery methods, including 3-d
   regridding, and large-grid support,
 * apply convolution filters to field constructs,

cf/__init__.py

@@ -119,7 +119,6 @@
 from .tiepointindex import TiePointIndex
 
 from .bounds import Bounds
-from .domain import Domain
 from .datum import Datum
 from .coordinateconversion import CoordinateConversion
 
@@ -138,6 +137,7 @@
 from .cellconnectivity import CellConnectivity
 from .cellmethod import CellMethod
 from .cellmeasure import CellMeasure
+from .domain import Domain
 from .domainancillary import DomainAncillary
 from .domainaxis import DomainAxis
 from .domaintopology import DomainTopology

cf/cellconnectivity.py

@@ -49,7 +49,8 @@ class CellConnectivity(mixin.PropertiesData, cfdm.CellConnectivity):
     from any other sources, but is consistent with UGRID encoding
     within CF-netCDF.
 
-    See CF Appendix I "The CF Data Model".
+    See CF Appendix I: The CF Data Model.
+    https://doi.org/10.5281/zenodo.14274886
 
     **NetCDF interface**
 

cf/constants.py

@@ -493,6 +493,31 @@
     },
 }
 
+# --------------------------------------------------------------------
+# CF cell methods
+# --------------------------------------------------------------------
+cell_methods = set(
+    (
+        "point",
+        "sum",
+        "maximum",
+        "maximum_absolute_value",
+        "median",
+        "mid_range",
+        "minimum",
+        "minimum_absolute_value",
+        "mean",
+        "mean_absolute_value",
+        "mean_of_upper_decile",
+        "mode",
+        "range",
+        "root_mean_square",
+        "standard_deviation",
+        "sum_of_squares",
+        "variance",
+    )
+)
+
 
 # --------------------------------------------------------------------
 # Logging level setup

cf/data/dask_utils.py

@@ -1,6 +1,6 @@
-"""Functions intended to be passed to be dask.
+"""Functions intended to be passed to be Dask.
 
-These will typically be functions that operate on dask chunks. For
+These will typically be functions that operate on Dask chunks. For
 instance, as would be passed to `dask.array.map_blocks`.
 
 """
@@ -62,7 +62,7 @@ def cf_convolve1d(a, window=None, axis=-1, origin=0):
 
         origin: `int`, optional
             Controls the placement of the filter on the input array’s
-            pixels. A value of 0 (the default) centers the filter over
+            pixels. A value of 0 (the default) centres the filter over
             the pixel, with positive values shifting the filter to the
             left, and negative ones to the right.
 
@@ -165,7 +165,7 @@ def cf_percentile(a, q, axis, method, keepdims=False, mtol=1):
     if np.ma.isMA(a):
         # ------------------------------------------------------------
         # Input array is masked: Replace missing values with NaNs and
-        # remask later.
+        # re-mask later.
         # ------------------------------------------------------------
         if a.dtype != float:
             # Can't assign NaNs to integer arrays