Update colormap usage documentation to prioritize string colormap names #29028

Kaustbh · 2024-10-27T20:04:11Z

This update suggests using string colormap names directly for cmap arguments due to their readability and ease of use. The update also recommends plt.colormaps[name] to retrieve colormap instances, offering a scalable approach that supports both built-in and user-registered colormaps.

timhoffm

@Kaustbh Sorry, I have not been clear on the intended change in #28915.

With the recommendation

So the recommendation would be:

Use str colormap names on cmap arguments.

Use plt.colormaps[name] to get the colormap instance.

I primarily intended to change the way we access colormaps in the documentation; i.e. demonstrate by example. The concrete action is: "Go through our docs and apply these rules."

I'm a bit torn whether it's worth to spell the recommendations out explicitly for the user. While it gives direction, it's one more think to read/learn. Also, there's no canonical place to put that recommendation. It certainly does not belong in the diverging_colormaps what's new entry - that link was only where I saw the plt.cm* use.

Kaustbh · 2024-10-28T03:42:59Z

Okay, I will give it a try.

Kaustbh · 2024-12-03T17:28:42Z

Hi @timhoffm while going through the documentation I saw an example, https://matplotlib.org/stable/gallery/mplot3d/imshow3d.html#sphx-glr-gallery-mplot3d-imshow3d-py, in this example code,
we are using colors = plt.get_cmap(cmap)(norm(array)), when I changed it to colors = plt.colormaps[cmap](norm(array)), I was getting the error,

raise KeyError(f"{item!r} is not a known colormap name") from None

KeyError: 'None is not a known colormap name'

which caused because we are having cmap=None in the imshow3d function, how should I solve this problem.
And should I work on changing all the occurences in the docs?

timhoffm · 2024-12-03T18:28:29Z

Please leave this as is for this PR - it’s off-topic.

(General note: plt.get_cmap() will continue to be valid and is an alias of matplotlib.colormaps.get_cmap(), which in contrast to item access resolves None to the default colormap.)

Kaustbh · 2024-12-03T20:10:00Z

Thank you for the clarification! I understand that plt.get_cmap() will remain valid and resolve None to the default colormap. I wanted to confirm: should I proceed with replacing all occurrences of plt.cm.* with the recommended syntax (cmap="name" or plt.colormaps[name]) as part of this PR?

timhoffm · 2024-12-03T20:32:42Z

should I proceed with replacing all occurrences of plt.cm.* with the recommended syntax (cmap="name" or plt.colormaps[name]) as part of this PR?

Yes.

Kaustbh · 2024-12-08T08:27:18Z

I have made the commit please review and suggest me any changes.

lib/matplotlib/tests/test_image.py

galleries/users_explain/colors/colorbar_only.py

galleries/examples/specialty_plots/leftventricle_bullseye.py

galleries/examples/specialty_plots/advanced_hillshading.py

galleries/examples/showcase/mandelbrot.py

galleries/examples/images_contours_and_fields/layer_images.py

galleries/examples/images_contours_and_fields/contourf_demo.py

doc/users/next_whats_new/diverging_colormaps.rst

timhoffm

Almost good to go. Please still fix the flake8/precommit errors. - The failing test on OSX is unrelated.

timhoffm · 2024-12-14T08:17:54Z

Pre commit isort fails. I don’t see directly what is wrong in the code. Can you please check what code changes it suggests?

QuLogic · 2024-12-17T00:20:09Z

Why are 132 files changed? Please don't changed unrelated files.

Kaustbh · 2024-12-17T05:04:54Z

I think it happened because of isort . command, can you please tell how can I fix this?

timhoffm · 2024-12-17T08:33:41Z

I assume, you have triggered isort locally and added all changes it has found? While I don't know why there are that many changes (maybe an update to isort?) these should not be part of this PR. We only want changes that are necessary in the context of this PR.

Before your last force-push there have been two or three isort errors in the precommit action. Please do the following:

go back to that state (use git reflog if necessary)
apply only the necessary isort changes for this PR. To do so, either:
- force push the old version again to see what the original error was, only run isort on the mentioned files
- run isort on the changed files in your commit. - Likely the simplest way to do this is to setup precommit locally https://matplotlib.org/devdocs/devel/development_setup.html#install-pre-commit-hooks

rcomer · 2024-12-17T12:49:10Z

pre-commit is configured to only run isort on three galleries

matplotlib/.pre-commit-config.yaml

Lines 63 to 68 in f8900ea

    
           - repo: https://github.com/pycqa/isort 
        
             rev: 5.13.2 
        
             hooks: 
        
               - id: isort 
        
                 name: isort (python) 
        
                 files: ^galleries/tutorials/|^galleries/examples/|^galleries/plot_types/

rcomer · 2024-12-19T16:59:46Z

If I have understood, all your deliberate changes are under galleries and all your non-deliberate changes are under lib. If that is correct, I think you can revert without resorting to reflogs:

git checkout HEAD~1 lib

This checks out the lib directory from the commit before the current one (HEAD~1).

galleries/examples/lines_bars_and_markers/multivariate_marker_plot.py

galleries/examples/specialty_plots/leftventricle_bullseye.py

lib/matplotlib/tests/test_colors.py

Kaustbh · 2025-01-03T05:56:35Z

@QuLogic can you please approve this PR or are there any changes to be made?

Kaustbh · 2025-01-11T05:59:26Z

Hi @QuLogic, I hope you're doing well. I am following up on my previous message regarding this PR. Please let me know if there are any changes I should make or if they are ready for approval. Thanks for your time!

QuLogic · 2025-01-11T08:20:29Z

This will also need a rebase to fix the conflicts.

Kaustbh · 2025-01-13T16:53:09Z

@QuLogic please check the commit.

QuLogic · 2025-01-14T00:20:12Z

The comments on galleries/examples/specialty_plots/leftventricle_bullseye.py remain relevant still.

QuLogic

Looks good now.

timhoffm reviewed Oct 27, 2024

View reviewed changes

timhoffm added the status: needs revision label Nov 5, 2024

Kaustbh force-pushed the issue3 branch from d3ee967 to e05731d Compare December 8, 2024 08:25

github-actions bot added topic: mplot3d Documentation: plot types files in galleries/plot_types Documentation: examples files in galleries/examples labels Dec 8, 2024

Kaustbh requested a review from timhoffm December 8, 2024 08:25

timhoffm reviewed Dec 9, 2024

View reviewed changes

Kaustbh force-pushed the issue3 branch from e05731d to e495f8b Compare December 11, 2024 15:42

Kaustbh requested a review from timhoffm December 11, 2024 15:43

timhoffm removed the status: needs revision label Dec 11, 2024

timhoffm reviewed Dec 11, 2024

View reviewed changes

Kaustbh force-pushed the issue3 branch from e495f8b to 06b2fe9 Compare December 12, 2024 19:53

Kaustbh requested a review from timhoffm December 12, 2024 19:54

Kaustbh force-pushed the issue3 branch from 06b2fe9 to da573f7 Compare December 15, 2024 16:57

github-actions bot added the status: needs rebase label Dec 20, 2024

Kaustbh force-pushed the issue3 branch from da573f7 to 99629bb Compare December 22, 2024 17:45

github-actions bot removed the topic: mplot3d label Dec 22, 2024

github-actions bot removed the status: needs rebase label Dec 22, 2024

Kaustbh force-pushed the issue3 branch from 99629bb to 72a37b8 Compare December 22, 2024 18:34

github-actions bot added the topic: mplot3d label Dec 22, 2024

QuLogic requested changes Dec 24, 2024

View reviewed changes

timhoffm reviewed Dec 29, 2024

View reviewed changes

lib/matplotlib/tests/test_colors.py Outdated Show resolved Hide resolved

lib/matplotlib/tests/test_colors.py Outdated Show resolved Hide resolved

Kaustbh force-pushed the issue3 branch from 72a37b8 to 790add8 Compare December 30, 2024 17:39

Kaustbh requested a review from timhoffm December 30, 2024 17:40

timhoffm approved these changes Dec 31, 2024

View reviewed changes

Kaustbh requested a review from QuLogic December 31, 2024 04:33

github-actions bot added the status: needs rebase label Jan 3, 2025

Kaustbh force-pushed the issue3 branch from 790add8 to 886cac4 Compare January 11, 2025 20:05

github-actions bot added Documentation: user guide files in galleries/users_explain or doc/users and removed status: needs rebase labels Jan 11, 2025

Update colormap usage documentation to prioritize string colormap names

191efce

Kaustbh force-pushed the issue3 branch from 886cac4 to 191efce Compare January 14, 2025 15:07

QuLogic approved these changes Jan 15, 2025

View reviewed changes

QuLogic merged commit 9cc62f1 into matplotlib:main Jan 15, 2025
39 checks passed

QuLogic added this to the v3.11.0 milestone Jan 15, 2025

Uh oh!

Update colormap usage documentation to prioritize string colormap names #29028

Update colormap usage documentation to prioritize string colormap names #29028

Uh oh!

Conversation

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!