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
Next Next commit
wrap lines to <= 80 characters
  • Loading branch information
@endolith
endolith committed May 23, 2012
commit d87156fa710bbd2004691bbfbede735bd89b87e8
39 changes: 27 additions & 12 deletions lib/matplotlib/pyplot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1645,14 +1645,16 @@ def colors():

def colormaps():
"""
matplotlib provides a number of colormaps, a complete list of which can be found in `cm._cmapnames`.
matplotlib provides a number of colormaps, a complete list of which can
be found in `cm._cmapnames`.

Copy link
Member

Choose a reason for hiding this comment

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

As an identifier with a _ prefix is supposed to be private, by Python convention, we probably shouldn't recommend using it in the docs. I think we should add a public alias for this and then recommend using the that in the docs.

Copy link
Member

Choose a reason for hiding this comment

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

Looking at this again, I don't see why this very function colormap couldn't be used to return a list of colormap names. This function currently only exists for documentation.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Making colormaps() return a list of colormaps seems pretty logical to me.

Copy link
Member

Choose a reason for hiding this comment

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

I would probably get all the colormaps with:

import matplotlib.cm as cm
print cm.cmap_d.keys()

But having a pyplot function which returns a list of cmap names sounds sensible.

Copy link
Member

Choose a reason for hiding this comment

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

Additionally, it would be nice to use full sphinx cross linking here (even if the thing you are linking to is not documented). e.g.

... which can be found in :class:`~matplotlib.cm.cmap_d`.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Well, cm.cmap_d.keys() and cm.datad.keys() both include all the reversed names like gray_r, which is probably not desirable for printing? _cmapnames is created from datad before it gets the reversed names added to it, so I used that. Didn't realize it shouldn't be exposed to the user like that, though.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

On the other hand, if you use register_cmap(), the new colormap shows up in cmap_d.keys(), but not in datad.keys() or _cmapnames, so cmap_d.keys() seems like the right answer. I guess showing the _r colormaps too is legitimate, since ones you create with register_cmap don't have any _r version.

Copy link
Member

Choose a reason for hiding this comment

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

Sounds like you are turning over some stones and finding some interesting "features". It might be worth putting some comments/attribute docstrings in matplotlib.cm at the datad, _cmapnames and cmap_d variables. Additionally, some of these inconsistencies might be improved by making the default colormaps go through the register_cmap function rather than have them modify the data structures directly (but that is a bigger change, and I can't guarantee that it is entirely sensible).

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::
Additionally, for the "base" colormaps below, you can set the colormap
post-hoc using the corresponding pylab interface function::

imshow(X)
hot()
Copy link
Member

Choose a reason for hiding this comment

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

I'm not a fan of the inconsistency of some colormaps being available this way and others not. On the other hand, I don't know if we want to pollute the pyplot namespace further by adding more colormaps there. It might be nice to have something like:

colormap('hot')

work. What do others think?

Copy link
Member

Choose a reason for hiding this comment

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

And that function could be used to set an rcparam for default colormap...

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I had the same thoughts. The post-hoc functions are copied from Matlab (except spectral()), but Matplotlib has a lot more built-in colormaps now, so it wouldn't make sense to give them all functions.

Maybe something shorter like cmap('hot'), since it's primarily used interactively?

Copy link
Contributor

Choose a reason for hiding this comment

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

There is pyplot.set_cmap('hot') for exactly that purpose. Given that nobody thought of this, it should definitely be mentioned in the colormaps docstring as well :) (Note: Its implementation is currently broken, but Issue #896 will fix this.)
/edit: Both the shortcut functions (hot(), jet() etc.) and set_cmap(...) do not only work post-hoc, but also "pre-hoc", as an alternative to the cmap keyword parameter.
/edit2: I always preferred those because cmap is documented to only accept colors.Colormap instances, which I thought needed an extra import (I did not notice pylab.cm already gives access to those, maybe it wasn't mentioned in the matplotlib 0.99 docstrings). However, as I just found out, cmap also accepts strings, so imshow, imsave and any other function documenting the cmap keyword argument need a docstring update as well! Would be great if you could include this in your pull request while you're at it.

Expand All @@ -1667,7 +1669,8 @@ def colormaps():
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
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:
Expand Down Expand Up @@ -1702,7 +1705,8 @@ def colormaps():
========= =======================================================

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
package <http://yorick.sourceforge.net/index.php>`_, an evolution of the GIST package, both by David H. Munro:
package <http://yorick.sourceforge.net/index.php>`_, an evolution of
the GIST package, both by David H. Munro:

============ =======================================================
Colormap Description
Expand All @@ -1712,13 +1716,17 @@ def colormaps():
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_stern "Stern special" color table from Interactive Data Language software
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_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 <http://colorbrewer.org>`_ color specifications and designs developed by Cynthia Brewer:
The following 34 colormaps are based on the `ColorBrewer <http://colorbrewer.org>`_
color specifications and designs developed by Cynthia Brewer:

Diverging:

Expand Down Expand Up @@ -1802,13 +1810,20 @@ def colormaps():

.. 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>`_
.. [#] 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 <http://www.ncl.ucar.edu/Document/Graphics/color_table_gallery.shtml>`_
.. [#] Resembles "BkBlAqGrYeOrReViWh200" from `Color Table Gallery
<http://www.ncl.ucar.edu/Document/Graphics/color_table_gallery.shtml>`_

.. [#] See `Diverging Color Maps for Scientific Visualization <http://www.cs.unm.edu/~kmorel/documents/ColorMaps/>`_ by Kenneth Moreland.
.. [#] See `Diverging Color Maps for Scientific Visualization
<http://www.cs.unm.edu/~kmorel/documents/ColorMaps/>`_ by Kenneth Moreland.

.. [#] See `A Color Map for Effective Black-and-White Rendering of Color-Scale Images <http://www.mathworks.com/matlabcentral/fileexchange/2662-cmrmap-m>`_ by Carey Rappaport
.. [#] See `A Color Map for Effective Black-and-White Rendering of Color-Scale
Images <http://www.mathworks.com/matlabcentral/fileexchange/2662-cmrmap-m>`_
by Carey Rappaport

"""
pass
Expand Down