Expand documentation.

Author: pp-mo

docs/src/further_topics/dataless_cubes.rst

@@ -0,0 +1,106 @@
+.. _dataless-cubes:
+
+==============
+Dataless Cubes
+==============
+It is possible for a cube to exist without a data payload.
+In this case ``cube.data`` is ``None``, instead of containing an array (real or lazy) as
+usual.
+
+This can be useful when the cube is used purely as a placeholder for metadata, e.g. to
+represent a combination of coordinates.
+
+Most notably, dataless cubes can be used as the target "grid cube" for most regridding
+schemes, since in that case the cube's coordinates are all that the method uses.
+See also :meth:`iris.util.make_gridcube`.
+
+
+Properties of dataless cubes
+----------------------------
+
+* ``cube.shape`` is unchanged
+* ``cube.data`` == ``None``
+* ``cube.dtype`` == ``None``
+* ``cube.core_data()`` == ``cube.lazy_data()`` == ``None``
+* ``cube.is_dataless()`` == ``True``
+* ``cube.has_lazy_data()`` == ``False``
+
+
+Cube creation
+-------------
+You can create a dataless cube with the :meth:`~iris.cube.Cube` constructor
+(i.e. ``__init__`` call), by specifying the ``shape`` keyword in place of ``data``.
+If both are specified, an error is raised (even if data and shape are compatible).
+
+
+Data assignment
+---------------
+You can make an existing cube dataless, by setting ``cube.data = None``.
+The data array is simply discarded.
+
+
+Cube copy
+---------
+The syntax that allows you to replace data on copying,
+e.g. ``cube2 = cube.copy(new_data)``, has now extended to accept the special value
+:data:`iris.DATALESS`.
+
+So, ``cube2 = cube.copy(iris.DATALESS)`` makes ``cube2`` a
+dataless copy of ``cube``.
+This is equivalent to ``cube2 = cube.copy(); cube2.data = None``.
+
+
+Save and Load
+-------------
+The netcdf file interface can save and re-load dataless cubes correctly.
+See : :ref:`netcdf_dataless`.
+
+
+.. _dataless_merge:
+
+Merging
+-------
+Merging is fully supported for dataless cubes, including combining them with "normal"
+cubes.
+
+* in all cases, the result has the same shape and metadata as if the same cubes had
+  data.
+* Merging multiple dataless cubes produces a dataless result.
+* Merging dataless and non-dataless cubes results in a partially 'missing' data array,
+  i.e. the relevant sections are filled with masked data.
+* Laziness is also preserved.
+
+
+Operations NOT supported
+-------------------------
+Dataless cubes are relatively new, and only partly integrated with Iris cube operations
+generally.
+
+The following are some of the notable features which do *not* support dataless cubes,
+at least as yet :
+
+* plotting
+
+* cube arithmetic
+
+* statistics
+
+* concatenation
+
+* :meth:`iris.cube.CubeList.realise_data`
+
+* various :class:`~iris.cube.Cube` methods, including at least:
+
+  * :meth:`~iris.cube.Cube.convert_units`
+
+  * :meth:`~iris.cube.Cube.subset`
+
+  * :meth:`~iris.cube.Cube.intersection`
+
+  * :meth:`~iris.cube.Cube.slices`
+
+  * :meth:`~iris.cube.Cube.interpolate`
+
+  * :meth:`~iris.cube.Cube.regrid`
+    Note: in this case the target ``grid`` can be dataless, but not the source
+    (``self``) cube.

docs/src/further_topics/index.rst

@@ -15,6 +15,7 @@ Extra information on specific technical issues.
    lenient_maths
    um_files_loading
    missing_data_handling
+   dataless_cubes
    netcdf_io
    dask_best_practices/index
    ugrid/index

docs/src/whatsnew/latest.rst

@@ -40,6 +40,14 @@ This document explains the changes made to Iris for this release
    :func:`~iris.fileformats.netcdf.saver.save_mesh` also supports ``zlib``
    compression. (:issue:`6565`, :pull:`6728`)
 
+#. `@pp-mo`_ added the ability to merge dataless cubes.  This also means they can be
+   re-loaded normally with :meth:`iris.load`.  See: :ref:`dataless_merge`.
+   (:issue:`5770`, :pull:`6581`)
+
+#. `@pp-mo`_ added a documentation section on dataless cubes.
+   See: :ref:`dataless-cubes`.
+   (:issue:`XXX`, :pull:`XXX`)
+
 
 🐛 Bugs Fixed
 =============

lib/iris/tests/integration/merge/test_merge.py

@@ -53,8 +53,7 @@ def mangle_cubelist(cubelist, dataless_option):
             or dataless_option == "dataless_all"
         ):
             # Make this one dataless
-            cube = cube.copy()
-            cube.data = None
+            cube = cube.copy(iris.DATALESS)
 
         result.append(cube)