Removal of a cube's cell measure by name (#3081) (#3295)

Removal of a cube's cell measure by name (#3081)

docs/iris/src/whatsnew/contributions_2.3.0/newfeature_2019-Mar-08_remove_cell_measure_by_name.txt

@@ -0,0 +1,2 @@
+* :meth:`iris.cube.Cube.remove_cell_measure` now also allows removal of a cell
+measure by its name (previously only accepted a CellMeasure object).

lib/iris/cube.py

@@ -1135,13 +1135,30 @@ def remove_cell_measure(self, cell_measure):
 
         Args:
 
-        * cell_measure (CellMeasure)
-            The CellMeasure to remove from the cube.
+        * cell_measure (string or cell_measure)
+            The (name of the) cell measure to remove from the cube. As either
 
-        See also
-        :meth:`Cube.add_cell_measure()<iris.cube.Cube.add_cell_measure>`
+            (a) a :attr:`standard_name`, :attr:`long_name`, or
+            :attr:`var_name`. Defaults to value of `default`
+            (which itself defaults to `unknown`) as defined in
+            :class:`iris._cube_coord_common.CFVariableMixin`.
+
+            (b) a cell_measure instance with metadata equal to that of
+            the desired cell_measures.
+
+        .. note::
+
+            If the argument given does not represent a valid cell_measure on
+            the cube, an :class:`iris.exceptions.CellMeasureNotFoundError`
+            is raised.
+
+        .. seealso::
+
+            :meth:`Cube.add_cell_measure()<iris.cube.Cube.add_cell_measure>`
 
         """
+        cell_measure = self.cell_measure(cell_measure)
+
         self._cell_measures_and_dims = [[cell_measure_, dim] for cell_measure_,
                                         dim in self._cell_measures_and_dims
                                         if cell_measure_ is not cell_measure]

lib/iris/tests/unit/cube/test_Cube.py

@@ -1646,6 +1646,15 @@ def test_remove_cell_measure(self):
         self.assertEqual(self.cube._cell_measures_and_dims,
                          [[self.b_cell_measure, (0, 1)]])
 
+    def test_remove_cell_measure_by_name(self):
+        self.cube.remove_cell_measure('area')
+        self.assertEqual(self.cube._cell_measures_and_dims,
+                         [[self.b_cell_measure, (0, 1)]])
+
+    def test_fail_remove_cell_measure_by_name(self):
+        with self.assertRaises(CellMeasureNotFoundError):
+            self.cube.remove_cell_measure('notarea')
+
 
 class Test__getitem_CellMeasure(tests.IrisTest):
     def setUp(self):