mention matlab origin, add cyclic description, describe ColorBrewer schemes, discourage use of qualitative and redundant schemes, change some details based on luminance plots

endolith · endolith · commit cce444103c12 · 2012-05-31T00:22:48.000-03:00
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1654,64 +1654,71 @@ def colormaps():
 
       imshow(X, cmap=cm.hot)
 
-    or post-hoc using the :func:`set_cmap` function::
+    or using the :func:`set_cmap` function::
         
       imshow(X)
       pyplot.set_cmap('hot')
       pyplot.set_cmap('jet')
 
-    In interactive mode, this will update the colormap allowing you to
-    see which one works best for your data.  Additionally, for the "base" 
-    colormaps below, you can set the colormap using the corresponding pylab 
-    shortcut interface function::
-
-      imshow(X)
-      hot()
-      jet()
-
+    In interactive mode, :func:`set_cmap` will update the colormap post-hoc, 
+    allowing you to see which one works best for your data.
+    
     All built-in colormaps can be reversed by appending ``_r``: For instance,
     ``gray_r`` is the reverse of ``gray``.
 
-    There are 3 common color schemes used in visualization:
-
-    1. Sequential schemes, for unipolar data that progresses from low to high
-    2. Diverging schemes, for bipolar data that emphasizes positive or 
-       negative deviations from a central value
-    3. Qualitative schemes, for categorical data where color doesn't have a 
-       relationship to magnitude
-
-    The base colormaps are:
-
+    There are several common color schemes used in visualization:
+
+    Sequential schemes
+      for unipolar data that progresses from low to high
+    Diverging schemes
+      for bipolar data that emphasizes positive or negative deviations from a 
+      central value
+    Cyclic schemes
+      meant for plotting values that wrap around at the 
+      endpoints, such as phase angle, wind direction, or time of day
+    Qualitative schemes
+      for nominal data that has no inherent ordering, where color is used 
+      only to distinguish categories
+
+    The base colormaps are (with the exception of `spectral`) derived from 
+    those of the same name provided with Matlab:
+    
       =========   =======================================================
       Colormap    Description
       =========   =======================================================
-      autumn      sequential increasing shades of red-orange-yellow
-      bone        sequential black-white color map with a tinge of blue,
-                  to emulate X-ray film
-      cool        sequential decreasing shades of cyan-magenta
+      autumn      sequential linearly-increasing shades of red-orange-yellow
+      bone        sequential increasing black-white color map with 
+                  a tinge of blue, to emulate X-ray film
+      cool        linearly-decreasing shades of cyan-magenta
       copper      sequential increasing shades of black-copper
-      flag        repeating red-white-blue-black pattern
-      gray        simple sequential linearly-increasing black-to-white
+      flag        repetitive red-white-blue-black pattern (not cyclic at 
+                  endpoints)
+      gray        sequential linearly-increasing black-to-white
                   grayscale
       hot         sequential black-red-yellow-white, to emulate blackbody
                   radiation from an object at increasing temperatures
-      hsv         red-yellow-green-cyan-blue-pink-magenta, formed by
-                  changing the hue component in the HSV color space;
-                  meant to be used in plotting periodic data (that is,
-                  in which the maximum magnitude and the minimum
-                  magnitude are equivalent)
-      jet         blue-cyan-yellow-red, a variant of hsv; based on a
-                  fluid-jet simulation by NCSA [#]_
+      hsv         cyclic red-yellow-green-cyan-blue-magenta-red, formed 
+                  by changing the hue component in the HSV color space
+      jet         a spectral map with dark endpoints, blue-cyan-yellow-red; 
+                  based on a fluid-jet simulation by NCSA [#]_
       pink        sequential increasing pastel black-pink-white, meant
                   for sepia tone colorization of photographs
-      prism       repeating red-yellow-green-blue-purple-...-green pattern
-      spring      shades of magenta-yellow
-      summer      shades of green-yellow
-      winter      shades of blue-green
+      prism       repetitive red-yellow-green-blue-purple-...-green pattern 
+                  (not cyclic at endpoints)
+      spring      linearly-increasing shades of magenta-yellow
+      summer      sequential linearly-increasing shades of green-yellow
+      winter      linearly-increasing shades of blue-green
       spectral    black-purple-blue-green-yellow-red-white spectrum
       =========   =======================================================
 
-    The next 7 palettes are from the `Yorick scientific visualisation
+    For the above list only, you can also set the colormap using the 
+    corresponding pylab shortcut interface function, similar to Matlab::
+
+      imshow(X)
+      hot()
+      jet()
+
+    The next set of palettes are from the `Yorick scientific visualisation
     package <http://yorick.sourceforge.net/index.php>`_, an evolution of 
     the GIST package, both by David H. Munro:
 
@@ -1720,56 +1727,70 @@ def colormaps():
       ============  =======================================================
       gist_earth    mapmaker's colors from dark blue deep ocean to green 
                     lowlands to brown highlands to white mountains
-      gist_gray     (identical to *gray*)
-      gist_heat     sequential red-orange-yellow-white, to emulate blackbody
-                    radiation from an iron bar as it grows hotter
-      gist_ncar     pseudo-spectral colormap from National Center for 
-                    Atmospheric Research [#]_
-      gist_rainbow  runs through the colors in spectral order at nearly 
-                    constant intensity
+      gist_heat     sequential increasing black-red-orange-white, to emulate 
+                    blackbody radiation from an iron bar as it grows hotter
+      gist_ncar     pseudo-spectral black-blue-green-yellow-red-purple-white 
+                    colormap from National Center for Atmospheric 
+                    Research [#]_
+      gist_rainbow  runs through the colors in spectral order from red to 
+                    violet at full saturation (like *hsv* but not cyclic)
       gist_stern    "Stern special" color table from Interactive Data 
                     Language software
-      gist_yarg     (identical to *gray_r*)
       ============  =======================================================
 
-    The following 34 colormaps are based on the `ColorBrewer 
+    The following colormaps are based on the `ColorBrewer 
     <http://colorbrewer.org>`_ color specifications and designs developed by 
     Cynthia Brewer:
 
-    Diverging:
-
-    * BrBG
-    * PiYG
-    * PRGn
-    * PuOr
-    * RdBu
-    * RdGy
-    * RdYlBu
-    * RdYlGn
-    * Spectral
-
-    Sequential:
-
-    * Blues
-    * BuGn
-    * BuPu
-    * GnBu
-    * Greens
-    * Greys
-    * Oranges
-    * OrRd
-    * PuBu
-    * PuBuGn
-    * PuRd
-    * Purples
-    * RdPu
-    * Reds
-    * YlGn
-    * YlGnBu
-    * YlOrBr
-    * YlOrRd
-
-    Qualitative:
+    ColorBrewer Diverging (luminance is highest at the midpoint, and 
+    decreases towards differently-colored endpoints):
+
+      ========  ===================================
+      Colormap  Description
+      ========  ===================================
+      BrBG      brown, white, blue-green
+      PiYG      pink, white, yellow-green
+      PRGn      purple, white, green
+      PuOr      orange, white, purple
+      RdBu      red, white, blue
+      RdGy      red, white, gray
+      RdYlBu    red, yellow, blue
+      RdYlGn    red, yellow, green
+      Spectral  red, orange, yellow, green, blue
+      ========  ===================================
+
+    ColorBrewer Sequential (luminance decreases monotonically):
+
+      ========  ====================================
+      Colormap  Description
+      ========  ====================================
+      Blues     white to dark blue
+      BuGn      white, light blue, dark green
+      BuPu      white, light blue, dark purple
+      GnBu      white, light green, dark blue
+      Greens    white to dark green
+      Greys     white to black (not linear)
+      Oranges   white, orange, dark brown
+      OrRd      white, orange, dark red
+      PuBu      white, light purple, dark blue
+      PuBuGn    white, light purple, dark green
+      PuRd      white, light purple, dark red
+      Purples   white to dark purple
+      RdPu      white, pink, dark purple
+      Reds      white to dark red
+      YlGn      light yellow, dark green
+      YlGnBu    light yellow, light green, dark blue
+      YlOrBr    light yellow, orange, dark brown
+      YlOrRd    light yellow, orange, dark red
+      ========  ====================================
+      
+    ColorBrewer Qualitative:
+
+    (For plotting nominal data, :class:`ListedColormap` should be used, 
+    not :class:`LinearSegmentedColormap`.  Different sets of colors are 
+    recommended for different numbers of categories.  These continuous 
+    versions of the qualitative schemes may be removed or converted in the 
+    future.)
 
     * Accent
     * Dark2
@@ -1787,7 +1808,6 @@ def colormaps():
       =========  =======================================================
       afmhot     sequential black-orange-yellow-white blackbody 
                  spectrum, commonly used in atomic force microscopy
-      binary     (identical to *gray_r*)
       brg        blue-red-green 
       bwr        diverging blue-white-red
       coolwarm   diverging blue-gray-red, meant to avoid issues with 3D 
@@ -1810,20 +1830,34 @@ def colormaps():
       gnuplot2   sequential color printable as gray 
                  (black-blue-violet-yellow-white)
       ocean      green-blue-white
-      rainbow    purple-blue-green-yellow-orange-red
+      rainbow    spectral purple-blue-green-yellow-orange-red colormap
+                 with diverging luminance
       seismic    diverging blue-white-red
       terrain    mapmaker's colors, blue-green-yellow-brown-white, 
                  originally from IGOR Pro
       =========  =======================================================
 
+    The following colormaps are redundant and may be removed in future 
+    versions.  It's recommended to use *gray* or *gray_r* instead, which 
+    produce identical output:
+
+      =========  =======================================================
+      Colormap   Description
+      =========  =======================================================
+      gist_gray  identical to *gray*
+      gist_yarg  identical to *gray_r*
+      binary     identical to *gray_r*
+      =========  =======================================================
+
     .. rubric:: Footnotes
 
     .. [#] Rainbow colormaps, ``jet`` in particular, are considered a poor 
       choice for scientific visualization by many researchers: `Rainbow Color 
       Map (Still) Considered Harmful 
       <http://www.jwave.vt.edu/%7Erkriz/Projects/create_color_table/color_07.pdf>`_
 
-    .. [#] Resembles "BkBlAqGrYeOrReViWh200" from `Color Table Gallery   
+    .. [#] Resembles "BkBlAqGrYeOrReViWh200" from NCAR Command 
+      Language. See `Color Table Gallery 
       <http://www.ncl.ucar.edu/Document/Graphics/color_table_gallery.shtml>`_
 
     .. [#] See `Diverging Color Maps for Scientific Visualization 
