colorbar keyword for iris.quickplot routines (#6169)

* Added `colorbar` keyword to relevant quickplot plotting routines to
user to control automatic generation of a colorbar.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Set defaults for colorbar keyword

* Added new test case for pcolormesh, pcolor and contourf

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Added "Whats New" entry + added my GitHub unsername to common_links.inc

* Updated IRIS_TEST_DATA_VERSION in CI

* Added reminder comment in ci-tests.yml

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.github/workflows/benchmarks_run.yml

@@ -60,7 +60,7 @@ jobs:
     env:
       IRIS_TEST_DATA_LOC_PATH: benchmarks
       IRIS_TEST_DATA_PATH: benchmarks/iris-test-data
-      IRIS_TEST_DATA_VERSION: "2.26"
+      IRIS_TEST_DATA_VERSION: "2.28"
       # Lets us manually bump the cache to rebuild
       ENV_CACHE_BUILD: "0"
       TEST_DATA_CACHE_BUILD: "2"

.github/workflows/ci-tests.yml

@@ -50,7 +50,8 @@ jobs:
             session: "tests"
 
     env:
-      IRIS_TEST_DATA_VERSION: "2.26"
+      # NOTE: IRIS_TEST_DATA_VERSION is also set in benchmarks_run.yml
+      IRIS_TEST_DATA_VERSION: "2.28"
       ENV_NAME: "ci-tests"
 
     steps:

docs/src/common_links.inc

@@ -79,5 +79,6 @@
 .. _@stephenworsley: https://github.com/stephenworsley
 .. _@tkknight: https://github.com/tkknight
 .. _@trexfeathers: https://github.com/trexfeathers
+.. _@ukmo-ccbunney: https://github.com/ukmo-ccbunney
 .. _@wjbenfold: https://github.com/wjbenfold
 .. _@zklaus: https://github.com/zklaus

docs/src/whatsnew/latest.rst

@@ -34,6 +34,17 @@ This document explains the changes made to Iris for this release
    equality methods to :class:`iris.io.format_picker.FormatAgent`, as requested
    in :issue:`6108`, actioned in :pull:`6119`.
 
+#. `@ukmo-ccbunney`_ added ``colorbar`` keyword to allow optional creation of
+   the colorbar in the following quickplot methods:
+
+   * :meth:`iris.quickplot.contourf`
+
+   * :meth:`iris.quickplot.pcolor`
+
+   * :meth:`iris.quickplot.pcolormesh`
+
+   Requested in :issue:`5970`, actioned in :pull:`6169`.
+
 
 🐛 Bugs Fixed
 =============

lib/iris/quickplot.py

@@ -48,14 +48,15 @@ def _title(cube_or_coord, with_units):
     return title
 
 
-def _label(cube, mode, result=None, ndims=2, coords=None, axes=None):
+def _label(cube, mode, result=None, ndims=2, coords=None, axes=None, colorbar=True):
     """Put labels on the current plot using the given cube."""
     if axes is None:
         axes = plt.gca()
 
     axes.set_title(_title(cube, with_units=False))
 
-    if result is not None:
+    # optional colorbar
+    if colorbar and result is not None:
         draw_edges = mode == iris.coords.POINT_MODE
         bar = plt.colorbar(
             result, ax=axes, orientation="horizontal", drawedges=draw_edges
@@ -89,12 +90,16 @@ def _label(cube, mode, result=None, ndims=2, coords=None, axes=None):
         raise ValueError(msg)
 
 
-def _label_with_bounds(cube, result=None, ndims=2, coords=None, axes=None):
-    _label(cube, iris.coords.BOUND_MODE, result, ndims, coords, axes)
+def _label_with_bounds(
+    cube, result=None, ndims=2, coords=None, axes=None, colorbar=True
+):
+    _label(cube, iris.coords.BOUND_MODE, result, ndims, coords, axes, colorbar)
 
 
-def _label_with_points(cube, result=None, ndims=2, coords=None, axes=None):
-    _label(cube, iris.coords.POINT_MODE, result, ndims, coords, axes)
+def _label_with_points(
+    cube, result=None, ndims=2, coords=None, axes=None, colorbar=True
+):
+    _label(cube, iris.coords.POINT_MODE, result, ndims, coords, axes, colorbar)
 
 
 def _get_titles(u_object, v_object):
@@ -181,6 +186,11 @@ def contourf(cube, *args, **kwargs):
 
         contour(cube, V)
 
+    Keywords
+    --------
+    colorbar : bool, default=True
+        If True, an appropriate colorbar will be added to the plot.
+
     See :func:`iris.plot.contourf` for details of valid keyword arguments.
 
     Notes
@@ -190,8 +200,9 @@ def contourf(cube, *args, **kwargs):
     """
     coords = kwargs.get("coords")
     axes = kwargs.get("axes")
+    colorbar = kwargs.pop("colorbar", True)
     result = iplt.contourf(cube, *args, **kwargs)
-    _label_with_points(cube, result, coords=coords, axes=axes)
+    _label_with_points(cube, result, coords=coords, axes=axes, colorbar=colorbar)
     return result
 
 
@@ -229,6 +240,11 @@ def outline(cube, coords=None, color="k", linewidth=None, axes=None):
 def pcolor(cube, *args, **kwargs):
     """Draw a labelled pseudocolor plot based on the given Cube.
 
+    Keywords
+    --------
+    colorbar : bool, default=True
+        If True, an appropriate colorbar will be added to the plot.
+
     See :func:`iris.plot.pcolor` for details of valid keyword arguments.
 
     Notes
@@ -238,14 +254,20 @@ def pcolor(cube, *args, **kwargs):
     """
     coords = kwargs.get("coords")
     axes = kwargs.get("axes")
+    colorbar = kwargs.pop("colorbar", True)
     result = iplt.pcolor(cube, *args, **kwargs)
-    _label_with_bounds(cube, result, coords=coords, axes=axes)
+    _label_with_bounds(cube, result, coords=coords, axes=axes, colorbar=colorbar)
     return result
 
 
 def pcolormesh(cube, *args, **kwargs):
     """Draw a labelled pseudocolour plot based on the given Cube.
 
+    Keywords
+    --------
+    colorbar : bool, default=True
+        If True, an appropriate colorbar will be added to the plot.
+
     See :func:`iris.plot.pcolormesh` for details of valid keyword arguments.
 
     Notes
@@ -256,8 +278,9 @@ def pcolormesh(cube, *args, **kwargs):
     """
     coords = kwargs.get("coords")
     axes = kwargs.get("axes")
+    colorbar = kwargs.pop("colorbar", True)
     result = iplt.pcolormesh(cube, *args, **kwargs)
-    _label_with_bounds(cube, result, coords=coords, axes=axes)
+    _label_with_bounds(cube, result, coords=coords, axes=axes, colorbar=colorbar)
     return result
 
 

lib/iris/tests/results/imagerepo.json

@@ -212,10 +212,13 @@
     "iris.tests.test_quickplot.TestLabels.test_contourf.1": "bf802f85c17fc17fc07eb42ac17f3f929130c06e3f80c07f7aa02e85c07f3e81",
     "iris.tests.test_quickplot.TestLabels.test_contourf.2": "be816a95907ae508c17e955ac07f3fa0945bc07f3f80c07f3aa36f01c0ff3f80",
     "iris.tests.test_quickplot.TestLabels.test_contourf_nameless.0": "be816af5907ee508c17e955ac03f3f809419c07f3f80c07f3a8b6f81c0ff3f80",
+    "iris.tests.test_quickplot.TestLabels.test_contourf_no_colorbar.0": "bf80c391c17fe07ec07e1d1a917e3f42917879224834487c6e24ca3e2f87c2ff",
     "iris.tests.test_quickplot.TestLabels.test_map.0": "e85a634c86a597a793c9349b94b79969c396c95bcce69a64d938c9b039a58ca6",
     "iris.tests.test_quickplot.TestLabels.test_map.1": "e85a636c86a597a793c9349b94b69969c396c95bcce69a64d938c9b039a58ca6",
     "iris.tests.test_quickplot.TestLabels.test_pcolor.0": "eea16affc05ab500956e974ac53f3d80925ac03f2f81c07e3fa12da1c2fe3f80",
+    "iris.tests.test_quickplot.TestLabels.test_pcolor_no_colorbar.0": "eea1c2dac51ab54a905e2d20905a6da5d05e6da19d60dade6da1dade6da1d2d8",
     "iris.tests.test_quickplot.TestLabels.test_pcolormesh.0": "eea16affc05ab500956e974ac53f3d80925ac03f2f81c07e3fa12da1c2fe3f80",
+    "iris.tests.test_quickplot.TestLabels.test_pcolormesh_no_colorbar.0": "eea1c2dac51ab54a905e2d20905a6da1d05e6da19d60dade6da1dade6da1d2dc",
     "iris.tests.test_quickplot.TestLabels.test_pcolormesh_str_symbol.0": "eea16affc05ab500956e974ac53f3d80925ac03f3f80c07e3fa12d21c2ff3f80",
     "iris.tests.test_quickplot.TestPlotHist.test_horizontal.0": "b59cc3dadb433c24c4f166039438793591a7dbdcbcdc9ccc68c697a91b139131",
     "iris.tests.test_quickplot.TestPlotHist.test_vertical.0": "bf80c7c6c07d7959647e343a33364b699589c6c64ec0312b9e227ad681ffcc68",

lib/iris/tests/test_quickplot.py

@@ -174,10 +174,22 @@ def test_contourf_nameless(self):
         qplt.contourf(cube, coords=["grid_longitude", "model_level_number"])
         self.check_graphic()
 
+    def test_contourf_no_colorbar(self):
+        qplt.contourf(
+            self._small(),
+            colorbar=False,
+            coords=["model_level_number", "grid_longitude"],
+        )
+        self.check_graphic()
+
     def test_pcolor(self):
         qplt.pcolor(self._small())
         self.check_graphic()
 
+    def test_pcolor_no_colorbar(self):
+        qplt.pcolor(self._small(), colorbar=False)
+        self.check_graphic()
+
     def test_pcolormesh(self):
         qplt.pcolormesh(self._small())
 
@@ -193,6 +205,10 @@ def test_pcolormesh_str_symbol(self):
 
         self.check_graphic()
 
+    def test_pcolormesh_no_colorbar(self):
+        qplt.pcolormesh(self._small(), colorbar=False)
+        self.check_graphic()
+
     def test_map(self):
         cube = self._slice(["grid_latitude", "grid_longitude"])
         qplt.contour(cube)