colormaps docstring update #889

Merged
merged 7 commits into from May 31, 2012

Conversation

Projects
None yet
6 participants
@endolith
Contributor

endolith commented May 23, 2012

This is an attempt at updating the colormaps docstring to include all the new colormaps and more information about where they came from and what they're supposed to do, some of which was in comments in _cm.py, but not otherwise visible to users. (https://gist.github.com/2719900)

Warning: I don't know if I did the rst formatting correctly, if the descriptions of colormaps are totally correct, if we should also mention that the "base" colormaps are copied from Matlab, or how to properly do forks and pull requests in GitHub. :)

endolith and others added some commits May 21, 2012

some typos and small changes
("overwrite" = original file no longer exists. "override" = file still exists, but we're ignoring what it says)
Merge pull request #884 from endolith/patch-3
some typo fixes and small changes to the matplotlibrc stuff
lib/matplotlib/pyplot.py
- * summer
- * winter
- * spectral
+ matplotlib provides a number of colormaps, a complete list of which can be found in `cm._cmapnames`.

This comment has been minimized.

Show comment Hide comment
@mdboom

mdboom May 23, 2012

Member

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.

@mdboom

mdboom May 23, 2012

Member

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.

This comment has been minimized.

Show comment Hide comment
@mdboom

mdboom May 23, 2012

Member

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.

@mdboom

mdboom May 23, 2012

Member

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.

This comment has been minimized.

Show comment Hide comment
@endolith

endolith May 23, 2012

Contributor

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

@endolith

endolith May 23, 2012

Contributor

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

This comment has been minimized.

Show comment Hide comment
@pelson

pelson May 23, 2012

Member

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.

@pelson

pelson May 23, 2012

Member

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.

This comment has been minimized.

Show comment Hide comment
@pelson

pelson May 23, 2012

Member

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`.
@pelson

pelson May 23, 2012

Member

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`.

This comment has been minimized.

Show comment Hide comment
@endolith

endolith May 23, 2012

Contributor

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.

@endolith

endolith May 23, 2012

Contributor

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.

This comment has been minimized.

Show comment Hide comment
@endolith

endolith May 24, 2012

Contributor

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.

@endolith

endolith May 24, 2012

Contributor

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.

This comment has been minimized.

Show comment Hide comment
@pelson

pelson May 24, 2012

Member

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).

@pelson

pelson May 24, 2012

Member

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).

lib/matplotlib/pyplot.py
imshow(X, cmap=cm.hot)
- or 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()

This comment has been minimized.

Show comment Hide comment
@mdboom

mdboom May 23, 2012

Member

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?

@mdboom

mdboom May 23, 2012

Member

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?

This comment has been minimized.

Show comment Hide comment
@WeatherGod

WeatherGod May 23, 2012

Member

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

@WeatherGod

WeatherGod May 23, 2012

Member

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

This comment has been minimized.

Show comment Hide comment
@endolith

endolith May 23, 2012

Contributor

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?

@endolith

endolith May 23, 2012

Contributor

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?

This comment has been minimized.

Show comment Hide comment
@f0k

f0k May 23, 2012

Contributor

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.

@f0k

f0k May 23, 2012

Contributor

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.

@mdboom

This comment has been minimized.

Show comment Hide comment
@mdboom

mdboom May 23, 2012

Member

This looks great. The rst formatting seems to be fine. Hop on the mailing list if you're having trouble building the docs -- I or others can help.

It would be awesome to also include the show_colormaps example inline here in the docstring. A picture is worth a thousand words for this stuff after all.

Member

mdboom commented May 23, 2012

This looks great. The rst formatting seems to be fine. Hop on the mailing list if you're having trouble building the docs -- I or others can help.

It would be awesome to also include the show_colormaps example inline here in the docstring. A picture is worth a thousand words for this stuff after all.

@WeatherGod

This comment has been minimized.

Show comment Hide comment
@WeatherGod

WeatherGod May 23, 2012

Member

This is excellent work. Thank you for putting the time in for doing this!

Member

WeatherGod commented May 23, 2012

This is excellent work. Thank you for putting the time in for doing this!

lib/matplotlib/pyplot.py
+ 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:

This comment has been minimized.

Show comment Hide comment
@pelson

pelson May 23, 2012

Member

Ideally we would like to get line widths <= 80 characters for smaller screens, would you mind putting newlines through this and other long lines.

@pelson

pelson May 23, 2012

Member

Ideally we would like to get line widths <= 80 characters for smaller screens, would you mind putting newlines through this and other long lines.

@pelson

This comment has been minimized.

Show comment Hide comment
@pelson

pelson May 23, 2012

Member

@endolith great stuff! The more people contributing to the documentation the better we can get it.

@ mpl devs: As far as I can see it, this would be suitable to go into 1.1.x. Maybe we should spark off another issue which implements the syntax discussed for setting a default palette instead of the plt.jet() / plt.hot() style syntax?

Member

pelson commented May 23, 2012

@endolith great stuff! The more people contributing to the documentation the better we can get it.

@ mpl devs: As far as I can see it, this would be suitable to go into 1.1.x. Maybe we should spark off another issue which implements the syntax discussed for setting a default palette instead of the plt.jet() / plt.hot() style syntax?

@mdboom

This comment has been minimized.

Show comment Hide comment
@mdboom

mdboom May 23, 2012

Member

See #896. Directly relevant to the discussion here.

Member

mdboom commented May 23, 2012

See #896. Directly relevant to the discussion here.

lib/matplotlib/pyplot.py
+ 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,

This comment has been minimized.

Show comment Hide comment
@efiring

efiring May 27, 2012

Member

You might replace the parenthetical explanation by saying, "...meant to be used for cyclic variables such wind direction or time of day",

@efiring

efiring May 27, 2012

Member

You might replace the parenthetical explanation by saying, "...meant to be used for cyclic variables such wind direction or time of day",

This comment has been minimized.

Show comment Hide comment
@endolith

endolith May 27, 2012

Contributor

ok, that makes sense.

"meant for plotting cyclic values that wrap around at the endpoints, such as wind direction or time of day"?

that could actually be a 4th category, couldn't it? I got the 3 categories from colorbrewer documentation, but they don't have any cyclic ones. any idea what the flag and prism maps are meant for?

@endolith

endolith May 27, 2012

Contributor

ok, that makes sense.

"meant for plotting cyclic values that wrap around at the endpoints, such as wind direction or time of day"?

that could actually be a 4th category, couldn't it? I got the 3 categories from colorbrewer documentation, but they don't have any cyclic ones. any idea what the flag and prism maps are meant for?

This comment has been minimized.

Show comment Hide comment
@efiring

efiring May 27, 2012

Member

Flag and prism might be used as alternatives for ordinary line contours, primarily giving a sense of shapes and gradients; but I suspect they are rarely used at all. Matlab has them, so we do too, for better or worse.

@efiring

efiring May 27, 2012

Member

Flag and prism might be used as alternatives for ordinary line contours, primarily giving a sense of shapes and gradients; but I suspect they are rarely used at all. Matlab has them, so we do too, for better or worse.

This comment has been minimized.

Show comment Hide comment
@endolith

endolith May 31, 2012

Contributor

Ok, I added a description of cyclic as a separate scheme

@endolith

endolith May 31, 2012

Contributor

Ok, I added a description of cyclic as a separate scheme

lib/matplotlib/pyplot.py
+ winter shades of blue-green
+ spectral black-purple-blue-green-yellow-red-white spectrum
+ ========= =======================================================
+

This comment has been minimized.

Show comment Hide comment
@efiring

efiring May 27, 2012

Member

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).

@efiring

efiring May 27, 2012

Member

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).

This comment has been minimized.

Show comment Hide comment
@endolith

endolith May 27, 2012

Contributor

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

@endolith

endolith May 27, 2012

Contributor

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

This comment has been minimized.

Show comment Hide comment
@efiring

efiring May 27, 2012

Member

"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.

@efiring

efiring May 27, 2012

Member

"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.

This comment has been minimized.

Show comment Hide comment
@endolith

endolith May 31, 2012

Contributor

Added

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

@endolith

endolith May 31, 2012

Contributor

Added

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

+ * Set1
+ * Set2
+ * Set3
+

This comment has been minimized.

Show comment Hide comment
@efiring

efiring May 27, 2012

Member

You might want to note here or elsewhere (footnote?) that the qualitative schemes here are illustrative, and that ordinarily they should be generated as discrete maps for the particular number of colors needed, not at quasi-continuous maps. You could even include a reference to the colors.ListedColormap class.

@efiring

efiring May 27, 2012

Member

You might want to note here or elsewhere (footnote?) that the qualitative schemes here are illustrative, and that ordinarily they should be generated as discrete maps for the particular number of colors needed, not at quasi-continuous maps. You could even include a reference to the colors.ListedColormap class.

This comment has been minimized.

Show comment Hide comment
@endolith

endolith May 27, 2012

Contributor

This is issue #881, for others' reference. Maybe we should "soft deprecate" them by saying they don't really belong here and shouldn't be used? Like gist_gray is identical to gray and should never have existed, so I just list it as "identical to gray". should I go a step further and say "deprecated, use gray instead"?

@endolith

endolith May 27, 2012

Contributor

This is issue #881, for others' reference. Maybe we should "soft deprecate" them by saying they don't really belong here and shouldn't be used? Like gist_gray is identical to gray and should never have existed, so I just list it as "identical to gray". should I go a step further and say "deprecated, use gray instead"?

This comment has been minimized.

Show comment Hide comment
@efiring

efiring May 27, 2012

Member

I like those suggestions. Maintaining truly bad and/or duplicate colormaps forever is just bad housekeeping, so putting them on a deprecation path makes sense, even if ends up being years before they actually disappear.

@efiring

efiring May 27, 2012

Member

I like those suggestions. Maintaining truly bad and/or duplicate colormaps forever is just bad housekeeping, so putting them on a deprecation path makes sense, even if ends up being years before they actually disappear.

This comment has been minimized.

Show comment Hide comment
@endolith

endolith May 31, 2012

Contributor

Ok, I moved the redundant grayscales into their own section and discouraged them, and added a note to the qualitative section.

@endolith

endolith May 31, 2012

Contributor

Ok, I moved the redundant grayscales into their own section and discouraged them, and added a note to the qualitative section.

mention matlab origin, add cyclic description, describe ColorBrewer s…
…chemes, discourage use of qualitative and redundant schemes, change some details based on luminance plots

efiring added a commit that referenced this pull request May 31, 2012

Merge pull request #889 from endolith/patch-4
colormaps docstring update

@efiring efiring merged commit 72c7887 into matplotlib:master May 31, 2012

@endolith endolith deleted the endolith:patch-4 branch Feb 25, 2013

endolith added a commit to endolith/matplotlib that referenced this pull request Dec 7, 2013

Remove redundant colormaps from examples
`gist_yarg`, `gist_gray`, and `binary` are identical to `gray`, so they are "on a deprecation path", and `spectral` was renamed to `nipy_spectral` to avoid conflicts with `Spectral`

matplotlib#889
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment