Merge pull request #12084 from jklymak/doc-link-palettable

tacaswell · tacaswell · commit 448413a3e00f · 2018-11-09T19:12:16.000-05:00
DOC: link palettable
diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
@@ -26,6 +26,8 @@
   :doc:`/tutorials/colors/colormapnorms` for more details about data
   normalization
 
+  More colormaps are available at palettable_
+
 The module also provides functions for checking whether an object can be
 interpreted as a color (:func:`is_color_like`), for converting such an object
 to an RGBA tuple (:func:`to_rgba`) or to an HTML-like hex string in the
@@ -53,6 +55,9 @@
   cycle does not include color.
 
 All string specifications of color, other than "CN", are case-insensitive.
+
+.. _palettable: https://jiffyclub.github.io/palettable/
+
 """
 
 from collections.abc import Sized
diff --git a/tutorials/colors/colormap-manipulation.py b/tutorials/colors/colormap-manipulation.py
@@ -3,11 +3,17 @@
 Creating Colormaps in Matplotlib
 ********************************
 
-Creating and manipulating colormaps in Matplotlib is straight-forward
-using the class `.ListedColormap` and a Nx4 numpy array of values
-between 0 and 1 to represent the RGBA values of the colormap.  There
+Matplotlib has a number of built-in colormaps accessible via
+`.matplotlib.cm.get_cmap`.  There are also external libraries like
+palettable_ that have many extra colormaps.
+
+.. _palettable: https://jiffyclub.github.io/palettable/
+
+However, we often want to create or manipulate colormaps in Matplotlib.
+This can be done using the class `.ListedColormap` and a Nx4 numpy array of
+values between 0 and 1 to represent the RGBA values of the colormap.  There
 is also a `.LinearSegmentedColormap` class that allows colormaps to be
-specified with far fewer anchor points defining segments, and linearly
+specified with a few anchor points defining segments, and linearly
 interpolating between the anchor points.
 
 Getting colormaps and accessing their values
diff --git a/tutorials/colors/colormaps.py b/tutorials/colors/colormaps.py
@@ -1,9 +1,13 @@
 """
-***********************
-Colormaps in Matplotlib
-***********************
+********************************
+Choosing Colormaps in Matplotlib
+********************************
 
-How (and why) to choose a particular colormap.
+Matplotlib has a number of built-in colormaps accessible via
+`.matplotlib.cm.get_cmap`.  There are also external libraries like
+[palettable]_ that have many extra colormaps.  Here we briefly discuss
+how to choose between the many options.  For help on creating your
+own colormaps, see :doc:`/tutorials/colors/colormap-manipulation`.
 
 Overview
 ========
@@ -268,7 +272,7 @@ def plot_color_gradients(cmap_category, cmap_list, nrows):
             # Plot colormap L values.  Do separately for each category
             # so each plot can be pretty.  To make scatter markers change
             # color along plot:
-            # http://stackoverflow.com/questions/8202605/matplotlib-scatterplot-colour-as-a-function-of-a-third-variable
+            # http://stackoverflow.com/questions/8202605/
 
             if cmap_category == 'Sequential':
                 # These colormaps all start at high lightness but we want them
@@ -322,30 +326,31 @@ def plot_color_gradients(cmap_category, cmap_list, nrows):
 # plots because the grayscale changes unpredictably through the
 # colormap.
 #
-# Conversion to grayscale is done in many different ways [bw]_. Some of the better
-# ones use a linear combination of the rgb values of a pixel, but weighted
-# according to how we perceive color intensity. A nonlinear method of conversion
-# to grayscale is to use the :math:`L^*` values of the pixels. In general, similar
-# principles apply for this question as they do for presenting one's information
-# perceptually; that is, if a colormap is chosen that is monotonically increasing
-# in :math:`L^*` values, it will print in a reasonable manner to grayscale.
+# Conversion to grayscale is done in many different ways [bw]_. Some of the
+# better ones use a linear combination of the rgb values of a pixel, but
+# weighted according to how we perceive color intensity. A nonlinear method of
+# conversion to grayscale is to use the :math:`L^*` values of the pixels. In
+# general, similar principles apply for this question as they do for presenting
+# one's information perceptually; that is, if a colormap is chosen that is
+# monotonically increasing in :math:`L^*` values, it will print in a reasonable
+# manner to grayscale.
 #
 # With this in mind, we see that the Sequential colormaps have reasonable
 # representations in grayscale. Some of the Sequential2 colormaps have decent
-# enough grayscale representations, though some (autumn, spring, summer, winter)
-# have very little grayscale change. If a colormap like this was used in a plot
-# and then the plot was printed to grayscale, a lot of the information may map to
-# the same gray values. The Diverging colormaps mostly vary from darker gray on
-# the outer edges to white in the middle. Some (PuOr and seismic) have noticeably
-# darker gray on one side than the other and therefore are not very symmetric.
-# coolwarm has little range of gray scale and would print to a more uniform plot,
-# losing a lot of detail. Note that overlaid, labeled contours could help
-# differentiate between one side of the colormap vs. the other since color cannot
-# be used once a plot is printed to grayscale. Many of the Qualitative and
-# Miscellaneous colormaps, such as Accent, hsv, and jet, change from darker to
-# lighter and back to darker gray throughout the colormap. This would make it
-# impossible for a viewer to interpret the information in a plot once it is
-# printed in grayscale.
+# enough grayscale representations, though some (autumn, spring, summer,
+# winter) have very little grayscale change. If a colormap like this was used
+# in a plot and then the plot was printed to grayscale, a lot of the
+# information may map to the same gray values. The Diverging colormaps mostly
+# vary from darker gray on the outer edges to white in the middle. Some
+# (PuOr and seismic) have noticeably darker gray on one side than the other
+# and therefore are not very symmetric. coolwarm has little range of gray scale
+# and would print to a more uniform plot, losing a lot of detail. Note that
+# overlaid, labeled contours could help differentiate between one side of the
+# colormap vs. the other since color cannot be used once a plot is printed to
+# grayscale. Many of the Qualitative and Miscellaneous colormaps, such as
+# Accent, hsv, and jet, change from darker to lighter and back to darker gray
+# throughout the colormap. This would make it impossible for a viewer to
+# interpret the information in a plot once it is printed in grayscale.
 
 mpl.rcParams.update({'font.size': 14})
 
@@ -395,13 +400,13 @@ def plot_color_gradients(cmap_category, cmap_list):
 # =========================
 #
 # There is a lot of information available about color blindness (*e.g.*,
-# [colorblindness]_). Additionally, there are tools available to convert images to
-# how they look for different types of color vision deficiencies (*e.g.*,
+# [colorblindness]_). Additionally, there are tools available to convert images
+# to how they look for different types of color vision deficiencies (*e.g.*,
 # [vischeck]_).
 #
-# The most common form of color vision deficiency involves differentiating between
-# red and green. Thus, avoiding colormaps with both red and green will avoid many
-# problems in general.
+# The most common form of color vision deficiency involves differentiating
+# between red and green. Thus, avoiding colormaps with both red and green will
+# avoid many problems in general.
 #
 #
 # References
@@ -418,3 +423,4 @@ def plot_color_gradients(cmap_category, cmap_list):
 # .. [colorblindness] http://www.color-blindness.com/
 # .. [vischeck] http://www.vischeck.com/vischeck/
 # .. [IBM] https://dx.doi.org/10.1109/VISUAL.1995.480803
+# .. [palettable] https://jiffyclub.github.io/palettable/
