PR summary

This draft PR is a reply to#14168 Feature request: Bivariate colormapping

The context of this draft PR is the discussion thread for#14168 and the weekly meeting Sep 15th 2023.
It was suggested that a classVectorMappable should be a drop-in replacement forScalarMappable.
And it would be of interest to see howVectorMappable and multivariate colormaps can be threaded through the existing api.
It was further suggested that the new functionality should be triggered by providing a multivariate or bivariate colormap.
This ensures that the new functionality is only triggered when the user showsintent.

This draft PR is intended to allow for further discussion of#14168 at the next few weekly meetings.

The following functionality is supported:

Multivariate colormaps:

importmatplotlib.pyplotaspltA=plt.imread('R.png')B=plt.imread('G.png')C=plt.imread('B.png')fig,axes=plt.subplots(1,2,figsize= (12,4))pm=axes[0].pcolormesh((A,B,C),cmap='3VarSubA',vmax= (0.4,0.6,0.5))cb0,cb1,cb2=fig.colorbars(pm,shape= (-1,2))axes[0].set_title('Subtractive multivariate colormap')pm=axes[1].pcolormesh((A,B,C),cmap='3VarAddA',vmax= (0.4,0.6,0.5))cb0,cb1,cb2=fig.colorbars(pm,shape= (-1,2))axes[1].set_title('Additive multivariate colormap')

(data fromhttps://arxiv.org/abs/1812.10366)

Bivariate colormaps:

im0,im1=get_random_data()fig,axes=plt.subplots(1,2,figsize= (12,4))pm=axes[0].pcolormesh((im0,im1),cmap='BiOrangeBlue',vmin=-1,vmax=1)cax=fig.colorbar_2D(pm,shape= (-1,2))axes[0].set_title('Square 2d colormap')pm=axes[1].pcolormesh((im0,im1),cmap='BiCone',vmin=-1,vmax=1)cax=fig.colorbar_2D(pm,shape= (-1,2))axes[1].set_title('Circular 2d colormap')

Minimum changes required

This implementation is designed to make minimal changes to the existing code.
I have tried to list the significant changes bellow:

cm.VectorMappable is a drop in replacement forcm.ScalarMappable.
VectorMappable uses delegation and contains one or moreScalarMappables (.scalars).

A new functionaxes._base.ensure_cmap(cmap) is added.
ensure_cmap(cmap) takes a colormap, string or None and returns aColormap,MultivarColormap, orBivarColormap object.
None will always return the default (1D) colormap. i.e. to use bivariate or multivariate data, the user must show intent by actively choosing a suitable colormap.

A new functionaxes._base.ensure_multivariate_norm(n_variates, data, norm, vmin, vmax) is added.
When called, this ensures thatdata,norm,vmin, andvmax all have lengthn_variates. Single arguments are repeated if neccessary.

The new member varaiblen_variates is accessible on allColormap,BivarColormap, andMultivarColormap objects. It is 1, 2 or n, respectively.

Figure.pcolormesh() is adapted to support multivariate data by the following four changes:

1. collections.Collection now inherits fromcm.VectorMappable instead ofcm.ScalarMappable
2. cmap = ensure_cmap(cmap) is called immediately inFigure.pcolormesh(). This gives access tocmap.n_variates.
3. Ifcmap.n_variates > 1, the functionensure_multivariate_norm() is called to ensure the correct length of the norm parameters
4. axes._pcolorargs() takes an additional keyword argument (n_variates), so that ifn_variates > 1, it can correctly extract the dimensions from the input data.

Implementation of multivariate and bivariate colormaps

Multivariate data (2-8 variates) is supported vi the classcolors.MultivarColormap.
MultivarColormap is iterable, and iterating onMultivarColormap returns (1D) Colormap objects.
MultivarColormap.combination_mode is either'Add' or'Sub', and this determines if the colormaps are are combined by adding or subtracting the RGB values.
The file_cm_listed_multivar contains new 1D colormaps to bulid the multivariate colormaps.
The multivariate colormaps are contained in acm.ColormapRegistry() accessible atmpl.multivar_colormaps

2D colormaps are supported via the classcolors.BivarColormap.
There are two subclasses:SegmentedBivarColormap andBivarColormapFromImage
SegmentedBivarColormap repurposes_image.resample() to extrapolate a smaller image to a larger image. By using this we do not need to store the full (256,256,3) LUT in the source files, but can get away with (65,65,3) for complex colormaps or (9,9,3) for more simple colormaps with no significant loss in fidelity.
BivarColormap.shape is either'square' or'circle'. This changes how values outside the colormap are interpolated onto the colormap.
The bivariate colormaps are contained in acm.ColormapRegistry() accessible atmpl.bivar_colormaps

Further work

There are a number of further topics that need to be worked on to make this more than a draft PR (as lited below).
However I think it would be conducive to first discuss the points above, and whether the design desicions made so far, are sensible.

1. There is anabsolutely minimal implementation ofFigure.colorbars() andFigure.colorbar_2D().
   These are only for illustration purposes, and will need to be completely rewritten, and we need to think about return types.
2. I have not tested multi/bivariate colormaps with different kinds of norms (log, etc.). I suspect it already works, but it will need to be supported in figure.colorbar_2D().
3. Need to implement multivariate functionality for (all?, subset of?) other functions that take cmap [scatter, hexbin, imshow, pcolor, pcolorfast, specgram, contour, contourf, hist2d, matshow, others?].
4. Ensure docstrings are suitable for the new classes and altered functions.
5. I designed a number colormaps, but we should have a discussion about these at some point. If the design criteria I chose is suitable, or if we should design some others instead.
6. Test for all functions that can now accept multivariate colormaps.
7. Tests forFigure.colorbars()/Figure.colorbar_2D() with various placement options, norms etc.
8. Documentation of new functionality
9. I have attempted to write/update docstrings as I have added new functionality/classes/functions, nonetheless they probably need some refinement. Likely first by me, and then someone else.
10. The additional functionality requires changes to a number of error messages, and new error messages will need to be raised in order to help users use the new functionality. I have attempted to make/update the most relevant cases, but more will probably be needed.
11. Suitable names of functions/variables
12. ...

PR checklist

• "closesFeature request: Bivariate colormapping #14168" is in the body of the PR description tolink the related issue
• new and changed code istested
• Plotting related features are demonstrated in anexample
• New Features andAPI Changes are noted with adirective and release note
• Documentation complies withgeneral anddocstring guidelines