DivergingNorm is a misleading name

[efiring]

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.

[timhoffm]

I habe a bit of a hard time finding a good name. Best so far is:

• TwoSlopeNorm.

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

• PiecewiseLinearNorm([-2, 0, 7]) and/or
• PiecewiseLinearNorm({-2: 1, 0: 0.5, 7: 1})

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]

Another candidate for a name is "BentNorm".
Regarding PiecewiseLinearNorm, see #4666 and #5061.

[jklymak]

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]

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]

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

It seems that the problem with #3858 was finding a fitting name for the norm, and people liked PiecewiseLinearNorm, but that suggests more generality than implemented here. How about DivergingNorm, since it's likely to get used with a diverging colormap? Then we can later implement the more general case as PiecewiseLinearNorm if needed.

@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]

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]

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]

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]

• I don't think we should allow discontinuities in norms. Neither unused colors nor values without colors make sense.
• While technically the transformation is a spline of degree 1 and thus LinearSplineNorm is formally ok, splines are usually used with higher degrees to get some smooth approximation. And that might be a bit misleading.

[efiring]

@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]

@ImportanceOfBeingErnest Thank you for your very through tracing through the history of this discussion!