added a reversed section to colormap reference and reversing section to

story645 · jklymak · timhoffm · story645 · commit e6b44f62a34a · 2022-09-18T22:10:09.000-04:00
colormap tutorial

Co-authored-by: Jody Klymak &lt;jklymak@gmail.com&gt;
Co-authored-by: Tim Hoffmann &lt;2836374+timhoffm@users.noreply.github.com&gt;
Co-authored-by: RutgerK &lt;2157033+RutgerK@users.noreply.github.com&gt;
Co-authored-by: Thomas A Caswell &lt;tcaswell@gmail.com&gt;
diff --git a/examples/color/colormap_reference.py b/examples/color/colormap_reference.py
@@ -6,16 +6,17 @@
 Reference for colormaps included with Matplotlib.
 
 A reversed version of each of these colormaps is available by appending
-``_r`` to the name, e.g., ``viridis_r``.
+``_r`` to the name, as shown in :ref:`reverse-cmap`.
 
 See :doc:`/tutorials/colors/colormaps` for an in-depth discussion about
-colormaps, including colorblind-friendliness.
+colormaps, including colorblind-friendliness, and
+:doc:`/tutorials/colors/colormap-manipulation` for a guide to creating
+colormaps.
 """
 
 import numpy as np
 import matplotlib.pyplot as plt
 
-
 cmaps = [('Perceptually Uniform Sequential', [
             'viridis', 'plasma', 'inferno', 'magma', 'cividis']),
          ('Sequential', [
@@ -40,7 +41,6 @@
             'gist_rainbow', 'rainbow', 'jet', 'turbo', 'nipy_spectral',
             'gist_ncar'])]
 
-
 gradient = np.linspace(0, 1, 256)
 gradient = np.vstack((gradient, gradient))
 
@@ -52,7 +52,7 @@ def plot_color_gradients(cmap_category, cmap_list):
     fig, axs = plt.subplots(nrows=nrows, figsize=(6.4, figh))
     fig.subplots_adjust(top=1-.35/figh, bottom=.15/figh, left=0.2, right=0.99)
 
-    axs[0].set_title(cmap_category + ' colormaps', fontsize=14)
+    axs[0].set_title(f"{cmap_category} colormaps", fontsize=14)
 
     for ax, cmap_name in zip(axs, cmap_list):
         ax.imshow(gradient, aspect='auto', cmap=cmap_name)
@@ -67,7 +67,23 @@ def plot_color_gradients(cmap_category, cmap_list):
 for cmap_category, cmap_list in cmaps:
     plot_color_gradients(cmap_category, cmap_list)
 
-plt.show()
+
+###############################################################################
+# .. _reverse-cmap:
+#
+# Reversed colormaps
+# ------------------
+#
+# Append ``_r`` to the name of any built-in colormap to get the reversed
+# version:
+
+plot_color_gradients("Original and reversed ", ['viridis', 'viridis_r'])
+
+# %%
+# The built-in reversed colormaps are generated when building the
+# `.ColormapRegistry` by calling the ``reversed`` method on the built-in
+# colormap objects. See :ref:`reversing-colormap` for more information about
+# the ``reversed`` method.
 
 #############################################################################
 #
diff --git a/tutorials/colors/colormap-manipulation.py b/tutorials/colors/colormap-manipulation.py
@@ -255,6 +255,29 @@ def plot_linearmap(cdict):
 
 plot_examples([cmap1, cmap2])
 
+#############################################################################
+# .. _reversing-colormap:
+#
+# Reversing a colormap
+# ====================
+#
+# Any colormap that is a registered as a matplotlib `.Colormap` can be reversed
+# using the ``reversed`` method of the colormap object. For example:
+
+colors = ["#ffffcc", "#a1dab4", "#41b6c4", "#2c7fb8", "#253494"]
+my_cmap = ListedColormap(colors, name="my_cmap")
+# register
+mpl.colormaps.register(cmap=my_cmap)
+# reverse custom colormap
+mpl.colormaps.register(cmap=my_cmap.reversed())
+
+plot_examples(['my_cmap', 'my_cmap_r'])
+
+# %%
+# This method generates a new colormap by reversing the order of colors in the
+# source colormap and creates a name for the reversed map by appending
+# ``_r`` to the source colormap's name.
+
 #############################################################################
 #
 # .. admonition:: References
