Doc: use empty ScalarMappable for colorbars with no associated image.

anntzer · anntzer · commit a49458706501 · 2019-12-29T22:58:42.000+01:00
This is consistent with the docstring of colorbar(), which explicitly
suggests this approach; this would also later allow deprecating
ColorbarBase, merging it into Colorbar.
diff --git a/examples/specialty_plots/leftventricle_bulleye.py b/examples/specialty_plots/leftventricle_bulleye.py
@@ -147,29 +147,18 @@ def bullseye_plot(ax, data, seg_bold=None, cmap=None, norm=None):
 # the colorbar will be used.
 cmap = mpl.cm.viridis
 norm = mpl.colors.Normalize(vmin=1, vmax=17)
-
-# ColorbarBase derives from ScalarMappable and puts a colorbar
-# in a specified axes, so it has everything needed for a
-# standalone colorbar.  There are many more kwargs, but the
-# following gives a basic continuous colorbar with ticks
-# and labels.
-cb1 = mpl.colorbar.ColorbarBase(axl, cmap=cmap, norm=norm,
-                                orientation='horizontal')
+# Create an empty ScalarMappable to set the colorbar's colormap and norm.
+# The following gives a basic continuous colorbar with ticks and labels.
+cb1 = fig.colorbar(mpl.cm.ScalarMappable(cmap=cmap, norm=norm),
+                   cax=axl, orientation='horizontal')
 cb1.set_label('Some Units')
 
 
-# Set the colormap and norm to correspond to the data for which
-# the colorbar will be used.
+# And again for the second colorbar.
 cmap2 = mpl.cm.cool
 norm2 = mpl.colors.Normalize(vmin=1, vmax=17)
-
-# ColorbarBase derives from ScalarMappable and puts a colorbar
-# in a specified axes, so it has everything needed for a
-# standalone colorbar.  There are many more kwargs, but the
-# following gives a basic continuous colorbar with ticks
-# and labels.
-cb2 = mpl.colorbar.ColorbarBase(axl2, cmap=cmap2, norm=norm2,
-                                orientation='horizontal')
+cb2 = fig.colorbar(mpl.cm.ScalarMappable(cmap=cmap2, norm=norm2),
+                   cax=axl2, orientation='horizontal')
 cb2.set_label('Some other units')
 
 
@@ -179,20 +168,19 @@ def bullseye_plot(ax, data, seg_bold=None, cmap=None, norm=None):
 cmap3 = mpl.colors.ListedColormap(['r', 'g', 'b', 'c'])
 cmap3.set_over('0.35')
 cmap3.set_under('0.75')
-
 # If a ListedColormap is used, the length of the bounds array must be
 # one greater than the length of the color list.  The bounds must be
 # monotonically increasing.
 bounds = [2, 3, 7, 9, 15]
 norm3 = mpl.colors.BoundaryNorm(bounds, cmap3.N)
-cb3 = mpl.colorbar.ColorbarBase(axl3, cmap=cmap3, norm=norm3,
-                                # to use 'extend', you must
-                                # specify two extra boundaries:
-                                boundaries=[0] + bounds + [18],
-                                extend='both',
-                                ticks=bounds,  # optional
-                                spacing='proportional',
-                                orientation='horizontal')
+cb3 = fig.colorbar(mpl.cm.ScalarMappable(cmap=cmap3, norm=norm3),
+                   cax=axl3,
+                   # to use 'extend', you must specify two extra boundaries:
+                   boundaries=[0] + bounds + [18],
+                   extend='both',
+                   ticks=bounds,  # optional
+                   spacing='proportional',
+                   orientation='horizontal')
 cb3.set_label('Discrete intervals, some other units')
 
 
diff --git a/tutorials/colors/colorbar_only.py b/tutorials/colors/colorbar_only.py
@@ -3,25 +3,27 @@
 Customized Colorbars Tutorial
 =============================
 
-This tutorial shows how to build colorbars without an attached plot.
+This tutorial shows how to build and customize standalone colorbars, i.e.
+without an attached plot.
 
 Customized Colorbars
 ====================
 
-`~matplotlib.colorbar.ColorbarBase` puts a colorbar in a specified axes,
-and can make a colorbar for a given colormap; it does not need a mappable
-object like an image. In this tutorial we will explore what can be done with
-standalone colorbar.
+A `~.Figure.colorbar` needs a "mappable" (`matplotlib.cm.ScalarMappable`)
+object (typically, an image) which indicates the colormap and the norm to be
+used.  In order to create a colorbar without an attached image, one can instead
+use a `.ScalarMappable` with no associated data.
 
 Basic continuous colorbar
 -------------------------
 
-Set the colormap and norm to correspond to the data for which the colorbar
-will be used. Then create the colorbar by calling
-:class:`~matplotlib.colorbar.ColorbarBase` and specify axis, colormap, norm
-and orientation as parameters. Here we create a basic continuous colorbar
-with ticks and labels. For more information see the
-:mod:`~matplotlib.colorbar` API.
+Here we create a basic continuous colorbar with ticks and labels.
+
+The arguments to the `~.Figure.colorbar` call are the `.ScalarMappable`
+(constructed using the *norm* and *cmap* arguments), the axes where the
+colorbar should be drawn, and the colorbar's orientation.
+
+For more information see the :mod:`~matplotlib.colorbar` API.
 """
 
 import matplotlib.pyplot as plt
@@ -33,11 +35,9 @@
 cmap = mpl.cm.cool
 norm = mpl.colors.Normalize(vmin=5, vmax=10)
 
-cb1 = mpl.colorbar.ColorbarBase(ax, cmap=cmap,
-                                norm=norm,
-                                orientation='horizontal')
+cb1 = fig.colorbar(mpl.cm.ScalarMappable(norm=norm, cmap=cmap),
+                   cax=ax, orientation='horizontal')
 cb1.set_label('Some Units')
-fig.show()
 
 ###############################################################################
 # Discrete intervals colorbar
@@ -56,7 +56,7 @@
 # bounds must be monotonically increasing.
 #
 # This time we pass some more arguments in addition to previous arguments to
-# :class:`~matplotlib.colorbar.ColorbarBase`. For the out-of-range values to
+# `~.Figure.colorbar`. For the out-of-range values to
 # display on the colorbar, we have to use the *extend* keyword argument. To use
 # *extend*, you must specify two extra boundaries. Finally spacing argument
 # ensures that intervals are shown on colorbar proportionally.
@@ -70,15 +70,15 @@
 
 bounds = [1, 2, 4, 7, 8]
 norm = mpl.colors.BoundaryNorm(bounds, cmap.N)
-cb2 = mpl.colorbar.ColorbarBase(ax, cmap=cmap,
-                                norm=norm,
-                                boundaries=[0] + bounds + [13],
-                                extend='both',
-                                ticks=bounds,
-                                spacing='proportional',
-                                orientation='horizontal')
+cb2 = fig.colorbar(
+    mpl.cm.ScalarMappable(cmap=cmap, norm=norm),
+    cax=ax,
+    boundaries=[0] + bounds + [13],
+    extend='both',
+    ticks=bounds,
+    spacing='proportional',
+    orientation='horizontal')
 cb2.set_label('Discrete intervals, some other units')
-fig.show()
 
 ###############################################################################
 # Colorbar with custom extension lengths
@@ -98,13 +98,15 @@
 
 bounds = [-1.0, -0.5, 0.0, 0.5, 1.0]
 norm = mpl.colors.BoundaryNorm(bounds, cmap.N)
-cb3 = mpl.colorbar.ColorbarBase(ax, cmap=cmap,
-                                norm=norm,
-                                boundaries=[-10] + bounds + [10],
-                                extend='both',
-                                extendfrac='auto',
-                                ticks=bounds,
-                                spacing='uniform',
-                                orientation='horizontal')
+cb3 = fig.colorbar(
+    mpl.cm.ScalarMappable(cmap=cmap, norm=norm),
+    cax=ax,
+    boundaries=[-10] + bounds + [10],
+    extend='both',
+    extendfrac='auto',
+    ticks=bounds,
+    spacing='uniform',
+    orientation='horizontal')
 cb3.set_label('Custom extension lengths, some other units')
-fig.show()
+
+plt.show()
