dev

Author: davidhassell

cf/data/dask_utils.py

@@ -518,11 +518,13 @@ def cf_healpix_bounds(
             If True then return the bounds' longitudes.
 
         pole_longitude: `None` or number
-            The longitude of bounds that lie exactly on the north
-            (south) pole. If `None` (the default) then the longitude
-            of such a vertex will be the same as the south (north)
-            vertex of the same cell. If set to a number, then the
-            longitudes of all such vertices will be given that value.
+            Define the longitudes of vertices that lie exactly on the
+            north or south pole. If `None` (the default) then the
+            longitude of such a vertex on the north (south) pole will
+            be the same as the longitude of the south (north) vertex
+            of the same cell. If set to a number, then the longitudes
+            of all vertices on the north or south pole will be given
+            the value *pole_longitude*.
 
     :Returns:
 

cf/healpix.py

@@ -199,30 +199,35 @@ def _healpix_increase_refinement_level(x, ncells, iaxis, quantity):
     """
     from dask.array.core import normalize_chunks
 
-    # Get the Dask array.
+    # Get the Dask array (e.g. dx.shape is (12, 19, 48))
     dx = x.data.to_dask_array(_force_mask_hardness=False)
 
     # Divide extensive data by the number of new cells
     if quantity == "extensive":
         dx = dx / ncells
 
     # Add a new size dimension just after the HEALPix dimension
+    # (e.g. .shape becomes (12, 19, 48, 1))
     new_axis = iaxis + 1
     dx = da.expand_dims(dx, new_axis)
 
-    # Work out what the chunks should be for the new dimension
+    # Modify the size of the new dimension to be the number of cells
+    # at the new refinement level which are contained in one cell at
+    # the original refinement level (e.g. size becomes 16)
     shape = list(dx.shape)
     shape[new_axis] = ncells
 
+    # Work out what the chunks should be for the new dimension
     chunks = list(dx.chunks)
     chunks[new_axis] = "auto"
     chunks = normalize_chunks(chunks, shape, dtype=dx.dtype)
 
-    # Broadcast the data along the new dimension
+    # Broadcast the data along the new dimension (e.g. dx.shape
+    # becomes (12, 19, 48, 16))
     dx = da.broadcast_to(dx, shape, chunks=chunks)
 
     # Reshape the array so that it has a single, larger HEALPix
-    # dimension
+    # dimension (e.g. dx.shape becomes (12, 19, 768))
     dx = dx.reshape(
         shape[:iaxis]
         + [shape[iaxis] * shape[new_axis]]
@@ -272,7 +277,7 @@ def _healpix_increase_refinement_level_indices(
     # Get any cached data values
     cached = healpix_index.data._get_cached_elements().copy()
 
-    # Get the Dask array
+    # Get the Dask array (e.g. dx.shape is (48,))
     dx = healpix_index.data.to_dask_array(_force_mask_hardness=False)
 
     # Set the data type to allow for the largest possible HEALPix
@@ -286,18 +291,23 @@ def _healpix_increase_refinement_level_indices(
     dx = dx * ncells
 
     # Add a new size dimension just after the HEALPix dimension
+    # (e.g. .shape becomes (48, 1))
     new_axis = 1
     dx = da.expand_dims(dx, new_axis)
 
-    # Work out what the chunks should be for the new dimension
+    # Modify the size of the new dimension to be the number of cells
+    # at the new refinement level which are contained in one cell at
+    # the original refinement level (e.g. size becomes 16)
     shape = list(dx.shape)
     shape[new_axis] = ncells
 
+    # Work out what the chunks should be for the new dimension
     chunks = list(dx.chunks)
     chunks[new_axis] = "auto"
     chunks = normalize_chunks(chunks, shape, dtype=dx.dtype)
 
-    # Broadcast the data along the new dimension
+    # Broadcast the data along the new dimension (e.g. dx.shape
+    # becomes (48, 16))
     dx = da.broadcast_to(dx, shape, chunks=chunks)
 
     # Increment the broadcast values along the new dimension, so that
@@ -306,10 +316,12 @@ def _healpix_increase_refinement_level_indices(
     # original refinement level.
     new_shape = [1] * dx.ndim
     new_shape[new_axis] = shape[new_axis]
+
     dx += da.arange(ncells, chunks=chunks[new_axis]).reshape(new_shape)
 
     # Reshape the new array to combine the original HEALPix and
     # broadcast dimensions into a single new HEALPix dimension
+    # (e.g. dx.shape becomes (768,))
     dx = dx.reshape(shape[0] * shape[new_axis])
 
     healpix_index.set_data(dx, copy=False)
@@ -324,8 +336,6 @@ def _healpix_increase_refinement_level_indices(
         x = np.array(cached[-1], dtype=dtype) * ncells + (ncells - 1)
         data._set_cached_elements({-1: x})
 
-    return
-
 
 def _healpix_indexing_scheme(healpix_index, hp, new_indexing_scheme):
     """Change the indexing scheme of HEALPix indices in-place.

cf/mixin/fielddomain.py

@@ -2268,6 +2268,7 @@ def healpix_to_ugrid(self, inplace=False):
             two_d=False, pole_longitude=0, inplace=True
         )
 
+        # Get the lat/lon coordinates
         x_key, x = f.auxiliary_coordinate(
             "Y",
             filter_by_axis=(axis,),
@@ -2308,8 +2309,9 @@ def healpix_to_ugrid(self, inplace=False):
                 "coordinate bounds"
             )
 
-        # Create the Domain Topology construct, by creating a unique
-        # integer identifer for each node location.
+        # Create the UGRID Domain Topology construct, by creating an
+        # arbitrary unique integer identifer for each unique node
+        # location.
         bounds_y = bounds_y.data.to_dask_array(_force_mask_hardness=False)
         bounds_x = bounds_x.data.to_dask_array(_force_mask_hardness=False)
 
@@ -2374,12 +2376,15 @@ def create_latlon_coordinates(
                 attempt this.
 
             pole_longitude: `None` or number
-                The longitude of coordinates, or coordinate bounds,
-                that lie exactly on the north or south pole. If `None`
-                (the default) then the longitudes of such points will
-                vary according to the algorithm being used to create
-                them. If set to a number, then the longitudes of such
-                points will all be given that value.
+                Define the longitudes of coordinates or coordinate
+                bounds that lie exactly on the north or south pole. If
+                `None` (the default) then the longitudes of such
+                points are determined by whatever algorithm was used
+                to create the coordinates, which will likely result in
+                different points on a pole having different
+                longitudes. If set to a number, then the longitudes of
+                all points on the north or south pole will be given
+                the value *pole_longitude*.
 
             overwrite: `bool`, optional
                 If True then remove any existing latitude and

cf/test/test_Field.py

@@ -3173,7 +3173,7 @@ def test_Field_healpix_to_ugrid(self):
         self.assertEqual(len(u.domain_topologies()), 1)
         self.assertEqual(len(u.auxiliary_coordinates()), 2)
 
-        topology = u.domain_topology().normalise().array
+        topology = u.domain_topology().normalise()
         self.assertEqual(np.unique(topology).size, 53)
         self.assertTrue(
             np.array_equal(
@@ -3434,9 +3434,8 @@ def test_Field_healpix_increase_refinement_level(self):
             self.assertEqual(
                 g.coordinate("healpix_index").data._get_cached_elements(), {}
             )
-            _ = str(
-                f.coordinate("healpix_index").data
-            )  # Create cached elements
+            # Create cached elements
+            _ = str(f.coordinate("healpix_index").data)
             g = f.healpix_increase_refinement_level(16, "intensive")
             self.assertEqual(
                 g.coordinate("healpix_index").data._get_cached_elements(),