Introduction of aggregation datasets

Changelog.rst

@@ -1,10 +1,20 @@
+Version NEXTVERSION
+----------------
+
+**2025-??-??**
+
+* Introduction of reading and writing of aggregation datasets (for
+  CF-1.13) (https://github.com/NCAS-CMS/cfdm/issues/319
+
+----
+
 Version 1.11.2.0
 ----------------
 
 **2025-01-28**
 
 * Introduction of `dask` for all data manipulations
-  https://github.com/NCAS-CMS/cfdm/issues/317)
+  (https://github.com/NCAS-CMS/cfdm/issue/317)
 * Fix bug that returned incorrect results when an invalid identifer is
   provided to `cf.Field.cell_methods`
   (https://github.com/NCAS-CMS/cfdm/issues/299)
@@ -31,6 +41,7 @@ Version 1.11.2.0
 * New dependency: ``h5py>=3.10.0``
 * New dependency: ``s3fs>=2024.6.0``
 * New dependency: ``dask>=2024.6.0,<=2024.7.1``
+* New dependency: ``uritools>=4.0.3``
 * Removed dependency: ``netcdf_flattener``
 
 ----

cfdm/__init__.py

@@ -164,6 +164,7 @@
     atol,
     chunksize,
     configuration,
+    dirname,
     environment,
     integer_dtype,
     log_level,
@@ -195,10 +196,12 @@
 
 from .data import (
     Array,
+    AggregatedArray,
     BoundsFromNodesArray,
     CellConnectivityArray,
     CompressedArray,
     Data,
+    FullArray,
     GatheredArray,
     H5netcdfArray,
     NetCDFArray,

cfdm/cfdmimplementation.py

@@ -26,6 +26,7 @@
 )
 from .abstract import Implementation
 from .data import (
+    AggregatedArray,
     BoundsFromNodesArray,
     CellConnectivityArray,
     Data,
@@ -1346,19 +1347,27 @@ def get_field_data_axes(self, field):
         """
         return field.get_data_axes()
 
-    def get_filenames(self, parent):
+    def get_filenames(self, parent, normalise=True):
         """Return the name of the file or files containing the data.
 
         :Parameters:
 
             parent:
 
+            normalise: `bool`, optional
+                If True (the default) then normalise the filenames by
+                applying any text substitutions and reslving the name
+                to an absolute path. If False then neither of these is
+                carried out.
+
+                .. versionadded:: (cfdm) NEXTVERSION
+
         :Returns:
 
             `set`
 
         """
-        return parent.get_filenames()
+        return parent.get_filenames(normalise=normalise)
 
     def get_data_max(self, parent):
         """Use `get_data_maximum` instead (since cfdm version 1.8.0)."""
@@ -1726,7 +1735,10 @@ def get_data(self, parent, default=None):
         <Data(180, 2): [[0, ..., 359]] degrees_north>
 
         """
-        return parent.get_data(default=default)
+        try:
+            return parent.get_data(default=default)
+        except AttributeError:
+            return default
 
     def get_data_axes(self, parent, key, default=None):
         """Get domain axis identifiers.
@@ -1868,6 +1880,24 @@ def initialise_CellMethod(self, axes=None, method=None, qualifiers=None):
         cls = self.get_class("CellMethod")
         return cls(axes=axes, method=method, qualifiers=qualifiers)
 
+    def initialise_AggregatedArray(self, **kwargs):
+        """Return a `AggregatedArray` instance.
+
+        .. versionadded:: (cfdm) NEXTVERSION
+
+        :Parameters:
+
+            kwargs: optional
+                Initialisation parameters to pass to the new instance.
+
+        :Returns:
+
+            `AggregatedArray`
+
+        """
+        cls = self.get_class("AggregatedArray")
+        return cls(**kwargs)
+
     def initialise_CoordinateConversion(
         self, domain_ancillaries=None, parameters=None
     ):
@@ -3653,25 +3683,59 @@ def has_property(self, parent, prop):
         """
         return parent.has_property(prop)
 
-    def squeeze(self, construct, axes=None):
+    def squeeze(self, construct, axes=None, inplace=False):
         """Remove size 1 axes from construct data.
 
         :Parameters:
 
             construct:
+                The construct.
 
             axes: optional
+                The axes to squeeze. If `None` then all size 1 axes
+                are removed from the data.
+
+            inplace: `bool`, optional
+                If True then do the operation in-place and return
+                `None`.
+
+                .. versionadded:: (Cfdm) NEXTVERSION
+
+        :Returns:
+
+                The construct with removed axes, or `None` if the
+                operation was in-place.
+
+        """
+        return construct.squeeze(axes=axes, inplace=inplace)
+
+    def unsqueeze(self, field, inplace=False):
+        """Insert size 1 axes into the field data array.
+
+        .. versionadded:: (Cfdm) NEXTVERSION
+
+        :Parameters:
+
+            field: `Field`
+                The field construct.
+
+            inplace: `bool`, optional
+                If True then do the operation in-place and return
+                `None`.
 
         :Returns:
 
-                The construct with removed axes.
+            `Field` or `None`
+                The field with inserted axes, or `None` if the
+                operation was in-place.
 
         """
-        return construct.squeeze(axes=axes)
+        return field.unsqueeze(inplace=inplace)
 
 
 _implementation = CFDMImplementation(
     cf_version=CF(),
+    AggregatedArray=AggregatedArray,
     AuxiliaryCoordinate=AuxiliaryCoordinate,
     CellConnectivity=CellConnectivity,
     CellConnectivityArray=CellConnectivityArray,

cfdm/core/__init__.py

@@ -11,9 +11,9 @@
 
 """
 
-__date__ = "2025-01-28"
-__cf_version__ = "1.11"
-__version__ = "1.11.2.0"
+__date__ = "202?-??-??"
+__cf_version__ = "1.12"
+__version__ = "1.12.0.0"
 
 from packaging import __version__ as _packaging_ver
 from packaging import __file__ as _packaging_file

cfdm/data/__init__.py

@@ -15,9 +15,11 @@
 
 from .subarray.abstract import MeshSubarray, Subarray, SubsampledSubarray
 
+from .aggregatedarray import AggregatedArray
 from .boundsfromnodesarray import BoundsFromNodesArray
 from .cellconnectivityarray import CellConnectivityArray
 from .gatheredarray import GatheredArray
+from .fullarray import FullArray
 from .h5netcdfarray import H5netcdfArray
 from .netcdfarray import NetCDFArray
 from .netcdf4array import NetCDF4Array

cfdm/data/abstract/__init__.py

@@ -1,4 +1,5 @@
 from .array import Array
 from .compressedarray import CompressedArray
+from .filearray import FileArray
 from .mesharray import MeshArray
 from .raggedarray import RaggedArray

cfdm/data/abstract/compressedarray.py

@@ -338,7 +338,10 @@ def compressed_array(self):
         if ca is None:
             raise ValueError("There is no underlying compressed array")
 
-        return ca.array
+        try:
+            return ca.array
+        except AttributeError:
+            return ca
 
     def get_compressed_axes(self):
         """Return axes that are compressed in the underlying array.
@@ -439,27 +442,45 @@ def conformed_data(self):
         """
         return {"data": self.source().copy()}
 
-    def get_filenames(self):
-        """Return the names of any files containing the compressed data.
+    def get_filename(self, normalise=False, default=AttributeError()):
+        """Return the name of the file containing the compressed data.
 
         .. versionadded:: (cfdm) 1.10.0.2
 
+        :Parameters:
+
+            {{normalise: `bool`, optional}}
+
+                .. versionadded:: (cfdm) NEXTVERSION
+
+            default: optional
+                Return the value of the *default* parameter if there
+                is no file name.
+
+                {{default Exception}}
+
+                .. versionadded:: (cfdm) NEXTVERSION
+
         :Returns:
 
-            `set`
-                The file names in normalised, absolute form. If the
-                data are all in memory then an empty `set` is
-                returned.
+            `str`
+                The file name.
 
         """
         data = self._get_compressed_Array(None)
         if data is None:
             return set()
 
-        try:
-            return data.get_filenames()
-        except AttributeError:
-            return set()
+        filenames = data.get_filenames(normalise=normalise)
+        if len(filenames) != 1:
+            if default is None:
+                return
+
+            return self._default(
+                default, f"{self.__class__.__name__} has no unique file name"
+            )
+
+        return filenames[0]
 
     def get_Subarray(self):
         """Return the Subarray class.