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 class VectorMappable should be a drop-in replacement for ScalarMappable.
And it would be of interest to see how VectorMappable 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 shows intent.

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:

import matplotlib.pyplot as plt
A = 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 from https://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 for cm.ScalarMappable.
VectorMappable uses delegation and contains one or more ScalarMappables (.scalars).

A new function axes._base.ensure_cmap(cmap) is added.
ensure_cmap(cmap) takes a colormap, string or None and returns a Colormap, MultivarColormap, or BivarColormap 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 function axes._base.ensure_multivariate_norm(n_variates, data, norm, vmin, vmax) is added.
When called, this ensures that data, norm, vmin, and vmax all have length n_variates. Single arguments are repeated if neccessary.

The new member varaible n_variates is accessible on all Colormap, BivarColormap, and MultivarColormap 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 from cm.VectorMappable instead of cm.ScalarMappable
2. cmap = ensure_cmap(cmap) is called immediately in Figure.pcolormesh(). This gives access to cmap.n_variates.
3. If cmap.n_variates > 1, the function ensure_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 if n_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 class colors.MultivarColormap.
MultivarColormap is iterable, and iterating on MultivarColormap 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 a cm.ColormapRegistry() accessible at mpl.multivar_colormaps

2D colormaps are supported via the class colors.BivarColormap.
There are two subclasses: SegmentedBivarColormap and BivarColormapFromImage
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 a cm.ColormapRegistry() accessible at mpl.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 an absolutely minimal implementation of Figure.colorbars() and Figure.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 for Figure.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

• "closes Feature request: Bivariate colormapping #14168" is in the body of the PR description to link the related issue
• new and changed code is tested
• Plotting related features are demonstrated in an example
• New Features and API Changes are noted with a directive and release note
• Documentation complies with general and docstring guidelines