Deprecate axes_grid1.colorbar.

See changelog note for rationale (looks like the mpl_toolkits colorbar
implementation was copy-pasted a while ago, and then did not get most of
the recent improvements to matplotlib's colorbar).

May be worth adding a property to the builtin colorbar similar to
mpl_toolkit's `cbar_axis` (pointing to whichever of `xaxis` or `yaxis`
is the long axis).

I don't think supporting overdrawing multiple colorbars on a single Axes
is really worth it.

Manual examination of axisartist/axes_grid1 examples that use colorbars
show no difference.

Author: anntzer

doc/api/next_api_changes/2018-02-10-AL.rst

@@ -0,0 +1,27 @@
+Deprecations
+````````````
+
+The ``mpl_toolkits.axes_grid1.colorbar`` module and its colorbar implementation
+are deprecated in favor of :mod:`matplotlib.colorbar`, as the former is
+essentially abandoned and the latter is a more featureful replacement with a
+nearly compatible API (for example, the following additional keywords are
+supported: ``panchor``, ``extendfrac``, ``extendrect``).
+
+The main differences are:
+
+- Setting the ticks on the colorbar is done by calling ``colorbar.set_ticks``
+  rather than ``colorbar.cbar_axis.set_xticks`` or
+  ``colorbar.cbar_axis.set_yticks``.
+- The colorbar's long axis is accessed with ``colorbar.xaxis`` or
+  ``colorbar.yaxis`` depending on the orientation, rather than
+  ``colorbar.cbar_axis``.
+- Overdrawing multiple colorbars on top of one another in a single Axes (e.g.
+  when using the ``cax`` attribute of `ImageGrid` elements) is not supported;
+  if you previously relied on the second colorbar being drawn over the first,
+  you can call ``cax.cla()`` to clear the axes before drawing the second
+  colorbar.
+
+During the deprecation period, the ``mpl_toolkits.legacy_colorbar``
+rcParam can be set to True to use ``mpl_toolkits.axes_grid1.colorbar`` in
+:mod:`mpl_toolkits.axes_grid1` code with a deprecation warning (the default),
+or to False to use ``matplotlib.colorbar``.

examples/axes_grid1/demo_axes_grid.py

@@ -5,10 +5,14 @@
 
 Grid of 2x2 images with single or own colorbar.
 """
+
 import matplotlib.pyplot as plt
 from mpl_toolkits.axes_grid1 import ImageGrid
 
 
+plt.rcParams["mpl_toolkits.legacy_colorbar"] = False
+
+
 def get_demo_image():
     import numpy as np
     from matplotlib.cbook import get_sample_data
@@ -108,8 +112,8 @@ def demo_grid_with_each_cbar_labelled(fig):
     for ax, cax, vlim in zip(grid, grid.cbar_axes, limits):
         im = ax.imshow(Z, extent=extent, interpolation="nearest",
                        vmin=vlim[0], vmax=vlim[1])
-        cax.colorbar(im)
-        cax.set_yticks((vlim[0], vlim[1]))
+        cb = cax.colorbar(im)
+        cb.set_ticks((vlim[0], vlim[1]))
 
     # This affects all axes because we set share_all = True.
     grid.axes_llc.set_xticks([-2, 0, 2])

examples/axes_grid1/demo_axes_grid2.py

@@ -5,13 +5,17 @@
 
 Grid of images with shared xaxis and yaxis.
 """
+
 import numpy as np
 
 import matplotlib.pyplot as plt
 from mpl_toolkits.axes_grid1 import ImageGrid
 import matplotlib.colors
 
 
+plt.rcParams["mpl_toolkits.legacy_colorbar"] = False
+
+
 def get_demo_image():
     from matplotlib.cbook import get_sample_data
     f = get_sample_data("axes_grid/bivariate_normal.npy", asfileobj=False)
@@ -53,10 +57,13 @@ def add_inner_title(ax, title, loc, **kwargs):
                  cbar_pad="1%",
                  )
 
-for ax, z in zip(grid, ZS):
+for i, (ax, z) in enumerate(zip(grid, ZS)):
     im = ax.imshow(
         z, origin="lower", extent=extent, interpolation="nearest")
-    ax.cax.colorbar(im)
+    cb = ax.cax.colorbar(im)
+    # Changing the colorbar ticks
+    if i in [1, 2]:
+        cb.set_ticks([-1, 0, 1])
 
 for ax, im_title in zip(grid, ["Image 1", "Image 2", "Image 3"]):
     t = add_inner_title(ax, im_title, loc='lower left')
@@ -69,10 +76,6 @@ def add_inner_title(ax, title, loc, **kwargs):
     #axis.label.set_size(10)
     #axis.major_ticklabels.set_size(6)
 
-# Changing the colorbar ticks
-grid[1].cax.set_xticks([-1, 0, 1])
-grid[2].cax.set_xticks([-1, 0, 1])
-
 grid[0].set_xticks([-2, 0])
 grid[0].set_yticks([-2, 0, 2])
 

examples/axes_grid1/demo_colorbar_of_inset_axes.py

@@ -7,7 +7,6 @@
 import matplotlib.pyplot as plt
 
 from mpl_toolkits.axes_grid1.inset_locator import inset_axes, zoomed_inset_axes
-from mpl_toolkits.axes_grid1.colorbar import colorbar
 
 
 def get_demo_image():
@@ -46,6 +45,6 @@ def get_demo_image():
                  borderpad=0,
                  )
 
-colorbar(im, cax=cax)
+fig.colorbar(im, cax=cax)
 
 plt.show()

examples/axes_grid1/demo_colorbar_with_axes_divider.py

@@ -13,7 +13,6 @@
 
 import matplotlib.pyplot as plt
 from mpl_toolkits.axes_grid1.axes_divider import make_axes_locatable
-from mpl_toolkits.axes_grid1.colorbar import colorbar
 
 fig, (ax1, ax2) = plt.subplots(1, 2)
 fig.subplots_adjust(wspace=0.5)
@@ -22,13 +21,13 @@
 ax1_divider = make_axes_locatable(ax1)
 # add an axes to the right of the main axes.
 cax1 = ax1_divider.append_axes("right", size="7%", pad="2%")
-cb1 = colorbar(im1, cax=cax1)
+cb1 = fig.colorbar(im1, cax=cax1)
 
 im2 = ax2.imshow([[1, 2], [3, 4]])
 ax2_divider = make_axes_locatable(ax2)
 # add an axes above the main axes.
 cax2 = ax2_divider.append_axes("top", size="7%", pad="2%")
-cb2 = colorbar(im2, cax=cax2, orientation="horizontal")
+cb2 = fig.colorbar(im2, cax=cax2, orientation="horizontal")
 # change tick position to top. Tick position defaults to bottom and overlaps
 # the image.
 cax2.xaxis.set_ticks_position("top")

examples/axes_grid1/simple_colorbar.py

@@ -17,3 +17,5 @@
 cax = divider.append_axes("right", size="5%", pad=0.05)
 
 plt.colorbar(im, cax=cax)
+
+plt.show()

lib/matplotlib/rcsetup.py

@@ -1426,6 +1426,8 @@ def _validate_linestyle(ls):
      # Additional arguments for convert movie writer (using pipes)
     'animation.convert_args':  [[], validate_stringlist],
 
+    'mpl_toolkits.legacy_colorbar': [True, validate_bool],
+
     # Classic (pre 2.0) compatibility mode
     # This is used for things that are hard to make backward compatible
     # with a sane rcParam alone.  This does *not* turn on classic mode

lib/mpl_toolkits/axes_grid1/axes_grid.py

@@ -1,11 +1,12 @@
 from numbers import Number
 
+import matplotlib as mpl
+from matplotlib import cbook
 import matplotlib.axes as maxes
 import matplotlib.ticker as ticker
 from matplotlib.gridspec import SubplotSpec
 
 from .axes_divider import Size, SubplotDivider, Divider
-from .colorbar import Colorbar
 from .mpl_axes import Axes
 
 
@@ -47,6 +48,16 @@ def colorbar(self, mappable, *, locator=None, **kwargs):
         else:
             orientation = "vertical"
 
+        if mpl.rcParams["mpl_toolkits.legacy_colorbar"]:
+            cbook.warn_deprecated(
+                "3.2", message="Since %(since)s, mpl_toolkits's own colorbar "
+                "implementation is deprecated; it will be removed "
+                "%(removal)s.  Set the 'mpl_toolkits.legacy_colorbar' rcParam "
+                "to False to use Matplotlib's default colorbar implementation "
+                "and suppress this deprecation warning.")
+            from .colorbar import Colorbar
+        else:
+            from matplotlib.colorbar import Colorbar
         cb = Colorbar(self, mappable, orientation=orientation, **kwargs)
         self._config_axes()
 
@@ -58,7 +69,10 @@ def on_changed(m):
         self.cbid = mappable.callbacksSM.connect('changed', on_changed)
         mappable.colorbar = cb
 
-        self.locator = cb.cbar_axis.get_major_locator()
+        if mpl.rcParams["mpl_toolkits.legacy_colorbar"]:
+            self.locator = cb.cbar_axis.get_major_locator()
+        else:
+            self.locator = cb.locator
 
         return cb
 

lib/mpl_toolkits/axes_grid1/colorbar.py

@@ -20,6 +20,7 @@
 
 import numpy as np
 import matplotlib as mpl
+from matplotlib import cbook
 import matplotlib.colors as colors
 import matplotlib.cm as cm
 from matplotlib import docstring
@@ -31,6 +32,10 @@
 from matplotlib.transforms import Bbox
 
 
+cbook.warn_deprecated(
+    "3.2", name="axes_grid1.colorbar", alternative="matplotlib.colorbar")
+
+
 make_axes_kw_doc = '''
 
     ============= ====================================================

lib/mpl_toolkits/tests/test_axes_grid.py

@@ -1,14 +1,22 @@
+from contextlib import ExitStack
 
-import matplotlib
-from matplotlib.testing.decorators import image_comparison
-from mpl_toolkits.axes_grid1 import ImageGrid
 import numpy as np
+import pytest
+
+import matplotlib as mpl
+from matplotlib.testing.decorators import image_comparison
 import matplotlib.pyplot as plt
+from mpl_toolkits.axes_grid1 import ImageGrid
 
 
-@image_comparison(['imagegrid_cbar_mode.png'], remove_text=True, style='mpl20')
-def test_imagegrid_cbar_mode_edge():
-    matplotlib.rcParams['image.interpolation'] = 'nearest'
+# The original version of this test relied on mpl_toolkits's slightly different
+# colorbar implementation; moving to matplotlib's own colorbar implementation
+# caused the small image comparison error.
+@pytest.mark.parametrize("legacy_colorbar", [False, True])
+@image_comparison(['imagegrid_cbar_mode.png'],
+                  remove_text=True, style='mpl20', tol=0.3)
+def test_imagegrid_cbar_mode_edge(legacy_colorbar):
+    mpl.rcParams["mpl_toolkits.legacy_colorbar"] = legacy_colorbar
 
     X, Y = np.meshgrid(np.linspace(0, 6, 30), np.linspace(0, 6, 30))
     arr = np.sin(X) * np.cos(Y) + 1j*(np.sin(3*Y) * np.cos(Y/2.))
@@ -19,9 +27,8 @@ def test_imagegrid_cbar_mode_edge():
     directions = ['row']*4 + ['column']*4
     cbar_locations = ['left', 'right', 'top', 'bottom']*2
 
-    for position, direction, location in zip(positions,
-                                             directions,
-                                             cbar_locations):
+    for position, direction, location in zip(
+            positions, directions, cbar_locations):
         grid = ImageGrid(fig, position,
                          nrows_ncols=(2, 2),
                          direction=direction,
@@ -30,14 +37,15 @@ def test_imagegrid_cbar_mode_edge():
                          cbar_mode='edge')
         ax1, ax2, ax3, ax4, = grid
 
-        im1 = ax1.imshow(arr.real, cmap='nipy_spectral')
-        im2 = ax2.imshow(arr.imag, cmap='hot')
-        im3 = ax3.imshow(np.abs(arr), cmap='jet')
-        im4 = ax4.imshow(np.arctan2(arr.imag, arr.real), cmap='hsv')
-
-        # Some of these colorbars will be overridden by later ones,
-        # depending on the direction and cbar_location
-        ax1.cax.colorbar(im1)
-        ax2.cax.colorbar(im2)
-        ax3.cax.colorbar(im3)
-        ax4.cax.colorbar(im4)
+        ax1.imshow(arr.real, cmap='nipy_spectral')
+        ax2.imshow(arr.imag, cmap='hot')
+        ax3.imshow(np.abs(arr), cmap='jet')
+        ax4.imshow(np.arctan2(arr.imag, arr.real), cmap='hsv')
+
+        with (pytest.warns(mpl.MatplotlibDeprecationWarning) if legacy_colorbar
+              else ExitStack()):
+            # In each row/column, the "first" colorbars must be overwritten by
+            # the "second" ones.  To achieve this, clear out the axes first.
+            for ax in grid:
+                ax.cax.cla()
+                ax.cax.colorbar(ax.images[0])