This seems fine, plus or minus the name which I'm not sure about.

Do you need to lock out setting vmin somehow? What happens if I set norm.vmin=-42 after I've initialized the norm?

I got the naming idea from the existing SymLogNorm -- and this is basically a symmetrical version of Normalize. Having said that, the name SymLinNorm would also make sense.

And yes, good point about vmin, it would make sense to restrict access to that. Or, alternatively, one could raise an error when the norm is evaluated and it is no longer symmetrical (this behavior is similar to changing vmin to a higher value than vmax for Normalize, it works until the norm is evaluated).

Thank you for your work on this @jpmattern ! As you noted, we have had several attempts at getting functionality like this in over the years, hopefully it works this time!

If the __init__ is going to take the center and 1 parameter, why not take the range (rather than the max)? SymNorm(center=50, range=5) feels a bit better than SynNorm(center=50, vmax=55)?

I think that using properties for both vmin/vmax to keep them in sync with each other is reasonable.

This will definitely need tests + documentation.

I'm not wild about the name, I also thought of the analogy to SymLog immediately, but my knee jerk reaction was concern (because of the funny linear / log transition in SymLog).

Could we get the same effect by adding a vcenter and vrange properties and kwargs to Normalize (which some rules to de-conflict them)? Maybe:

• if you set vmin or vmax, the other does not change and the center / range are re-computed
• if you set vcenter or vrange the other is held constant and vmin / vmax are re-computed
• for kwargs you can give up to any 2 and we sort out the rest

but that would lose what I think is the most important feature of this proposal which is that auto scaling works. Maybe we want the above + a very thin sub-class that changes the autoscale rules?

I like the idea of using range rather than vmax, this would also be a change that could easily be included in the proposed SymNorm changes.

As for changing the name, I would be in favour of that but I haven't come up with a better name so far. One thing that throws me off a bit is the single "m" in the name when both "symmetrical" and "symmetry" have two "m"s.

Changing the entire structure of Normalize could be the most elegant solution: Getters and setters could be used to protect against invalid changes to the properties (e.g. setting vmin to a value greater than vmax). And a Normalize(symmetrical=True) would be pretty self-explanatory. However, that kind of change is quite substantial and would require a lot more testing. I'd be happy to work on a solution if there's desire for a more substantial change.

I’m not a fan of one Normalize method with conflicting kwargs.

CenteredNorm?

I'd go for halfrange instead of range. Center +/- halfrange is what one (at least me) typically thinks about.

CenteredNorm is good. SymmetricNorm would also work. SymNorm is a bit of an awkward abbreviation (despite the precedence of SymLogNorm).

I like the idea of using halfrange and the name makes it clear that it defines half of the range and not the full range which could have been an alternative. The updated code is using halfrange now and the norm has also be renamed.

I am personally not sure if I like CenteredNorm or SymmetricalNorm better but since we had 2 votes for it already, I opted for the former.

You can count my vote as half - if you prefer SymmetricalNorm, that's fine w/ me. I didn't like SymNorm - probably residual trauma from SymLogNorm.

This would need a note & example in the What's new document.

As an example, I'd suggest the image in my first post above, adjusted for the new name. I modified en example from the gallery to create it, code would look something like this:

import numpy as np
import matplotlib.cm as cm
import matplotlib.pyplot as plt
import matplotlib.colors as mcolors

delta = 0.1
x = np.arange(-3.0, 4.001, delta)
y = np.arange(-4.0, 3.001, delta)
X, Y = np.meshgrid(x, y)
Z1 = np.exp(-X**2 - Y**2)
Z2 = np.exp(-(X - 1)**2 - (Y - 1)**2)
Z = (0.9*Z1 - 0.5*Z2) * 2

#cmap = cm.RdYlGn
cmap = cm.seismic

fig, axs = plt.subplots(ncols=3, figsize=(10,2.5))

ax = axs[0]
pc = ax.pcolormesh(Z, norm=mcolors.Normalize(), cmap=cmap)
fig.colorbar(pc, ax=ax)
ax.set_title('Normalize()')

ax = axs[1]
pc = ax.pcolormesh(Z, norm=mcolors.TwoSlopeNorm(vcenter=0.0), cmap=cmap)
fig.colorbar(pc, ax=ax)
ax.set_title('TwoSlopeNorm(vcenter=0.0)')

ax = axs[2]
pc = ax.pcolormesh(Z, norm=mcolors.CenteredNorm(), cmap=cmap)
fig.colorbar(pc, ax=ax)
ax.set_title('CenteredNorm()')

Where would the example for the code go? Is examples/color/ the right directory and should it be added to a new file?

There is a tutorial on colormap norms. It also has the examples broken out into user demo, but that seems a silly place for them. Without thinking about it too deeply, I'd add the example to the tutorial.

I like where this is heading!

This definitly needs a test, I suggest starting with

@pytest.mark.style(style)
@check_figures_equal(extensions=['png'], st)
def test_centered_norm(fig_ref, fig_test):
    ax_test = fig_test.subplots()
    ax_ref = fig_ref.subplots()

    # make the "same" plot using CenteredNorm and Normalize

I see that at call time it fixes the limits, I think we should also raise or warn if we do change it. If a user does not realize that they have ended up with a CenteredNorm, set norm.vmax = ... we are going to silently discard their change on the next draw. That is the sort of thing that end result in 5 hours of chasing down rabbit holes, growing concerned you are forgetting how to program, and then a lot of rage..... or so friends tell me ;).

Demo and test code sound good, I can add those. @tacaswell, I think to produce a warning or raise and error is a sensible idea but the only way to implement it I can think of involves changes to the super class Normalize. Currently, there is no control over what the user sets vmin and vmax to, but one could turn them into properties with getter and setter methods which could then be overridden by CenteredNorm.

Closes #1806.

The prominent use of "Symmetric logarithmic" in the tutorial and the call for a "symmetric" norm in #1806 makes me think that SymmetricalNorm might be a more intuitive name than CenteredNorm. What do others think? I know we have a couple of votes already.

One of the most difficult issues with adding the new norm to the tutorial was where to place it. It seems more commonly applicable than SymLogNorm which is appearing very early on and makes the case for symmetrical data in its description. The TwoSlopeNorm appears quite late in the tutorial, so I have scrapped the use of TwoSlopeNorm from the example and placed it above SymLogNorm for now. I am happy to move it.

I have added a new gallery example and a few tests to the code. Those appear to run without issues in my virtual environment. I cannot quite wrap my head around the errors reported above. They may be related to me adding code to the gallery but I am not sure what to do about them, can someone help?

This is the error message that CircleCI is showing me:

tar cf doc/build/sphinx-gallery-files.tar.gz doc/api/_as_gen doc/gallery doc/tutorials

tar: doc/build/sphinx-gallery-files.tar.gz: Cannot open: No such file or directory

tar: Error is not recoverable: exiting now

😱 I would find this so useful!

In terms of the failing tests, could you rebase this on top of the current master branch, and we can see if the tests are still failing.

Sounds good, I will try this in the next few days.

Ok, I went through the rebasing process and the tests I did on my end succeeded (generating the gallery image). The automated test above fails in an odd place with an error message that is not very helpful to me, it appears to finish building the documentation and then exits with an error:

embedding documentation hyperlinks for tutorials... [ 92%] text_intro.html
embedding documentation hyperlinks for tutorials... [ 95%] text_props.html
embedding documentation hyperlinks for tutorials... [ 97%] sg_execution_times.html
embedding documentation hyperlinks for tutorials... [100%] annotations.html

make: *** [Makefile:33: html] Error 1

Exited with code exit status 2

I'm not sure the rebase was quite right, as you shouldn't have so many unrelated commits in the PR. I see the last commit is a merge, which shouldn't be there. That means you pulled the old commits from GitHub back into your local copy. After rebasing, you'll want to force push back to GitHub to delete the old commits, instead of pulling.

The doc error is earlier in the log:

/home/circleci/project/doc/tutorials/colors/colormapnorms.rst:99: WARNING: py:obj reference target not found: colors.CenteredNorm

Thanks @QuLogic, that was helpful. The doc error was related to a missing entry for CenteredNorm in doc/api/colors_api.rst. I have never worked with Sphinx before but that issue seems to be resolved.

I don't know what to do about the rebase though. This is my first one and it appeared to go well until I accidentally performed a git pull and now I have a bunch of extra commits in my branch. My attempts to undo them have been unsuccessful so far.

Yes, after a rebase, you don't want to pull, you want to force push to replace the old versions on GitHub. You can see this using git log --graph --pretty=fuller master..symnorm. The left-most branchline contains commits authored in July, and committed in September, i.e., the rebased commits. The middle branchline is a merge path which doesn't really matter. The right-most branchline contains commits authored in July and committed in July, i.e., the original commits.

To drop the old commits, do the following:

$ git checkout symnorm
# Back to the last commit made of the _new_ commits
$ git reset --hard de6de1950eeb49177b3d320548f154edab4c6e92
# Replace everything on GitHub
$ git push --force-with-lease origin symnorm

PS, git on your computer says your name is Paul home desktop, which doesn't match your name in GitHub, and seems more like a description of your computer than your actual name. You'll probably want to fix that.

True, I changed the author names to the commits in question.

This would need a What's new entry as well.

Ok, I

• added a what's new entry with a new example plot (creating a heatmap plot)
• slightly modified and expanded the tests to include usage of the setters
• added the seed to the tests, though it may make more sense to set the seed before every individual check

@jklymak, I agree that it would make sense to place the tutorial entry below or closer to TwoSlopeNorm but I like that it currently sits just above SymLogNorm and the flow of text works quite well in my opinion: LogNorm sets the stage for a logarithmic transformation, CenteredNorm introduces the concept of symmetry and a center, and then SymLogNorm combines the two, starting out with: "Similarly, it sometimes happens that there is data that is positive and negative, but we would still like a logarithmic scaling applied to both."
Happy to change the order but I think it works quite well right now.

In my most recent commit, I expanded testing to cover 100% of the CenteredNorm code. I may be wrong but I don't think the most recent failing check is due to my commits to the code. Are there any other requests for features?

Thanks @jpmattern - looks like a useful addition!

Awesome, thanks! Great to see that this feature its making its way into the code now.