Repository navigation
DivergingNorm is a misleading name #15336
Description
DivergingNorm was introduced when #12419 was merged. Discussion of #15333 on the Sept. 24, 2019 call led to the conclusion that the "DivergingNorm" name was an unfortunate and misleading choice. We need to select a better name ASAP, preferably before the 3.2 release, so that DivergingNorm can be deprecated and replaced before it is in wide use.
Activity
timhoffm commented on Sep 25, 2019
I habe a bit of a hard time finding a good name. Best so far is:
The original DivergingNorm came from here: #4666 (comment)
Maybe it would be best to actually implement a more general PiecewiseLinearNorm(vlimits).
DivergingNorm(vmin=-2, vcenter=0, vmax=7)
would then be
for the list, we would divide the [0...1] range into equal segments to determine the target value of a given limit.
If the generalization seems too complicated for 3.2, we could still add the PiecewiseLinearNorm() with a restriction that it currently does only support three values [vmin, vcenter, vmax] (NotImplementedError for everything else). That way, we could already deprecate DivergingNorm and redirect its users to PiecewiseLinearNorm while continuing to use the DivergingNorm code under the hood. We can then later rewrite the logic to be more general for 3.3 without breaking user code that already switched to the special case PiecewiseLinearNorm([vmin, vcenter, vmax]).
efiring commented on Sep 25, 2019
Another candidate for a name is "BentNorm".
Regarding PiecewiseLinearNorm, see #4666 and #5061.
jklymak commented on Sep 26, 2019
I called it MidPointNorm here: https://matplotlib.org/tutorials/colors/colormapnorms.html#custom-normalization-manually-implement-two-linear-ranges
Or OffsetNorm at some other point.
jklymak commented on Sep 26, 2019
I'd be OK with a general PiecewiseLinearNorm if someone had a good example of why it would be useful to have more than two linear ramps
ImportanceOfBeingErnest commented on Sep 26, 2019
In 2011 @Tillsten wrote MidPointNorm in https://stackoverflow.com/a/7746125/4124317 which seems to be the earliest version of what is now known as DivergingNorm.
In 2013 @joferkington simplified this and called it MidpointNormalize in https://stackoverflow.com/a/20146989/4124317
In 2014 @phobson Created a PR with a mixture of both solutions under the name OffsetNorm.
This was taken over by @dopplershift in #4666 under the name PiecewiseLinearNorm. Within this thread @jkseppan came up with the name DivergingNorm
@tacaswell was "sold on Diverging Norm" (2015)
which led to @jkseppan bringing in #5054 with that name.
That has gone stale, until being picked up in #12419 by @jklymak, not changing the name that was previously agreed upon.
I'm summarizing this here such that discussion wouldn't need rerun through the same circles it already has years ago.
Also I would like to mention that there are already a few stackoverflow answers actively using DivergingNorm around, so deprecation would surely hit some people.
timhoffm commented on Sep 26, 2019
Example usecases for PiecewiseLinearNorm with more than two segments.
@jklymak PiecewiseLinearNorm with more than two segments could be useful for data with large ranges but important features in small ranges. For example
could be tuned in a way that the large part of the colormap describes the scale [-1, 1], but you keep some range for [-10, 1] and [1, 10].
Also, if you know to have data more or less at different levels such as (cross-section)
You could increase the sensitivity around -1 and 1 and shrink the color range used for the uninteresting [-0.9, 0.9] data.
jklymak commented on Sep 26, 2019
I deal with "red" data sets like that all the time. For something like that, I think its preferable to solve the problem via analysis (typically filtering), rather than fiddle with a very non-traditional color mappings. Just think about the figure caption you'd have to include with a plot like that: "Note that the colormapping has three linear ramps, the first from -1.2 to -0.8 encompassing 1/3 of the colors, the second from -0.8 to 0.8 encompassing the second third, and the third from 0.8 to 1.2 encompassing the last third of the colormap". I think it'd get a rough time in review.
But, if you want to take a crack at making PiecewiseLinearNorm work, that'd probably be fine. There were lots of complaints about various design decisions, etc etc, so its a tough row to hoe.
efiring commented on Sep 26, 2019
Minor note on nomenclature: PiecewiseLinearNorm probably should be called LinearSplineNorm unless it allows discontinuities. I haven't checked, but I think the various versions in PRs for these things have all been continuous.
timhoffm commented on Sep 27, 2019
efiring commented on Oct 1, 2019
@timhoffm would you like to put in a PR to deprecate the DivergingNorm name and replace it with TwoSlopeNorm? Or would you prefer that I do it?
tacaswell commented on Oct 19, 2019
@ImportanceOfBeingErnest Thank you for your very through tracing through the history of this discussion!
API: rename DivergingNorm to TwoSlopeNorm
API: rename DivergingNorm to TwoSlopeNorm