added a reversed section to colormap reference and reversing section to

story645 · rutj3 · jklymak · story645 · commit 5f1e34cc9283 · 2022-09-19T15:21:24.000-04:00
colormap tutorial

Co-authored-by: RutgerK &lt;2157033+RutgerK@users.noreply.github.com&gt;
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: 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,21 @@ 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 using `.Colormap.reversed`.
+# For an example, see :ref:`reversing-colormap`
 
 #############################################################################
 #
diff --git a/tutorials/colors/colormap-manipulation.py b/tutorials/colors/colormap-manipulation.py
@@ -255,6 +255,43 @@ def plot_linearmap(cdict):
 
 plot_examples([cmap1, cmap2])
 
+#############################################################################
+# .. _reversing-colormap:
+#
+# Reversing a colormap
+# ====================
+#
+# Any colormap can be reversed using `.Colormap.reversed`. For example:
+
+colors = ["#ffffcc", "#a1dab4", "#41b6c4", "#2c7fb8", "#253494"]
+my_cmap = ListedColormap(colors, name="my_cmap")
+
+my_cmap_r = my_cmap.reversed()
+
+plot_examples([my_cmap, my_cmap_r])
+# %%
+# This method reverses the parent colormap. If no name is passed in, it also
+# names the reversed map by appending ``_r`` to the parent colormap's name.
+# See :ref:`registering-colormap` for an example.
+
+##############################################################################
+# .. _registering-colormap:
+#
+# Registering a colormap
+# ======================
+#
+# Colormaps can be added to the `matplotlib.colormaps` list of named colormaps.
+# This allows the colormaps to be accessed by name in plotting functions:
+
+mpl.colormaps.register(cmap=my_cmap)
+mpl.colormaps.register(cmap=my_cmap_r)
+
+plot_examples(['my_cmap', 'my_cmap_r'])
+
+# %%
+# The cmaps registered in this example were created in
+# :ref:`reversing-colormap`
+
 #############################################################################
 #
 # .. admonition:: References
