Skip to content

DOC: colormaps docstring update #889

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
May 31, 2012
Merged

DOC: colormaps docstring update #889

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7ee65ef
typo
endolith May 21, 2012
ceff6f3
some typos and small changes
endolith May 21, 2012
fbbf5bb
Merge pull request #884 from endolith/patch-3
efiring May 22, 2012
73fb325
update colormaps docstring with more maps, their origins and purposes…
endolith May 23, 2012
d87156f
wrap lines to <= 80 characters
endolith May 23, 2012
11590e6
make colormaps() return a list of all colormaps
endolith May 24, 2012
cce4441
mention matlab origin, add cyclic description, describe ColorBrewer s…
endolith May 31, 2012
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
mention matlab origin, add cyclic description, describe ColorBrewer s… 
…chemes, discourage use of qualitative and redundant schemes, change some details based on luminance plots
  • Loading branch information
@endolith
endolith committed May 31, 2012
commit cce444103c12b6b39473f4d2dfa562ce14b3dbf9
202 changes: 118 additions & 84 deletions lib/matplotlib/pyplot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
========= =======================================================

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems it would be more fair to acknowledge here that all but the last are designed to match their Matlab counterparts, or something to that effect (if that is the case).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah they're all copied from matlab except spectral, but I wasn't sure if that should be mentioned or not. any ideas for wording? they are also used in other things like h5utils, but, again, copied from matlab. http://ab-initio.mit.edu/wiki/index.php/Color_tables_in_h5topng

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"With the exception of spectral, the above colormaps are based on those of the same name provided by Matlab."

I don't know how they were derived or extracted; alternative wording suggestions are welcome.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added

"The base colormaps are (with the exception of spectral) derived from those of the same name provided with Matlab:"

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:

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down