PR Summary

This is a relatively major re-arrangement of how we create colorbars. This will simplify making colorbars for other norms if the norms are created with a scale. It also allows more normal manipulation of the colorbar axes. There are some negative consequences as well.

Issue

Currently most colorbars are drawn as a pcolormesh on a hidden axes. When extend='both'/'upper'/'lower' it makes the axes longer by a proportion extendlen and draws the extend regions by distorting the upper and/or lower cell of the pcolormesh. This is great, except it means that all the usual tick locators need to have special cases that do not continue drawing the ticks into the region of the axis that has the extend triangles. We do that now with a few piecemeal wrapper classes: _ColorbarAutoLocator(ticker.MaxNLocator), _ColorbarAutoMinorLocator(ticker.AutoMinorLocator), etc. Needless to say that is clunky.

The scale used for the colorbar also has to nicely invert past vmin and vmax for the triangles to be drawn properly, despite the fact these regions are only meant for over/under colors that you wouldn't necessarily expect an arbitrary norm to be able to handle.

Proposal

The proposed solution here is to draw the main pcolor ("solid") on a full axes that goes from vmin to vmax, and draw the extend triangles ("extends") as patches appended to the end of that axes. They are drawn in axes space, so the scale of the axes and the limits of the axes no longer matter.

The problem with this approach is that all the sizing and placement of axes is with an axes that is the size of the solid and the extends. i.e. if shrink=1 the whole axes, including the extends, is the height (or width) of the parent axes.

The solution proposed here is to draw the solid on an inset_axes that is shrunk from the parent axes if there are extends.

Pros:

• The visible axis labels are all on the "inner" axes and no longer require weird wrappers around the tick Locators.
• Any scale can be used, and the user can set the scale manually as they like. The initial scale is chosen from the norm, if it has one, or chosen to be linear.
• the user can change the min and max of the axes if they like. We sometimes get requests for this if the user wants to zoom in on some part of the colormap.
• I think the code is simpler, but I wrote it so YMMV

Cons:

manual axes placement is not the main colorbar axes object any more:

The biggest con is that for

cax = fig.add_axes([0.1, 0.1, 0.8, 0.07])
cb = fig.colorbar(im, cax=cax)

the axes object we create is new so that cb.ax is no longer cax. In fact cax == cb.ax.parent_axes. So this breaks cases where the user hoped to do things to cax after it was created. Of course they can access cb.ax. This failed one test where we did cax.tick_params. We can pass these through as we find them (I did already for tick_params). However, this also means that cax.xaxis points to an axis we make invisible now, and won't do anything (again cb.ax.xaxis points to the right thing.)

I will argue this breakage is worth it. Doing random things to cax failed much of the time anyway, whereas the new object stored on cb.ax should be much more robust. Unfortunately, however, I cannot think of a reasonable way to deprecate this.

Slight change in visibility of lines with extends

This is an obscure one, but lines are now partly cut off if they are drawn on the edge of the colorbar and there is an extend. The test that broke this didn't appear to have a reasonable reason to have an extend in that case anyhow (see contour_colorbar.png, and contour_manual_colors_and_levels.png)

Other changes:

1. There seemed to have been a bug in colorbar widths with extends before, where they ended up a bit narrower than the colorbars without extends. This can be seen in double_cbar.png and a few other tests.
2. If there is only one extend, the new axes is offset from the center. This means that the label (which is attached to the inner_axes) is now offset as well. We could move it (by placing the label logic all on the parent), but I'm not convinced that it doesn't look better to let it move down and be centred on the spine. (Also double_cbar.png)
3. I ditched the private _internal.classic_mode for the colorbars. It doesn't change that many tests, and it needlessly complicates the Locator code to keep it around.

Test:

fig, ax = plt.subplots(1, 2, constrained_layout=True)
pc = ax[0].pcolormesh(np.arange(100).reshape(10, 10)+1)
cb = fig.colorbar(pc, ax=ax[0], extend='both')
cb.ax.set_yscale('log')

pc = ax[1].pcolormesh(np.arange(100).reshape(10, 10)+1)
cb = fig.colorbar(pc, ax=ax[1], extend='both')
cb.ax.set_ylim([20, 90])
plt.show()

Before

After

PR Checklist

• Has pytest style unit tests (and pytest passes).
• Is Flake 8 compliant (run flake8 on changed files to check).
• New features are documented, with examples if plot related.
• Documentation is sphinx and numpydoc compliant (the docs should build without error).
• Conforms to Matplotlib style conventions (install flake8-docstrings and run flake8 --docstring-convention=all).
• New features have an entry in doc/users/next_whats_new/ (follow instructions in README.rst there).
• API changes documented in doc/api/next_api_changes/ (follow instructions in README.rst there).