Copy-edit the standalone colorbar tutorial

- The tutorial is mostly about making standalone colorbars, so use that
  as title.
- Most users will still want the colorbar next to an existing axes, so
  explain how to do that.
- "Extended colorbar with continuous colorscale" is first about discrete
  colorbars (extensions are a second point), so adjust the title; also
  it already needs to introduce BoundaryNorm.  Adjust the next example's
  text accordingly as well, as it now only needs to introduce
  ListedColormap.
- In that next example, describe the additional kwargs to colorbar() in
  a bullet list.
- More consistently use fully qualified names the first time a new class
  is introduced, and unqualified names thereafter.
- Use constrained layout instead of manually adjusting figure
  geometries.
- Minor additional tweaks.

Author: anntzer

galleries/users_explain/colors/colorbar_only.py

@@ -1,56 +1,65 @@
 """
 .. redirect-from:: /tutorials/colors/colorbar_only
 
-=============================
-Customized Colorbars Tutorial
-=============================
+====================
+Standalone colorbars
+====================
 
 This tutorial shows how to build and customize standalone colorbars, i.e.
 without an attached plot.
 
-Customized Colorbars
-====================
-
 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
--------------------------
-
-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
-
 import matplotlib as mpl
 
-fig, ax = plt.subplots(figsize=(6, 1))
-fig.subplots_adjust(bottom=0.5)
+# %%
+# Basic continuous colorbar
+# -------------------------
+# 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 `~matplotlib.colorbar` API.
+
+fig, ax = plt.subplots(figsize=(6, 1), layout='constrained')
 
 cmap = mpl.cm.cool
 norm = mpl.colors.Normalize(vmin=5, vmax=10)
 
 fig.colorbar(mpl.cm.ScalarMappable(norm=norm, cmap=cmap),
              cax=ax, orientation='horizontal', label='Some Units')
 
+# %%
+# Colorbar attached next to a pre-existing axes
+# ---------------------------------------------
+# All examples in this tutorial (except this one) show a standalone colorbar on
+# its own figure, but it is possible to display the colorbar *next* to a
+# pre-existing Axes *ax* by passing ``ax=ax`` to the colorbar() call (meaning
+# "draw the colorbar next to *ax*") rather than ``cax=ax`` (meaning "draw the
+# colorbar on *ax*").
+
+fig, ax = plt.subplots(layout='constrained')
+
+fig.colorbar(mpl.cm.ScalarMappable(norm=mpl.colors.Normalize(0, 1), cmap='magma'),
+             ax=ax, orientation='vertical', label='a colorbar label')
 
 # %%
-# Extended colorbar with continuous colorscale
-# --------------------------------------------
-#
-# The second example shows how to make a discrete colorbar based on a
-# continuous cmap. With the "extend" keyword argument the appropriate colors
-# are chosen to fill the colorspace, including the extensions:
-fig, ax = plt.subplots(figsize=(6, 1))
-fig.subplots_adjust(bottom=0.5)
+# Discrete and extended colorbar with continuous colorscale
+# ---------------------------------------------------------
+# The following example shows how to make a discrete colorbar based on a
+# continuous cmap.  We use `matplotlib.colors.BoundaryNorm` to describe the
+# interval boundaries (which must be in increasing order), and further pass the
+# *extend* argument to it to further display "over" and "under" colors (which
+# are used for data outside of the norm range).
+
+fig, ax = plt.subplots(figsize=(6, 1), layout='constrained')
 
 cmap = mpl.cm.viridis
 bounds = [-1, 2, 5, 7, 12, 15]
@@ -61,72 +70,58 @@
              label="Discrete intervals with extend='both' keyword")
 
 # %%
-# Discrete intervals colorbar
-# ---------------------------
-#
-# The third example illustrates the use of a
-# :class:`~matplotlib.colors.ListedColormap` which generates a colormap from a
-# set of listed colors, `.colors.BoundaryNorm` which generates a colormap
-# index based on discrete intervals and extended ends to show the "over" and
-# "under" value colors. Over and under are used to display data outside of the
-# normalized [0, 1] range. Here we pass colors as gray shades as a string
-# encoding a float in the 0-1 range.
+# Colorbar with arbitrary colors
+# ------------------------------
+# The following example still uses a `.BoundaryNorm` to describe discrete
+# interval boundaries, but now uses a `matplotlib.colors.ListedColormap` to
+# associate each interval with an arbitrary color (there must be as many
+# intervals than there are colors).  The "over" and "under" colors are set on
+# the colormap using `.Colormap.with_extremes`.
 #
-# If a :class:`~matplotlib.colors.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.
+# We also pass additional arguments to `~.Figure.colorbar`:
 #
-# This time we pass additional arguments to
-# `~.Figure.colorbar`. For the out-of-range values to display on the colorbar
-# without using the *extend* keyword with
-# `.colors.BoundaryNorm`, we have to use the *extend* keyword argument directly
-# in the colorbar call.  Here we also
-# use the spacing argument to make
-# the length of each colorbar segment proportional to its corresponding
-# interval.
-
-fig, ax = plt.subplots(figsize=(6, 1))
-fig.subplots_adjust(bottom=0.5)
+# - To display the out-of-range values on the colorbar, we use the *extend*
+#   argument in the colorbar() call.  (This is equivalent to passing the
+#   *extend* argument in the `.BoundaryNorm` constructor as done in the
+#   previous example.)
+# - To make the length of each colorbar segment proportional to its
+#   corresponding interval, we use the *spacing* argument in the colorbar()
+#   call.
 
-cmap = (mpl.colors.ListedColormap(['red', 'green', 'blue', 'cyan'])
-        .with_extremes(over='0.25', under='0.75'))
+fig, ax = plt.subplots(figsize=(6, 1), layout='constrained')
 
+cmap = (mpl.colors.ListedColormap(['red', 'green', 'blue', 'cyan'])
+        .with_extremes(under='yellow', over='magenta'))
 bounds = [1, 2, 4, 7, 8]
 norm = mpl.colors.BoundaryNorm(bounds, cmap.N)
+
 fig.colorbar(
     mpl.cm.ScalarMappable(cmap=cmap, norm=norm),
-    cax=ax,
+    cax=ax, orientation='horizontal',
     extend='both',
-    ticks=bounds,
     spacing='proportional',
-    orientation='horizontal',
     label='Discrete intervals, some other units',
 )
 
 # %%
 # Colorbar with custom extension lengths
 # --------------------------------------
-#
-# Here we illustrate the use of custom length colorbar extensions, on a
-# colorbar with discrete intervals. To make the length of each extension the
+# We can customize the length colorbar extensions, on a colorbar with discrete
+# intervals. To make the length of each extension the
 # same as the length of the interior colors, use ``extendfrac='auto'``.
 
-fig, ax = plt.subplots(figsize=(6, 1))
-fig.subplots_adjust(bottom=0.5)
+fig, ax = plt.subplots(figsize=(6, 1), layout='constrained')
 
 cmap = (mpl.colors.ListedColormap(['royalblue', 'cyan', 'yellow', 'orange'])
         .with_extremes(over='red', under='blue'))
-
 bounds = [-1.0, -0.5, 0.0, 0.5, 1.0]
 norm = mpl.colors.BoundaryNorm(bounds, cmap.N)
+
 fig.colorbar(
     mpl.cm.ScalarMappable(cmap=cmap, norm=norm),
-    cax=ax,
-    extend='both',
-    extendfrac='auto',
-    ticks=bounds,
+    cax=ax, orientation='horizontal',
+    extend='both', extendfrac='auto',
     spacing='uniform',
-    orientation='horizontal',
     label='Custom extension lengths, some other units',
 )