Make make_gridcube() dataless, and improve documentation cross-refs.

Author: pp-mo

docs/src/further_topics/dataless_cubes.rst

@@ -38,6 +38,12 @@ Data assignment
 You can make an existing cube dataless, by setting ``cube.data = None``.
 The data array is simply discarded.
 
+Likewise, you can add data by assigning any data array of the correct shape, which
+turns it into a 'normal' cube.
+
+Note that ``cube.dtype`` always matches ``cube.data.dtype``.  A dataless cube has a
+dtype of ``None``.
+
 
 Cube copy
 ---------

docs/src/further_topics/netcdf_io.rst

@@ -190,8 +190,8 @@ TBC
 
 .. _save_load_dataless:
 
-Dataless Cubes
---------------
+Dataless Cubes in NetCDF files
+------------------------------
 It now possible to have "dataless" cubes, where ``cube.data is None``.
 When these are saved to a NetCDF file interface, this results in a netcdf file variable
 with all-unwritten data (meaning that it takes up no storage space).

docs/src/whatsnew/latest.rst

@@ -30,8 +30,8 @@ This document explains the changes made to Iris for this release
 ✨ Features
 ===========
 
-#. `@pp-mo`_ added a new utility function for making a test cube with a specified 2D
-   horizontal grid.
+#. `@pp-mo`_ added the :func:`~iris.util.make_gridcube` utility function, for making a
+   dataless test-cube with a specified 2D horizontal grid.
    (:issue:`5770`, :pull:`6581`)
 
 #. `@bjlittle`_ extended ``zlib`` compression of :class:`~iris.cube.Cube` data

lib/iris/fileformats/pp.py

@@ -54,7 +54,7 @@
     "save_pairs_from_cube",
 ]
 
-
+#: Standard spherical earth radius, as defined for MetOffice Unified Model.
 EARTH_RADIUS = 6371229.0
 
 

lib/iris/tests/unit/util/test_make_gridcube.py

@@ -28,6 +28,8 @@ def test_default(self):
         assert cube.standard_name is None
         assert cube.long_name == "grid_cube"
         assert cube.coord_system() == _GLOBE
+        assert cube.is_dataless()
+        assert cube.shape == (20, 30)
 
         assert len(cube.coords()) == 2
         co_x, co_y = [cube.coord(axis=ax) for ax in "xy"]
@@ -46,10 +48,6 @@ def test_default(self):
         assert np.all(co_y.points == np.linspace(-90.0, 90.0, 20))
         assert co_y.points.dtype == np.dtype("f8")
 
-        assert cube.has_lazy_data()
-        assert cube.shape == (20, 30)
-        assert np.all(cube.data == 0)
-
     def test_regular_region(self):
         """Check use of n? and ?lims args."""
         cube = make_gridcube(xlims=(20, 30), nx=5, ylims=(10, 25), ny=4)

lib/iris/util.py

@@ -2625,6 +2625,9 @@ def make_gridcube(
     It has one-dimensional X and Y coordinates, in a specific coordinate system.
     Both can be given either regularly spaced or irregular points.
 
+    The cube is dataless, meaning that ``cube.data`` is ``None``, but data can easily be
+    assigned if required.  See :ref:`dataless-cubes`.
+
     Parameters
     ----------
     nx : int, optional
@@ -2654,7 +2657,7 @@ def make_gridcube(
     Returns
     -------
     cube: iris.cube.Cube
-        A cube with the specified grid, and all-zeroes (lazy) data.
+        A cube with the specified grid, but no data.
 
     Warnings
     --------
@@ -2671,7 +2674,7 @@ def make_gridcube(
     # float32 zero, to force minimum 'f4' floating point precision
     zero_f4 = np.asarray(
         0.0,
-        dtype="f4",  # single precision (minimum), or what was passed
+        dtype="f4",
     )
 
     def dimco(
@@ -2759,7 +2762,8 @@ def dimco(
     xco = dimco("x", x_name, units, x_points, xlims, nx, coord_system=coord_system)
     yco = dimco("y", y_name, units, y_points, ylims, ny, coord_system=coord_system)
     cube = Cube(
-        da.zeros((yco.shape[0], xco.shape[0]), dtype=np.int8),
+        data=None,
+        shape=(yco.shape[0], xco.shape[0]),
         long_name="grid_cube",
         dim_coords_and_dims=((yco, 0), (xco, 1)),
     )