Skip to content

DOC: briefly describe norms in general in norm guide #32231

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

Draft
story645 wants to merge 1 commit into
base: main
Choose a base branch
from
+10 −10
Draft

DOC: briefly describe norms in general in norm guide #32231

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
20 changes: 10 additions & 10 deletions galleries/users_explain/colors/colormapnorms.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,23 +7,23 @@
Colormap normalization
======================
Objects that use colormaps by default linearly map the colors in the
colormap from data values *vmin* to *vmax*. For example::
Normalization objects map data values into the colormap indexing range, and this

@timhoffm timhoffm Aug 19, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

The overall topic is still mapping data to color. IMHO we should start the introduction there and not with the Normalization part only. e.g.

Objects that use colormaps map their data to color values in a two-step process. First, Normalization objects map data values to normalized values. The transformations can be linear or non-linear, but the transformation parameters are typically chosen so that relevant values are mapped to the interval [0, 1]. The colormap then maps the values in the interval [0, 1] to actual colors. Values below 0 / above 1 are mapped to the "under" / "over" values of the colormap. Hence, to spread the relevant data range to the full colormap, the norm should map that data range to [0, 1].

@story645 story645 Aug 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Objects that use colormaps map their data to color values in a two-step process.

The point of colorizer is that theoretically this isn't totally true anymore, but I agree w/ your broader point of easing more into normalization rather than starting there.

@timhoffm timhoffm Aug 20, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

You can and it’s probably a good idea to mention colorizer. Note that it’s only a formalization of the norm+colorbar concept, not an abstraction (which would allow arbitrary mapping. From the module docstring:

The Colorizer class which handles the data to color pipeline via a normalization and a colormap.

@story645 story645 Aug 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

not an abstraction (which would allow arbitrary mapping

Discrete colorizer would be the full abstraction (in that any norm involved would be purely implementation detail of data value -> listedcolormap index -> color while most norms are data value -norm -> cmap interval range value -cmap-> cmap array index) but yeah let me think on how to write this.

@timhoffm timhoffm Aug 21, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

We currently don’t have that. The most fundamental class is Colorizer, which is built using norm+cmap. So I would not bother with further abstractions until we have them.

indexing range is determined by the choice of normalization function. Normalization
classes are defined in the :func:`matplotlib.colors` module and linear normalization
:func:`matplotlib.colors.Normalize` is the default.
Objects that use colormaps by default linearly map the data value range [*vmin*, *vmax*]
to the colormap indexing range [0, 1]. For example::
pcm = ax.pcolormesh(x, y, Z, vmin=-1., vmax=1., cmap='RdBu_r')
will map the data in *Z* linearly from -1 to +1, so *Z=0* will
give a color at the center of the colormap *RdBu_r* (white in this
case).
Matplotlib does this mapping in two steps, with a normalization from
the input data to [0, 1] occurring first, and then mapping onto the
indices in the colormap. Normalizations are classes defined in the
:func:`matplotlib.colors` module. The default, linear normalization
is :func:`matplotlib.colors.Normalize`.
Artists that map data to color pass the arguments *vmin* and *vmax* to
construct a :func:`matplotlib.colors.Normalize` instance, then call it:
Artists that map data to color pass the arguments *vmin* and *vmax* to a
:func:`.Normalize` object instantiated inside the artist. Here is an
example of explicitly creating a norm and then mapping a data value to a colormap index:
.. code-block:: pycon
Expand Down
Loading