DOC: Note about collapsing multi-dimensional coordinates

docs/iris/src/userguide/cube_statistics.rst

@@ -98,6 +98,22 @@ in the gallery takes a zonal mean of an ``XYT`` cube by using the
 ``collapsed`` method with ``latitude`` and ``iris.analysis.MEAN`` as arguments.
 
 
+.. note::
+    You cannot partially collapse a multi-dimensional coordinate. Thus in the
+    above example you would not be able to collapse the cube along either of
+    the axes described by the ``grid_latitude`` or ``grid_longitude``
+    coordinates individually. Doing so would result in a partial collapse of
+    the 2D ``surface_altitude`` coordinate.
+
+    Instead you must either fully collapse the coordinate (in this case
+    requiring that both ``grid_latitude`` or ``grid_longitude`` coordinates be
+    collapsed together in a single collapse operation) or not collapse the
+    coordinate at all.
+
+    Multi-dimensional derived coordinates (such as ``altitude`` in the above
+    example) will not prevent a successful collapse operation across a
+    cube dimension that the multi-dimensional derived coordinate spans.
+
 .. _cube-statistics-collapsing-average:
 
 Area averaging

lib/iris/coords.py

@@ -943,11 +943,21 @@ def cell(self, index):
 
     def collapsed(self, dims_to_collapse=None):
         """
-        Returns a copy of this coordinate which has been collapsed along
+        Returns a copy of this coordinate, which has been collapsed along
         the specified dimensions.
 
         Replaces the points & bounds with a simple bounded region.
 
+        .. note::
+            You cannot partially collapse a multi-dimensional coordinate. To
+            successfully collapse a multi-dimensional coordinate (i.e. a
+            coordinate that describes more than one of a cube's axes) you
+            must collapse all cube axes that the multi-dimensional coordinate
+            spans in a single collapse operation.
+
+            Multi-dimensional derived coordinates will not prevent a successful
+            collapse operation.
+
         """
         if isinstance(dims_to_collapse, (int, np.integer)):
             dims_to_collapse = [dims_to_collapse]

lib/iris/cube.py

@@ -2945,6 +2945,16 @@ def collapsed(self, coords, aggregator, **kwargs):
                 cube.collapsed(['latitude', 'longitude'],
                                iris.analysis.VARIANCE)
 
+        .. note::
+            You cannot partially collapse a multi-dimensional coordinate. To
+            successfully collapse a multi-dimensional coordinate (i.e. a
+            coordinate that describes more than one of a cube's axes) you
+            must collapse all cube axes that the multi-dimensional coordinate
+            spans in a single collapse operation.
+
+            Multi-dimensional derived coordinates will not prevent a successful
+            collapse operation.
+
         """
         # Convert any coordinate names to coordinates
         coords = self._as_list_of_coords(coords)