Skip to content

Add deprecation for colormaps #20853

Closed
Closed
@QuLogic

Description

@QuLogic

This is tracking for the next stage of the colormap registry, pulled out of the original PR so that it doesn't get lost. (Originally written by @timhoffm)

Overall goal

The registry is a more natural structure for managing colormaps. We have data and corresponding functions that are tightly related. IMHO it's a much nicer API for the user and easier to extend. And we get rid of some API quirks in the functions like get_cmap(.. lut=...) or the parameter order register_cmap(name, cmap) where name is optional.

Target state

  • the matplotlib.cm colormap functions should eventually be removed:
    • matplotlib.cm.register_cmap(...) - use mpl.colormaps.register(...) instead
    • matplotlib.cm.unregister_cmap(...) - use mpl.colormaps.unregister(...) instead
    • matplotlib.cm.get_cmap(name) - use mpl.colormaps[name] instead, followed by .resampled() if needed to cover get_cmap(lut=...).
  • I'm open for discussion if we keep the pyplot functions or replace them with the registry as well. Suggestion on pyplot:
    • eventually remove plt.register_cmap - use mpl.colormaps.register(...) instead. - This is a fundamental operation and IMHO beyond the scope of pyplot
    • keep plt.get_cmap() - This is too widely used to be removed. But eventually remove its lut parameter in favor of plt.get_cmap().resampled().

Transition path

While I would like to eventually remove the matplotlib.cm functions, I propose a prolonged transition path because they are quite fundamental functions also used in third party libraries:

  • For 3.5: introduce the registry as is in this PR; discourage the cm functions. This is to see if we have missed something important in the design and get user feedback. - Maybe we should declare the registry experimental.
  • For 3.6: Introduce a pending deprecation on all functions that we want to eventually remove. This is the time where all downstream libraries should start switching to using the registry.
  • For 3.7 (or later): Deprecate all the functions we want to remove.
  • For 3.9 (or later): Remove all the functions we want to remove.

I strongly advocate to introduce this PR in 3.5. If everything goes well, we don't need modifications (only extensions) to the registry, which means that downstream libraries would have 3.5 as a minimum dependency when they switch to the registry.

On read-only colormaps

The registry colormap access already returns copies of the colormaps and by that implements the change to get_cmap, which is scheduled to take effect in 3.6 (#19766). He can be quicker here, because the new API does not have to maintain backward compatibility for the deprecation period.
Other than that, the registry is independent of cmap mutability.

Originally posted by @timhoffm in #18503 (comment)

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions