diff --git a/doc/users/customizing.rst b/doc/users/customizing.rst index fe78adeda2b3..de5716ac3ff1 100644 --- a/doc/users/customizing.rst +++ b/doc/users/customizing.rst @@ -24,7 +24,7 @@ locations, in the following order: is something like :file:`/usr/lib/python2.5/site-packages` on Linux, and maybe :file:`C:\\Python25\\Lib\\site-packages` on Windows. Every time you install matplotlib, this file will be overwritten, so if you want your - customizations to be saved, please move this file to you :file:`.matplotlib` + customizations to be saved, please move this file to your :file:`.matplotlib` directory. To display where the currently active :file:`matplotlibrc` file was diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 5171dbe0b0e2..0ed23dffdab2 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -1645,39 +1645,232 @@ def colors(): def colormaps(): """ - matplotlib provides the following colormaps. - - * autumn - * bone - * cool - * copper - * flag - * gray - * hot - * hsv - * jet - * pink - * prism - * spring - * summer - * winter - * spectral + Matplotlib provides a number of colormaps, and others can be added using + :func:`register_cmap`. This function documents the built-in colormaps, + and will also return a list of all registered colormaps if called. You can set the colormap for an image, pcolor, scatter, etc, - either as a keyword argument:: + using a keyword argument:: imshow(X, cmap=cm.hot) - or post-hoc using the corresponding pylab interface function:: + or using the :func:`set_cmap` function:: + + imshow(X) + pyplot.set_cmap('hot') + pyplot.set_cmap('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 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 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 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 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 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 + ========= ======================================================= + + 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() - In interactive mode, this will update the colormap allowing you to - see which one works best for your data. - """ - pass + The next set of 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_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 + ============ ======================================================= + + The following colormaps are based on the `ColorBrewer + `_ color specifications and designs developed by + Cynthia Brewer: + + 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 + * 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 + 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 [#]_ + 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." [#]_ + 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 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 + `_ + + .. [#] Resembles "BkBlAqGrYeOrReViWh200" from NCAR Command + Language. See `Color Table Gallery + `_ + + .. [#] See `Diverging Color Maps for Scientific Visualization + `_ by Kenneth + Moreland. + + .. [#] See `A Color Map for Effective Black-and-White Rendering of + Color-Scale Images + `_ + by Carey Rappaport + + """ + return sorted(cm.cmap_d.keys()) ## Plotting part 1: manually generated functions and wrappers ## diff --git a/matplotlibrc.template b/matplotlibrc.template index d5baf3b73c7b..bf293447703a 100644 --- a/matplotlibrc.template +++ b/matplotlibrc.template @@ -3,9 +3,9 @@ # This is a sample matplotlib configuration file - you can find a copy # of it on your system in # site-packages/matplotlib/mpl-data/matplotlibrc. If you edit it -# there, please note that it will be overridden in your next install. +# there, please note that it will be overwritten in your next install. # If you want to keep a permanent local copy that will not be -# over-written, place it in HOME/.matplotlib/matplotlibrc (unix/linux +# overwritten, place it in HOME/.matplotlib/matplotlibrc (unix/linux # like systems) and C:\Documents and Settings\yourname\.matplotlib # (win32 systems). # @@ -40,7 +40,7 @@ backend : %(backend)s # "pyqt" and "pyside". The "pyqt" setting has the side effect of # forcing the use of Version 2 API for QString and QVariant. -# if you are runing pyplot inside a GUI and your backend choice +# if you are running pyplot inside a GUI and your backend choice # conflicts, we will automatically try to find a compatible one for # you if backend_fallback is True #backend_fallback: True @@ -220,8 +220,8 @@ backend : %(backend)s # For example, use ',' as a decimal # separator in the fr_FR locale. #axes.unicode_minus : True # use unicode for the minus symbol - # rather than hypen. See - # http://en.wikipedia.org/wiki/Plus_sign + # rather than hyphen. See + # http://en.wikipedia.org/wiki/Plus_and_minus_signs#Character_codes #axes.color_cycle : b, g, r, c, m, y, k # color cycle for plot lines # as list of string colorspecs: # single letter, long name, or @@ -265,7 +265,7 @@ backend : %(backend)s #legend.numpoints : 2 # the number of points in the legend line #legend.fontsize : large #legend.pad : 0.0 # deprecated; the fractional whitespace inside the legend border -#legend.borderpad : 0.5 # border whitspace in fontsize units +#legend.borderpad : 0.5 # border whitespace in fontsize units #legend.markerscale : 1.0 # the relative size of legend markers vs. original # the following dimensions are in axes coords #legend.labelsep : 0.010 # deprecated; the vertical space between the legend entries @@ -288,7 +288,7 @@ backend : %(backend)s #figure.facecolor : 0.75 # figure facecolor; 0.75 is scalar gray #figure.edgecolor : white # figure edgecolor -# The figure subplot parameters. All dimensions are fraction of the +# The figure subplot parameters. All dimensions are a fraction of the # figure width or height #figure.subplot.left : 0.125 # the left side of the subplots of the figure #figure.subplot.right : 0.9 # the right side of the subplots of the figure