Add colorbar example to docs

fmaussion · efiring · commit 3ad379d2a0ea · 2020-05-28T11:58:47.000-10:00
diff --git a/examples/api/colorbar_only.py b/examples/api/colorbar_only.py
@@ -0,0 +1,90 @@
+'''
+====================
+Customized colorbars
+====================
+
+This example shows how to build colorbars without an attached mappable.
+'''
+
+import matplotlib.pyplot as plt
+import matplotlib as mpl
+
+# Make a figure and axes with dimensions as desired.
+fig = plt.figure(figsize=(8, 5))
+ax1 = fig.add_axes([0.05, 0.85, 0.9, 0.1])
+ax2 = fig.add_axes([0.05, 0.6, 0.9, 0.1])
+ax3 = fig.add_axes([0.05, 0.35, 0.9, 0.1])
+ax4 = fig.add_axes([0.05, 0.1, 0.9, 0.1])
+
+# Set the colormap and norm to correspond to the data for which
+# the colorbar will be used.
+cmap = mpl.cm.cool
+norm = mpl.colors.Normalize(vmin=5, vmax=10)
+
+# 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(ax1, cmap=cmap,
+                                norm=norm,
+                                orientation='horizontal')
+cb1.set_label('Some Units')
+
+# The second example shows how to make a discrete colorbar based on a
+# continuous cmapnorm = mpl.colors.BoundaryNorm(bounds, cmap.N, extend='both')
+cmap = mpl.cm.viridis
+bounds = [-1, 2, 5, 7, 12, 15]
+norm = mpl.colors.BoundaryNorm(bounds, cmap.N, extend='both')
+cb2 = mpl.colorbar.ColorbarBase(ax2, cmap=cmap,
+                                     norm=norm,
+                                     orientation='horizontal')
+cb2.set_label("Discrete intervals with extend='both' keyword")
+
+
+# The third example illustrates the use of a ListedColormap, a
+# BoundaryNorm, and extended ends to show the "over" and "under"
+# value colors.
+cmap = mpl.colors.ListedColormap(['r', 'g', 'b', 'c'])
+cmap.set_over('0.25')
+cmap.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 = [1, 2, 4, 7, 8]
+norm = mpl.colors.BoundaryNorm(bounds, cmap.N)
+cb3 = mpl.colorbar.ColorbarBase(ax3, cmap=cmap,
+                                norm=norm,
+                                # to use 'extend', you must
+                                # specify two extra boundaries:
+                                boundaries=[0] + bounds + [13],
+                                extend='both',
+                                ticks=bounds,  # optional
+                                spacing='proportional',
+                                orientation='horizontal')
+cb3.set_label('Discrete intervals, some other units')
+
+# The fourth example illustrates the use of custom length colorbar
+# extensions, used on a colorbar with discrete intervals.
+cmap = mpl.colors.ListedColormap([[0., .4, 1.], [0., .8, 1.],
+                                  [1., .8, 0.], [1., .4, 0.]])
+cmap.set_over((1., 0., 0.))
+cmap.set_under((0., 0., 1.))
+
+bounds = [-1., -.5, 0., .5, 1.]
+norm = mpl.colors.BoundaryNorm(bounds, cmap.N)
+cb4 = mpl.colorbar.ColorbarBase(ax4, cmap=cmap,
+                                norm=norm,
+                                boundaries=[-10] + bounds + [10],
+                                extend='both',
+                                # Make the length of each extension
+                                # the same as the length of the
+                                # interior colors:
+                                extendfrac='auto',
+                                ticks=bounds,
+                                spacing='uniform',
+                                orientation='horizontal')
+cb4.set_label('Custom extension lengths, some other units')
+
+plt.show()
