DOC: briefly describe norms in general in norm guide - #32231
Conversation
github-actions
Bot
added
the
Documentation: user guide
| 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 |
There was a problem hiding this comment.
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,
Normalizationobjects 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].
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
|
I think going from concrete and the default most people will already be familiar with to the more abstract is more useful than starting with the abstraction. I think that is what the original did, though no doubt it could be better worded. |
I think the document should signpost/introduce what the whole document is about before jumping into the specifics. My experience broadly is that it helps orient people to tell them what I'm showing them examples of before I show them examples. ETA: Also it's just defining terms before they get used. |
3 participants
PR summary
Added a sentence and moved things around to briefly explain what norms are/do before getting into examples.
AI Disclosure
nope
PR quality check