Documenting the matplotlib colormaps

readme.md

Researched the origins and purposes of all the colormaps built into matplotlib, then added the info to the colormaps() docstring in pyplot.py

This info is now at: http://matplotlib.org/api/pyplot_summary.html?highlight=colormaps#matplotlib.pyplot.colormaps

Accent.py

# https://github.com/matplotlib/matplotlib/issues/881
# Several of the ColorBrewer maps are "qualitative", meaning
# they are just a group of colors that can be used together 
# for categories of data.  So I remapped Accent to segments 
# instead of continuous:

# Actually, these should be used with ListedColormap, and 
# the number of colors should depend on the number of 
# categories in the data, with colors removed from the 
# list in a certain order?

_Accent_data = {
    'blue': [
    (0.0,   0.0,                    0.49803921580314636), 
    (0.125, 0.49803921580314636,    0.83137255907058716), 
    (0.25,  0.83137255907058716,    0.52549022436141968), 
    (0.375, 0.52549022436141968,    0.60000002384185791), 
    (0.5,   0.60000002384185791,    0.69019609689712524), 
    (0.625, 0.69019609689712524,    0.49803921580314636), 
    (0.75,  0.49803921580314636,    0.090196080505847931), 
    (0.875, 0.090196080505847931,   0.40000000596046448), 
    (1.0,   0.40000000596046448,    0.0),
    ],

    'green': [
    (0.0,   0.0,                    0.78823530673980713),
    (0.125, 0.78823530673980713,    0.68235296010971069),
    (0.25,  0.68235296010971069,    0.75294119119644165),
    (0.375, 0.75294119119644165,    1.0), 
    (0.5,   1.0,                    0.42352941632270813), 
    (0.625, 0.42352941632270813,    0.0078431377187371254),
    (0.75,  0.0078431377187371254,  0.35686275362968445),
    (0.875, 0.35686275362968445,    0.40000000596046448),
    (1.0,   0.40000000596046448,    0.0),
    ],

    'red': [
    (0.0,   0.0,                    0.49803921580314636),
    (0.125, 0.49803921580314636,    0.7450980544090271),
    (0.25,  0.7450980544090271,     0.99215686321258545),
    (0.375, 0.99215686321258545,    1.0), 
    (0.5,   1.0,                    0.21960784494876862), 
    (0.625, 0.21960784494876862,    0.94117647409439087), 
    (0.75,  0.94117647409439087,    0.74901962280273438), 
    (0.875, 0.74901962280273438,    0.40000000596046448),
    (1.0,   0.40000000596046448,    0.0),
    ],
    }

colormaps_docstring.rst

matplotlib provides a number of colormaps, a complete list of which can be found in cm._cmapnames.

You can set the colormap for an image, pcolor, scatter, etc, using a keyword argument:

imshow(X, cmap=cm.hot)

Additionally, for the "base" colormaps below, you can set the colormap post-hoc using the corresponding pylab interface function:

imshow(X)
hot()
jet()

In interactive mode, this will update the colormap allowing you to see which one works best for your data.

All 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, which don't have a relationship to magnitude

The base colormaps are:

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
copper	sequential increasing shades of black-copper
flag	repeating red-white-blue-black pattern
gray	simple 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 [1]
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
spectral	black-purple-blue-green-yellow-red-white spectrum

The next 7 palettes are from the Yorick scientific visualisation package, an evolution of the GIST package, both by David H. Munro:

Colormap	Description
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 [2]
gist_rainbow	runs through the colors in spectral order at nearly constant intensity
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 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:

• Accent
• Dark2
• Paired
• Pastel1
• Pastel2
• Set1
• Set2
• Set3

Other miscellaneous schemes:

Colormap	Description
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 shading, color blindness, and ordering of colors [3]
CMRmap	"Default colormaps on color images often reproduce to confusing grayscale images. The proposed colormap maintains an aesthetically pleasing color image that automatically reproduces to a monotonic grayscale with discrete, quantifiable saturation levels." [4]
cubehelix	Unlike most other color schemes cubehelix was designed by D.A. Green to be monotonically increasing in terms of perceived brightness. Also, when printed on a black and white postscript printer, the scheme results in a greyscale with monotonically increasing brightness. This color scheme is named cubehelix because the r,g,b values produced can be visualised as a squashed helix around the diagonal in the r,g,b color cube.
gnuplot	gnuplot's traditional pm3d scheme (black-blue-red-yellow)
gnuplot2	sequential color printable as gray (black-blue-violet-yellow-white)
ocean	green-blue-white
rainbow	purple-blue-green-yellow-orange-red
seismic	diverging blue-white-red
terrain	mapmaker's colors, blue-green-yellow-brown-white, originally from IGOR Pro

Footnotes

[1]	Rainbow colormaps, jet in particular, are considered a poor choice for scientific visualization by many researchers: Rainbow Color Map (Still) Considered Harmful

[2]	Resembles "BkBlAqGrYeOrReViWh200" from Color Table Gallery

[3]	See Diverging Color Maps for Scientific Visualization by Kenneth Moreland.

[4]	See A Color Map for Effective Black-and-White Rendering of Color-Scale Images by Carey Rappaport

full list.txt

From cm._cmapnames


Copied from MATLAB:

    autumn 
    bone 
    cool 
    copper 
    flag 
    gray 
    hot 
    hsv 
    jet 
    pink 
    prism 
    spring 
    summer 
    winter 

    (Not copied from MATLAB: colorcube, lines, white)

    These were all added here https://github.com/matplotlib/matplotlib/commit/26ffb47e95d7d694a94bb101d17ebcd0622d15f7


spectral (Spectral is not the same! rename to nipy_spectral?)

    "Tim Leslie's spectral patch"
    https://github.com/matplotlib/matplotlib/commit/b64652d335d4318d1b1a332843837a0c17a4a202
    added after "Spectral"

    from nipy
    http://sourceforge.net/mailarchive/message.php?msg_id=8931272

    Only non-MATLAB colormap to have a post-hoc function

    Related to http://www.math.mcgill.ca/keith/surfstat/doc/SurfStat/spectral.html and http://www.mathworks.com/matlabcentral/fileexchange/4706-mia-2-4/content/mia24/Tools/spectralmni.m but none of these have the same endpoints

    "black-purple-blue-green-yellow-red-white"




Copied from GIST/Yorick:

    # The next 7 palettes are from the Yorick scientific visalisation package,
    # an evolution of the GIST package, both by David H. Munro.

    descriptions here http://dhmunro.github.com/yorick-doc/manual/yorick_70.html http://projects.scipy.org/scipy/browser/trunk/Lib/xplt/gistdata?rev=685

    These palettes tend to start with dark colors and progress toward lighter colors, except yarg and rainbow
    
    gist_earth  "is loosely based on mapmaker's colors from dark blue deep ocean to green lowlands to brown highlands to white mountains" "dk blue - lt blue - dk green - yellow green - lt brown - white sort of like mapmakers colors from deep ocean to snow capped peak"
    gist_gray (identical to gray)
    gist_heat "a red-orange scale resembling the colors of an iron bar as it grows hotter" "dk red - red - orange - yellow  - white	color temperatures of hot iron bar"
    gist_ncar - resembles BkBlAqGrYeOrReViWh200 from National Center for Atmospheric Research
    http://www.ncl.ucar.edu/Document/Graphics/color_table_gallery.shtml
    gist_rainbow "runs through the colors in spectral order at nearly constant intensity" "colors in spectral order"
    gist_stern # red - dk blue - lt blue - gray green - white "Stern special" color table from IDL (c) Research Systems, Inc.
    gist_yarg (identical to gray_r and binary)

    sources here: https://github.com/dhmunro/yorick/tree/master/g
    no explanation of what ncar or stern are for
    'Earlier versions of SkyView used the "Stern Special" color table by default, but we now default to more realistic if less colorful black and white images.'
    'In appearance the most significant change is that by default images are now black and white. Users can select any of the old and many new color tables if desired but we feel that the black and white images most accurately reflect the intensity scaling. Some novice users were confused about the meaning of the colors in the old versions. The old system used the Stern Special color table.'

    In [4]: array_equal(cm.cmap_d['gist_gray'](arange(256)), cm.cmap_d['gray'](arange(256)))
    Out[4]: True

ColorBrewer

    # 34 colormaps based on color specifications and designs
    # developed by Cynthia Brewer (http://colorbrewer.org).
    # The ColorBrewer palettes have been included under the terms
    # of an Apache-stype license (for details, see the file
    # LICENSE_COLORBREWER in the license directory of the matplotlib
    # source distribution).

    Added here https://github.com/matplotlib/matplotlib/commit/31c07815140e97becf2f2e037b8a214e263290b2
    Categorizations here http://rgm2.lab.nig.ac.jp/RGM2/func.php?rd_id=RColorBrewer:ColorBrewer

             maxcolors category

    Diverging
    BrBG            11      div
    PiYG            11      div
    PRGn            11      div
    PuOr            11      div
    RdBu            11      div
    RdGy            11      div
    RdYlBu          11      div
    RdYlGn          11      div
    Spectral        11      div  (not the same as spectral)

    Qualitative (these aren't supposed to be continuous! bug report?)
    Accent           8     qual
    Dark2            8     qual
    Paired          12     qual
    Pastel1          9     qual
    Pastel2          8     qual
    Set1             9     qual
    Set2             8     qual
    Set3            12     qual

    Sequential
    Blues            9      seq
    BuGn             9      seq
    BuPu             9      seq
    GnBu             9      seq
    Greens           9      seq
    Greys            9      seq
    Oranges          9      seq
    OrRd             9      seq
    PuBu             9      seq
    PuBuGn           9      seq
    PuRd             9      seq
    Purples          9      seq
    RdPu             9      seq
    Reds             9      seq
    YlGn             9      seq
    YlGnBu           9      seq
    YlOrBr           9      seq
    YlOrRd           9      seq




cubehelix

    Unlike most other color schemes cubehelix was designed by D.A. Green to
    be monotonically increasing in terms of perceived brightness.
    Also, when printed on a black and white postscript printer, the scheme
    results in a greyscale with monotonically increasing brightness.
    This color scheme is named cubehelix because the r,g,b values produced
    can be visualised as a squashed helix around the diagonal in the
    r,g,b color cube.

    discussion http://sourceforge.net/mailarchive/message.php?msg_id=28065739
    paper http://arxiv.org/abs/1108.5083

    see cm.cubehelix()   (no way to view the docstring?)


coolwarm

    # This bipolar color map was generated from 
    # "Diverging Color Maps for Scientific Visualization" by Kenneth Moreland.
    # <http://www.cs.unm.edu/~kmorel/documents/ColorMaps/>

    Discussion about patch:
    http://sourceforge.net/mailarchive/message.php?msg_id=27816391

    – The map yields images that are aesthetically pleasing.
    – The map has a maximal perceptual resolution.
    – Interference with the shading of 3D surfaces is minimal.
    – The map is not sensitive to vision deficiencies.
    – The order of the colors should be intuitively the same for all people.
    – The perceptual interpolation matches the underlying scalars of the map.

    http://www.cs.unm.edu/~kmorel/documents/ColorMaps/index.html



CMRmap

    Default colormaps on color images often reproduce to confusing grayscale images. The proposed colormap maintains an aesthetically pleasing color image that automatically reproduces to a monotonic grayscale with discrete, quantifiable saturation levels.

    # Implementation of Carey Rappaport's CMRmap.
    # See `A Color Map for Effective Black-and-White Rendering of Color-Scale Images' by Carey Rappaport
    # http://www.mathworks.com/matlabcentral/fileexchange/2662-cmrmap-m


misc others added at the same time

    afmhot - Used in atomic force microscopy?
    brg
    bwr
    gnuplot
    gnuplot2
    ocean
    rainbow
    seismic
    terrain - from "a measurement program called 'Igor'"  http://www.wavemetrics.com/products/igorpro/creatinggraphs/colortab.htm

    all added here: http://sourceforge.net/mailarchive/message.php?msg_id=23330302

    seismic from here? http://soliton.vm.bytemark.co.uk/pub/cpt-city/gery/index.html http://www.mathworks.com/matlabcentral/fileexchange/30585-large-data-in-matlab-a-seismic-data-processing-case-study/content/migration/seismic.m

    afmhot, ocean, rainbow from here? http://gnuplot.sourceforge.net/docs_4.2/node216.html

    apparently AFM because heat is a common palette for atomic force microscopy? https://www.google.com/search?q=atomic+force+microscopy&tbm=isch  "The color selection uses the HSB-color model where the color (H) is set in ° value. The color is selected by entering a number or by clicking a color in the color bar."

binary

    identical to gray_r and gist_yarg

    In [8]: array_equal(cm.cmap_d['binary'](arange(256)), cm.cmap_d['gray_r'](arange(256)))
    Out[8]: True

    added here: https://github.com/matplotlib/matplotlib/commit/47af03d985d9729f3eedc41354fe11a22eff35c4

    meant for barcodes?




identify which are isoluminant/monotonic, sequential/diverging/cyclic/spectral, etc

"sequential (quantitative) variables, discrete (qualitative) variables, and bipolar (diverging) variables"

h5utils definitions.rst

From http://ab-initio.mit.edu/wiki/index.php/Color_tables_in_h5topng

autumn

red-orange-yellow color map; based on colormap of the same name in Matlab

bluered

blue-white-red colorbar, useful for signed data in conjunction with -Z option to make white=0

bone

nearly grayscale (blackish to whitish) color map with a tinge of blue; based on colormap of the same name in Matlab, which suggests using it to add an "electronic" look to grayscale images

colorcube

enhanced color-cube color map; based on colormap of the same name in Matlab, basically designed to fill the RGB color space with an emphasis on a few pure colors

cool

cyan-magenta color map; based on colormap of the same name in Matlab

copper

black-copper color map; based on colormap of the same name in Matlab

dkbluered

dark blue-white-red colorbar, useful for signed data in conjunction with -Z option to make white=0; similar to bluered but shows a bit more dynamic range for the maxima/minima by darkening at the ends

flag

alternating red/white/blue/black color map; based on colormap of the same name in Matlab

gray

simple black-to-white grayscale color bar

green

white-green color map; useful for translucent overlays with -A

hot

black-red-yellow-white color map, useful for nonnegative "intensity" data — based on colormap of the same name in Matlab, loosely resembling the color of heated object at increasing temperatures

hsv

red-yellow-green-cyan-blue-pink-magenta color map formed by changing the hue component in the HSV color space; based on colormap of the same name in Matlab, who recommend it for used in plotting periodic data (that is, in which the maximum magnitude and the minimum magnitude are equivalent)

jet

blue-cyan-yellow-red color map (a variant of hsv; based on colormap of the same name in Matlab, who based it on a fluid-jet simulation by NCSA

lines

oscillating color map; based on colormap of the same name in Matlab (based on the Matlab plot-line colors)

pink

pastel black-pink-white color map; based on colormap of the same name in Matlab, used for Sepia tone colorization

prism

repeating red-yellow-green-blue-purple-...-green color map; based on colormap of the same name in Matlab

spring

magenta-yellow color map; based on colormap of the same name in Matlab

summer

green-yellow color map; based on colormap of the same name in Matlab

vga

Windows 4-bit color map; based on colormap of the same name in Matlab

winter

blue-green color map; based on colormap of the same name in Matlab

yarg

simple white-to-black grayscale color bar (the reverse of gray, and almost equivalent to using -gray or gray with -r); this is useful to make contour-like overlays with the -A option because its transparency scale (black is transparent) is the opposite of gray (white is transparent)

yellow

white-yellow color map; useful for translucent overlays with -A

MATLABs definitions.rst

From http://www.mathworks.com/help/techdoc/ref/colormap.html

autumn

varies smoothly from red, through orange, to yellow.

bone

is a grayscale colormap with a higher value for the blue component. This colormap is useful for adding an "electronic" look to grayscale images.

colorcube

contains as many regularly spaced colors in RGB color space as possible, while attempting to provide more steps of gray, pure red, pure green, and pure blue.

cool

consists of colors that are shades of cyan and magenta. It varies smoothly from cyan to magenta.

copper

varies smoothly from black to bright copper.

flag

consists of the colors red, white, blue, and black. This colormap completely changes color with each index increment.

gray

returns a linear grayscale colormap.

hot

varies smoothly from black through shades of red, orange, and yellow, to white.

hsv

varies the hue component of the hue-saturation-value color model. The colors begin with red, pass through yellow, green, cyan, blue, magenta, and return to red. The colormap is particularly appropriate for displaying periodic functions. hsv(m) is the same as hsv2rgb([h ones(m,2)]) where h is the linear ramp, h = (0:m–1)'/m.

jet

ranges from blue to red, and passes through the colors cyan, yellow, and orange. It is a variation of the hsv colormap. The jet colormap is associated with an astrophysical fluid jet simulation from the National Center for Supercomputer Applications. See Examples.

lines

produces a colormap of colors specified by the axes ColorOrder property and a shade of gray.

pink

contains pastel shades of pink. The pink colormap provides sepia tone colorization of grayscale photographs.

prism

repeats the six colors red, orange, yellow, green, blue, and violet.

spring

consists of colors that are shades of magenta and yellow.

summer

consists of colors that are shades of green and yellow.

white

is an all white monochrome colormap.

winter

consists of colors that are shades of blue and green.

you did rename 'spectral' to 'nipy_spectral', thanks!
line 26, "spectral (Spectral is not the same! rename to nipy_spectral**?**)"
implies it wasn't renamed to me, but it was renamed!

#ValueError: 'spectral' is not a valid value for name; supported values are....etc