From f1331b5977bb3c99518ff8f322f57b845b629dee Mon Sep 17 00:00:00 2001 From: Peter Killick Date: Wed, 28 Oct 2015 11:56:02 +0000 Subject: [PATCH 1/2] Multi-dimensional coordinate collapse note --- docs/iris/src/userguide/cube_statistics.rst | 16 ++++++++++++++++ lib/iris/coords.py | 12 +++++++++++- lib/iris/cube.py | 10 ++++++++++ 3 files changed, 37 insertions(+), 1 deletion(-) diff --git a/docs/iris/src/userguide/cube_statistics.rst b/docs/iris/src/userguide/cube_statistics.rst index f3ef6f3b8e..23aad89916 100644 --- a/docs/iris/src/userguide/cube_statistics.rst +++ b/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 diff --git a/lib/iris/coords.py b/lib/iris/coords.py index a1bab3888d..dbd9384a50 100644 --- a/lib/iris/coords.py +++ b/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] diff --git a/lib/iris/cube.py b/lib/iris/cube.py index 504a38ceda..579c122709 100644 --- a/lib/iris/cube.py +++ b/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) From 53a6795e152cbcac8d9d5bbf0df849b725385bc2 Mon Sep 17 00:00:00 2001 From: Peter Killick Date: Mon, 23 Nov 2015 09:51:51 +0000 Subject: [PATCH 2/2] Review actions: move new docs around. --- docs/iris/src/userguide/cube_statistics.rst | 19 +++---------------- lib/iris/coords.py | 11 +++-------- lib/iris/cube.py | 15 ++++++++++----- 3 files changed, 16 insertions(+), 29 deletions(-) diff --git a/docs/iris/src/userguide/cube_statistics.rst b/docs/iris/src/userguide/cube_statistics.rst index 23aad89916..df02b15429 100644 --- a/docs/iris/src/userguide/cube_statistics.rst +++ b/docs/iris/src/userguide/cube_statistics.rst @@ -97,22 +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. - -.. 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. +You cannot partially collapse a multi-dimensional coordinate. See +:ref:`cube.collapsed ` for more +information. .. _cube-statistics-collapsing-average: diff --git a/lib/iris/coords.py b/lib/iris/coords.py index dbd9384a50..88ed25cef0 100644 --- a/lib/iris/coords.py +++ b/lib/iris/coords.py @@ -949,14 +949,9 @@ def collapsed(self, dims_to_collapse=None): 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. + You cannot partially collapse a multi-dimensional coordinate. See + :ref:`cube.collapsed ` for more + information. """ if isinstance(dims_to_collapse, (int, np.integer)): diff --git a/lib/iris/cube.py b/lib/iris/cube.py index 579c122709..beed0bf3c9 100644 --- a/lib/iris/cube.py +++ b/lib/iris/cube.py @@ -2945,12 +2945,17 @@ 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. 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. + 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.