Merge pull request #1819 from dkillick/collapse_2d_coord_note

DOC: Note about collapsing multi-dimensional coordinates
SciTools · Nov 23, 2015 · 66a8fa9 · 66a8fa9
2 parents 5950ab0 + 53a6795
commit 66a8fa9
Show file tree

Hide file tree

Showing 3 changed files with 24 additions and 1 deletion.
diff --git a/docs/iris/src/userguide/cube_statistics.rst b/docs/iris/src/userguide/cube_statistics.rst
@@ -97,6 +97,9 @@ For an example of using this functionality, the
 in the gallery takes a zonal mean of an ``XYT`` cube by using the
 ``collapsed`` method with ``latitude`` and ``iris.analysis.MEAN`` as arguments.
 
+You cannot partially collapse a multi-dimensional coordinate. See
+:ref:`cube.collapsed <partially_collapse_multi-dim_coord>` for more
+information.
 
 .. _cube-statistics-collapsing-average:
 

diff --git a/lib/iris/coords.py b/lib/iris/coords.py
@@ -942,11 +942,16 @@ 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. See
+            :ref:`cube.collapsed <partially_collapse_multi-dim_coord>` for more
+            information.
+
         """
         if isinstance(dims_to_collapse, (int, np.integer)):
             dims_to_collapse = [dims_to_collapse]

diff --git a/lib/iris/cube.py b/lib/iris/cube.py
@@ -2960,6 +2960,21 @@ def collapsed(self, coords, aggregator, **kwargs):
                 cube.collapsed(['latitude', 'longitude'],
                                iris.analysis.VARIANCE)
 
+        .. _partially_collapse_multi-dim_coord:
+
+        .. note::
+            You cannot partially collapse a multi-dimensional coordinate. Doing
+            so would result in a partial collapse of the multi-dimensional
+            coordinate. Instead you must either:
+                 * collapse in a single operation all cube axes that the
+                   multi-dimensional coordinate spans,
+                 * remove the multi-dimensional coordinate from the cube before
+                   performing the collapse operation, or
+                 * not collapse the coordinate at all.
+
+            Multi-dimensional derived coordinates will not prevent a successful
+            collapse operation.
+
         """
         # Convert any coordinate names to coordinates
         coords = self._as_list_of_coords(coords)