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
make colormaps() return a list of all colormaps
  • Loading branch information
@endolith
endolith committed May 24, 2012
commit 11590e64b46704388e7b9e60d31be7609b13a796
46 changes: 28 additions & 18 deletions lib/matplotlib/pyplot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1645,33 +1645,40 @@ 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, 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.

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::
or post-hoc 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()
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.

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

Expand Down Expand Up @@ -1725,8 +1732,9 @@ def colormaps():
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 @@ -1775,7 +1783,7 @@ def colormaps():
Other miscellaneous schemes:

========= =======================================================
Colormap Description
Colormap Description
========= =======================================================
afmhot sequential black-orange-yellow-white blackbody
spectrum, commonly used in atomic force microscopy
Expand Down Expand Up @@ -1819,14 +1827,16 @@ def colormaps():
<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.
<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>`_
.. [#] 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
return sorted(cm.cmap_d.keys())


## Plotting part 1: manually generated functions and wrappers ##
Expand Down