Implement dataless cubes

lib/iris/__init__.py

@@ -143,7 +143,12 @@ def callback(cube, field, filename):
 class Future(threading.local):
     """Run-time configuration controller."""
 
-    def __init__(self, datum_support=False, pandas_ndim=False, save_split_attrs=False):
+    def __init__(
+        self,
+        datum_support=False,
+        pandas_ndim=False,
+        save_split_attrs=False,
+    ):
         """Container for run-time options controls.
 
         To adjust the values simply update the relevant attribute from
@@ -189,7 +194,11 @@ def __repr__(self):
         # msg = ('Future(example_future_flag={})')
         # return msg.format(self.example_future_flag)
         msg = "Future(datum_support={}, pandas_ndim={}, save_split_attrs={})"
-        return msg.format(self.datum_support, self.pandas_ndim, self.save_split_attrs)
+        return msg.format(
+            self.datum_support,
+            self.pandas_ndim,
+            self.save_split_attrs,
+        )
 
     # deprecated_options = {'example_future_flag': 'warning',}
     deprecated_options: dict[str, Literal["error", "warning"]] = {}
@@ -832,3 +841,7 @@ def use_plugin(plugin_name):
     significance of the import statement and warn that it is an unused import.
     """
     importlib.import_module(f"iris.plugins.{plugin_name}")
+
+
+# To be used when copying a cube to make the new cube dataless.
+DATALESS = "NONE"

lib/iris/_data_manager.py

@@ -10,32 +10,42 @@
 import numpy.ma as ma
 
 from iris._lazy_data import as_concrete_data, as_lazy_data, is_lazy_data
+import iris.exceptions
+import iris.warnings
 
 
 class DataManager:
     """Provides a well defined API for management of real or lazy data."""
 
-    def __init__(self, data):
+    def __init__(self, data, shape=None):
         """Create a data manager for the specified data.
 
         Parameters
         ----------
         data :
             The :class:`~numpy.ndarray` or :class:`~numpy.ma.core.MaskedArray`
             real data, or :class:`~dask.array.core.Array` lazy data to be
-            managed.
+            managed. If a value of None is given, the data manager will be
+            considered dataless.
+
+        shape :
+            A tuple, representing the shape of the data manager. This can only
+            be used in the case of `data=None`, and will render the data manager
+            dataless.
 
         """
+        if (shape is not None) and (data is not None):
+            msg = "`shape` should only be provided if `data is None`"
+            raise ValueError(msg)
+
         # Initialise the instance.
         self._lazy_array = None
         self._real_array = None
 
         # Assign the data payload to be managed.
+        self._shape = shape
         self.data = data
 
-        # Enforce the manager contract.
-        self._assert_axioms()
-
     def __copy__(self):
         """Forbid :class:`~iris._data_manager.DataManager` instance shallow-copy support."""
         name = type(self).__name__
@@ -126,11 +136,16 @@ def __repr__(self):
     def _assert_axioms(self):
         """Definition of the manager state, that should never be violated."""
         # Ensure there is a valid data state.
-        is_lazy = self._lazy_array is not None
-        is_real = self._real_array is not None
-        emsg = "Unexpected data state, got {}lazy and {}real data."
-        state = is_lazy ^ is_real
-        assert state, emsg.format("" if is_lazy else "no ", "" if is_real else "no ")
+        empty = self._lazy_array is None and self._real_array is None
+        overfilled = self._lazy_array is not None and self._real_array is not None
+        if overfilled:
+            msg = "Unexpected data state, got both lazy and real data."
+            raise ValueError(msg)
+        elif (
+            empty and self._shape is None
+        ):  # if I remove the second check, allows empty arrays, like old behaviour
+            msg = "Unexpected data state, got no lazy or real data, and no shape."
+            raise ValueError(msg)
 
     def _deepcopy(self, memo, data=None):
         """Perform a deepcopy of the :class:`~iris._data_manager.DataManager` instance.
@@ -148,25 +163,30 @@ def _deepcopy(self, memo, data=None):
         :class:`~iris._data_manager.DataManager` instance.
 
         """
+        shape = None
         try:
             if data is None:
                 # Copy the managed data.
                 if self.has_lazy_data():
                     data = copy.deepcopy(self._lazy_array, memo)
-                else:
+                elif self._real_array is not None:
                     data = self._real_array.copy()
+                else:
+                    shape = self.shape
+            elif type(data) is str and data == iris.DATALESS:
+                shape = self.shape
+                data = None
             else:
                 # Check that the replacement data is valid relative to
                 # the currently managed data.
                 dm_check = DataManager(self.core_data())
                 dm_check.data = data
                 # If the replacement data is valid, then use it but
                 # without copying it.
-            result = DataManager(data)
+            result = DataManager(data=data, shape=shape)
         except ValueError as error:
             emsg = "Cannot copy {!r} - {}"
             raise ValueError(emsg.format(type(self).__name__, error))
-
         return result
 
     @property
@@ -219,15 +239,20 @@ def data(self, data):
             managed.
 
         """
+        # If data is None, ensure previous shape is maintained, and that it is
+        # not wrapped in an np.array
+        dataless = data is None
+        if dataless:
+            self._shape = self.shape
+
         # Ensure we have numpy-like data.
-        if not (hasattr(data, "shape") and hasattr(data, "dtype")):
+        elif not (hasattr(data, "shape") and hasattr(data, "dtype")):
             data = np.asanyarray(data)
 
-        # Determine whether the class instance has been created,
-        # as this method is called from within the __init__.
-        init_done = self._lazy_array is not None or self._real_array is not None
-
-        if init_done and self.shape != data.shape:
+        # Determine whether the class already has a defined shape,
+        # as this method is called from __init__.
+        has_shape = self.shape is not None
+        if has_shape and not dataless and self.shape != data.shape:
             # The _ONLY_ data reshape permitted is converting a 0-dimensional
             # array i.e. self.shape == () into a 1-dimensional array of length
             # one i.e. data.shape == (1,)
@@ -242,7 +267,8 @@ def data(self, data):
         else:
             if not ma.isMaskedArray(data):
                 # Coerce input data to ndarray (including ndarray subclasses).
-                data = np.asarray(data)
+                if not dataless:
+                    data = np.asarray(data)
             if isinstance(data, ma.core.MaskedConstant):
                 # Promote to a masked array so that the fill-value is
                 # writeable to the data owner.
@@ -261,12 +287,19 @@ def dtype(self):
     @property
     def ndim(self):
         """The number of dimensions covered by the data being managed."""
-        return self.core_data().ndim
+        return len(self.shape)
 
     @property
     def shape(self):
         """The shape of the data being managed."""
-        return self.core_data().shape
+        if self.core_data() is None:
+            result = self._shape
+        else:
+            result = self.core_data().shape
+        return result
+
+    def is_dataless(self):
+        return (self.core_data() is None) and (self.shape is not None)
 
     def copy(self, data=None):
         """Return a deep copy of this :class:`~iris._data_manager.DataManager` instance.

lib/iris/cube.py

@@ -174,6 +174,8 @@ def _assert_is_cube(obj):
         if not hasattr(obj, "add_aux_coord"):
             msg = r"Object {obj} cannot be put in a cubelist, as it is not a Cube."
             raise ValueError(msg)
+        elif obj.is_dataless():
+            raise iris.exceptions.DatalessError("CubeList")
 
     def _repr_html_(self):
         from iris.experimental.representation import CubeListRepresentation
@@ -1190,7 +1192,7 @@ def _walk_nodes(node):
 
     def __init__(
         self,
-        data: np.typing.ArrayLike,
+        data: np.typing.ArrayLike | None = None,
         standard_name: str | None = None,
         long_name: str | None = None,
         var_name: str | None = None,
@@ -1204,6 +1206,7 @@ def __init__(
         cell_measures_and_dims: Iterable[tuple[CellMeasure, int]] | None = None,
         ancillary_variables_and_dims: Iterable[tuple[AncillaryVariable, int]]
         | None = None,
+        shape: tuple | None = None,
     ):
         """Create a cube with data and optional metadata.
 
@@ -1250,6 +1253,9 @@ def __init__(
             A list of CellMeasures with dimension mappings.
         ancillary_variables_and_dims :
             A list of AncillaryVariables with dimension mappings.
+        shape :
+            An alternative to providing data, this defines the shape of the
+            cube, but initialises the cube as dataless.
 
         Examples
         --------
@@ -1276,7 +1282,7 @@ def __init__(
         self._metadata_manager = metadata_manager_factory(CubeMetadata)
 
         # Initialise the cube data manager.
-        self._data_manager = DataManager(data)
+        self._data_manager = DataManager(data, shape)
 
         #: The "standard name" for the Cube's phenomenon.
         self.standard_name = standard_name
@@ -1475,6 +1481,8 @@ def convert_units(self, unit: str | Unit) -> None:
 
         """
         # If the cube has units convert the data.
+        if self.is_dataless():
+            raise iris.exceptions.DatalessError("convert_units")
         if self.units.is_unknown():
             raise iris.exceptions.UnitConversionError(
                 "Cannot convert from unknown units. "
@@ -2883,6 +2891,16 @@ def has_lazy_data(self) -> bool:
         """
         return self._data_manager.has_lazy_data()
 
+    def is_dataless(self) -> bool:
+        """Detail whether this :class:`~iris.cube.Cube` is dataless.
+
+        Returns
+        -------
+        bool
+
+        """
+        return self._data_manager.is_dataless()
+
     @property
     def dim_coords(self) -> tuple[DimCoord, ...]:
         """Return a tuple of all the dimension coordinates, ordered by dimension.
@@ -3091,6 +3109,8 @@ def subset(self, coord: AuxCoord | DimCoord) -> Cube | None:
         whole cube is returned. As such, the operation is not strict.
 
         """
+        if self.is_dataless():
+            raise iris.exceptions.DatalessError("subset")
         if not isinstance(coord, iris.coords.Coord):
             raise ValueError("coord_to_extract must be a valid Coord.")
 
@@ -3212,6 +3232,8 @@ def intersection(self, *args, **kwargs) -> Cube:
             which intersects with the requested coordinate intervals.
 
         """
+        if self.is_dataless():
+            raise iris.exceptions.DatalessError("intersection")
         result = self
         ignore_bounds = kwargs.pop("ignore_bounds", False)
         threshold = kwargs.pop("threshold", 0)
@@ -3736,6 +3758,9 @@ def slices(
             dimension index.
 
         """  # noqa: D214, D406, D407, D410, D411
+        if self.is_dataless():
+            raise iris.exceptions.DatalessError("slices")
+
         if not isinstance(ordered, bool):
             raise TypeError("'ordered' argument to slices must be boolean.")
 
@@ -3823,7 +3848,8 @@ def transpose(self, new_order: list[int] | None = None) -> None:
 
         # Transpose the data payload.
         dm = self._data_manager
-        data = dm.core_data().transpose(new_order)
+        if not self.is_dataless():
+            data = dm.core_data().transpose(new_order)
         self._data_manager = DataManager(data)
 
         dim_mapping = {src: dest for dest, src in enumerate(new_order)}
@@ -4083,6 +4109,7 @@ def _deepcopy(self, memo, data=None):
             aux_coords_and_dims=new_aux_coords_and_dims,
             cell_measures_and_dims=new_cell_measures_and_dims,
             ancillary_variables_and_dims=new_ancillary_variables_and_dims,
+            shape=(dm.shape if dm.core_data() is None else None),
         )
 
         new_cube.metadata = deepcopy(self.metadata, memo)
@@ -4310,6 +4337,8 @@ def collapsed(
                 cube.collapsed(['latitude', 'longitude'],
                                iris.analysis.VARIANCE)
         """
+        if self.is_dataless():
+            raise iris.exceptions.DatalessError("collapsed")
         # Update weights kwargs (if necessary) to handle different types of
         # weights
         weights_info = None
@@ -4530,6 +4559,8 @@ def aggregated_by(
                     STASH                       m01s00i024
 
         """
+        if self.is_dataless():
+            raise iris.exceptions.DatalessError("aggregated_by")
         # Update weights kwargs (if necessary) to handle different types of
         # weights
         weights_info = None
@@ -4829,6 +4860,8 @@ def rolling_window(
         """  # noqa: D214, D406, D407, D410, D411
         # Update weights kwargs (if necessary) to handle different types of
         # weights
+        if self.is_dataless():
+            raise iris.exceptions.DatalessError("rolling_window")
         weights_info = None
         if kwargs.get("weights") is not None:
             weights_info = _Weights(kwargs["weights"], self)
@@ -5034,6 +5067,8 @@ def interpolate(
             True
 
         """
+        if self.is_dataless():
+            raise iris.exceptions.DatalessError("interoplate")
         coords, points = zip(*sample_points)
         interp = scheme.interpolator(self, coords)  # type: ignore[arg-type]
         return interp(points, collapse_scalar=collapse_scalar)
@@ -5079,6 +5114,8 @@ def regrid(self, grid: Cube, scheme: iris.analysis.RegriddingScheme) -> Cube:
             this function is not applicable.
 
         """
+        if self.is_dataless():
+            raise iris.exceptions.DatalessError("regrid")
         regridder = scheme.regridder(self, grid)
         return regridder(self)
 

lib/iris/exceptions.py

@@ -161,3 +161,14 @@ class CannotAddError(ValueError):
     """Raised when an object (e.g. coord) cannot be added to a :class:`~iris.cube.Cube`."""
 
     pass
+
+
+class DatalessError(ValueError):
+    """Raised when an method cannot be performed on a dataless :class:`~iris.cube.Cube`."""
+
+    def __str__(self):
+        msg = (
+            "Dataless cubes are still early in implementation, and dataless {} "
+            "operations are not currently supported."
+        )
+        return msg.format(super().__str__())