GeezerVison

I think this should take an ax and a cax argument, just like normal colorbar. For layout we are going to want the option for the colorbar to steal space from a number of axes, not just the axes that holds the mappable (though it's probably fine to default to that)

This should also play well with constrained layout. Tight layout won't work with colorbars so that is not a concern. If you need help with that, please ping. However conceptually it should be the same as a normal colorbar, it'll just possibly be much larger.

1. Yes, agree on unique signature
2. Especially since this is gonna be colorsquare/colorcircle/colorpane -> Esri just calls them legends far as I can tell (also this R library) but I think that'd maybe create too much collision here.

3. We might also/instead want the legend placement, especially for the geographic usecase. Which yes third parties can implement/might make more sense for cartopy to do.

1. Yes

2. bivar_colorbar seems ok. While it's a bit of a bulky "bar", I think the verbal connection to the 1D colorbar is still very valuable. All other names I can think of (color_square, color_patch, color_legend) all feel more off that stretching the meaning of "bar".

3. (c) is out. AFAIK we don't have other cases where we lump dimensions together in such a way. It also makes it hard to set one axis only (would require some (None, yticks) acrobatics).
   (a) is appealing, because the API we'd have to define is really minimal. On the downside, it feels a bit too low-level to expose the full axes (yes Colorbar gives you access as well, but that's rather for advanced use cases). OTOH people know how to configure Axes, so much knowledge can ve transferred.
   (b) is appealing in that it has a strong analogy to Colorbar, but I'm afraid, we're putting in a lot of boilerplate for little gain.
   A fourth option (d) would be to expose properties colorbar.xaxis, colorbar.yaxis, which is still a quite minimal API, but gives access to all the axis configuration options, e.g. colorbar.xaxis.set_ticks(). The downside is that the Axis-level functions are less known than their high-level wrappers.

   Overall, I'm inclined to go with (d) - it's only a little more overhead than (a) but still quite minimal and feels cleaner. We could later still add some (b) functions if we see the need.

Also apparently I didn't read 3 correctly 🤦‍♀️ but I agree w/ @timhoffm's proposal d)

This is progressing well, thank you for all the feedback so far.

In the draft, I am using

        self._image = self.ax.imshow(
            self.colorizer.cmap.lut,
            origin='lower',
            extent=(0, 1, 0, 1),
            transform=self.ax.transAxes,
            interpolation='nearest',
            alpha=self.alpha,
        )

to display the bivariate colorbar.

The transform=self.ax.transAxes is important because it allows us to use a different axis scale (i.e. log) without changing the image.
However, it has the side-effect that if one changes the limits on the axis, the axis changes while the norm stays the same.

This can for example be illustrated by:

norm = mpl.colors.MultiNorm(['log', 'log'])
ca = mpl.colorizer.Colorizer('BiOrangeBlue', norm)
fig, ax = plt.subplots()
cbar = fig.bivar_colorbar(ca, cax = ax, ticklocations=['left', 'bottom'])

norm.norms[1].vmin = 0.1
norm.norms[1].vmax = 10
cbar.xaxis.set_ticks([1, 10, 100])
print(ca.norm.vmin, ca.norm.vmax, cbar.ax.get_xlim() ) 
# (None, 0.1), (None, 10.0), (0.1, 100.0)

Where the xlim is changed but vmax on the norm is not.

My thinking is that any action taken by the user which would change the limits on the axis by operations on the axis, and not by setting the vmin or vmax, should raise an error of the form:

    raise ValueError("Changing the limits of this axis must be done "
            "using the norm attached to the bivariate colorbar.")

I can do this by connecting to "xlim_changed" and "ylim_changed".

Does this seem like a reasonable solution to you?

When ax.xaxis.set_ticks([1, 10, 100]) is called, it does not emit "xlim_changed". To me this seems like a bug. Should I make an issue?

Wouldn't it make sense to use pcolormesh instead of image so users can change the scale if they want to?

Wouldn't it make sense to use pcolormesh instead of image so users can change the scale if they want to?

Thank you for the feedback @jklymak, but I think we can work with imshow in this case.

The user should be able to change the scale on the norm, which will change the axis, but the bivariate colormap should render the same.

Consider these two figures:

Where the only change is that a LogNorm is used to when visualizing the GDP per capita in the lower plot.
This changes the way the data is mapped to color [the figure on the left], as well as the scale on the x-axis in the figure to the right, but the rendering of the colormap [in figure space] stays the same.

I do not think there is a need to set a scale different from that of the norm.

(additionally: I would like to avoid pcolormesh if possible, because if saved as an SVG, each tile in the mesh gets stored as a polygon, which makes it almost impossible to edit the svg later. I personally find the pipeline matplotlib→inkscape to be extremely powerful, and would like that to be possible here.)

The plots are based on https://trygvrad.github.io//mpl_docs/Bivariate%20colormaps.html

People do ask to set the scale differently from the norm and they will be able to, but will get incorrect scaling of the colors. Pcolormesh can be rasterized, so you can avoid the polygon problem in svg/pdf. Note normal colorbar uses pcolormesh.

@jklymak thank you for the specification, I will see if I can make pcolormesh behave :)

@jklymak
I was able to implement pcolormesh in a suitable way, and I agree that this is a much better solution.

I am looking at what we need for layouts for multivar colorbar.
Fundamentally, I think we want something like this:

import matplotlib.pyplot as plt
import numpy as np

im_A = np.arange(200)[np.newaxis, :]*np.ones((200, 200))
im_B = np.arange(200)[:, np.newaxis]*np.ones((200, 200))
im_C = 0.9*im_A + 0.9*im_B

im_A = np.sin(im_A**0.5)**2
im_B = np.sin(im_B**0.5)**2
im_C = np.sin(im_C**0.5)**2

fig, axes = plt.subplots(2, 2, figsize = (10, 6))
axes = axes.ravel()
locs = ['left', 'right', 'top', 'bottom']

im = (im_A, im_B, im_C)
for i, loc in enumerate(locs):
    cim = axes[i].imshow(im, cmap='3VarAddA')
    cb = fig.multivar_colorbar(cim, location=loc, use_gridspec=False, fraction=0.3)

Where fig.multivar_colorbar returns a new class MultivarColorbar which is iterable, and the user can get [or iterate through] constituent Colorbar objects. All callbacks between the Artist [and Colorizer] and the colorbars is handled through the MultivarColorbar object.

In terms of layout, I want the user to have the option to organize the colorbars in a different way:

    cb = fig.multivar_colorbar(..., n_major=2)

or

    cb = fig.multivar_colorbar(..., n_major=1)

For the prototype I am basing this on bbox.splitx() and bbox.splity() [gridspec=False].

In the existing code there is make_axes and make_axes_gridspec. With this PR I think we will now need 6 versions:

make_axes
make_bivar_axes
make_multivar_axes
make_axes_gridspec
make_bivar_axes_gridspec
make_multivar_axes_gridspec [not yet implemented]

Because there is a lot of overlap, I have created a number of private helper functions, which (hopefully) avoids duplicate code.

@jklymak does this make sense to you in terms of the layout?
I would be happy to for any suggestions you have that can make this more elegant/suitable :)
My apologies that this PR is slightly difficult to read as it build upon #30597 rather than main.

I have not yet started looking at make_multivar_axes_gridspec. I suspect we can do something smart with the gridspec here. This is very much not my area of expertise, so some support here would be appreciated, but I think it would be best if we make sure we align on what is the intended behaviour first :)

I'll need to look at what you are proposing. Ideally I think your colorbars would be encapsulated inside something constrained layout thinks is a "colorbar" that is should put into the colorbar slot in the layout manager. After that the "colorbar" can look as you like.

If you want the colorbars to be placed inside of the allotted area by the layout manager I think that will be more difficult

Overall I would not suggest making a gridspec version of the colorbars. I suppose those allow a non optimal but still legible layout.

I can try and look closer this weekend. If you had some example scripts for me to look at that'd make things easier. Apologies if they are already in this PR

bivar_colorbar seems to work fine with constrained layout.

mulitvar_colorbar doesn't work with

    return do_constrained_layout(fig, w_pad=w_pad, h_pad=h_pad,
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/jklymak/matplotlib/lib/matplotlib/_constrained_layout.py", line 116, in do_constrained_layout
    make_layout_margins(layoutgrids, fig, renderer, h_pad=h_pad,
  File "/Users/jklymak/matplotlib/lib/matplotlib/_constrained_layout.py", line 402, in make_layout_margins
    pad = colorbar_get_pad(layoutgrids, cbax)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/jklymak/matplotlib/lib/matplotlib/_constrained_layout.py", line 822, in colorbar_get_pad
    parents = cax._colorbar_info['parents']
              ^^^^^^^^^^^^^^^^^^
AttributeError: 'MultivarColorbar' object has no attribute '_colorbar_info'. Did you mean: '_set_colorbar_info'?

which looks fixable?

This might be the silliest thing but can we maybe flip the names to colorbar_{bi, multi}? I think would be especially easier for auto complete.

I'll need to look at what you are proposing.

:D

Ideally I think your colorbars would be encapsulated inside something constrained layout thinks is a "colorbar" that is should put into the colorbar slot in the layout manager. After that the "colorbar" can look as you like.

@jklymak This is a good idea, and I will try to make it happen, but I am not super familiar with this part of the code. What kind of object do you think that something should be, because I don't think it should be an axis in an of itself, but it should probably show up in Figure.get_children() [?]

    def get_children(self):
        """Get a list of artists contained in the figure."""
        return [self.patch,
                *self.artists,
                *self._localaxes,
                *self.lines,
                *self.patches,
                *self.texts,
                *self.images,
                *self.legends,
                *self.subfigs]

bivar_colorbar seems to work fine with constrained layout. mulitvar_colorbar doesn't work with

Thanks for checking this, I will fix this and add some tests that cover these cases.

This might be the silliest thing but can we maybe flip the names to colorbar_{bi, multi}? I think would be especially easier for auto complete.

@story645 I think there is significant merit to this argument :)

@jklymak @timhoffm @story645 I think this PR is ready for review.
Keep in mind that it builds upon #30597 rather than main, but I have rebased these onto main a couple of days ago.

I will start making PRs for #30529 and #30528 . These should be easier as they don't involve new API

@jklymak @timhoffm @story645 is it possible you have time to look at this in the coming weeks?

Now that #30597 is merged, I have rebased this onto main, so that it can be reviewed.

@jklymak do you have time to review this, both in terms of functionality and the code?
The new top-level functionality is fig.colorbar_multivar() and fig.colorbar_bivar(). Let me know if you want me to include examples (in the docs) in this PR.

I hope its ok if I ask you to take a look at this @rcomer , I was told by @story645 that you have done some PRs that interact with the layout engine.

This PR is the last code-heavy PR required to get multivariate and bivariate color mapping to work, a project that has been ongoing since 2024 Bivariate and Multivariate Colormapping. We are on the last mile, but I need someone to review this PR, preferably someone with experience with the layout engine.

In short, this PR allows you to make the 2d colorbar for the following plot, using the new Figure.colorbar_bivar(mappable) member function on the Figure class.

And similar for multivariate colorbars using Figure.colorbar_multivar(mappable).

If you would be willing to review this PR that would be very much appreciated 🥇

The first question is:

• Does this PR use the layout engine in a sensible way?

Other than that I think it is mostly a question of if there are any more things/edge cases we should test.

Let me know if you have any questions :)

Hi @trygvrad, I'm sorry but I do not have the capacity to be able to take this on, at least not for the next couple of months.

Thank you for the quick reply @rcomer

@story645 I wanted to go through this in the meeting today, but I don't have the mental capacity to attend today. Could you put it on the agenda for next week?
I will prepare a summary of the PR for next week so that we can more easily go through it.

No problem, will do!

This is a summary of what this PR does, so that it is easier to review:

New top level functionality

• Two new figure methods, fig.colorbar_bivar() and fig.colorbar_multivar().
• fig.colorbar_bivar()draws a 2D colormap as a square "stamp" next to the axes, not as a strip. It follows the convention from PR MultivarColormap and BivarColormap #28454: the first data axis is shown on the y-axis and the second on the x-axis.
• fig.colorbar_multivar() draws a separate colorbar for each variable in the multivariate case. You can arrange these in rows and colums by specifying the number of colorbars along the long axis.

New classes

• BivarColorbar – works mostly same as Colorbar only with two axes instead of one.
  Layout engine reserves space in a manner similar to colorbar
  The scale of the axes follow from the norm, same as with colorbar
  Ticklocations based on placement
  Interactive pan and zoom edit both norms directly _get_view, _set_view, _set_view_from_bbox, drag_pan
  Layout engine resizes axes when figure is resized
• MultivarColorbar(Sequence)
  A Sequence of Colorbar objects.
  Is not associated with a single Axes, but each constituent Colorbar will have its own axes
  Individual Colorbar accessed by indexing, i.e. fig.colorbar_multivar()[2].minorticks_off()
  Creates new axes if not provided using the caxes keyword: fig.colorbar_multivar(mappable) will create new axes for the colorbars, while fig.colorbar_multivar(mappable, caxes=axes) will place the colorbars in the axes provided.
  When creating new axes, the grid layout can be customized (rows/columns, spacing) but finer control is offered by passing a list of Axes.

Axes creation helpers and organization

• In colorbar.py, make_axes and make_axes_gridspec are split into shared pieces
• When dynamically resizing a plot the axes with the mappable need to keep track of what colorbars it is associated with. This is handled by the _colorbars property on the axes with the mappable. This contains objects that have a _colorbar_info dict. This dict now has a "type" key, and the behaviour branches on the type ('Colorbar', 'BivarColorbar' or 'MultivarColorbar'). For Colorbar and BivarColorbar the _colorbar_info exists on the associated axes, and contains the parameters required for positioning and scaling (aspect etc.). MultivarColorbar is not associated with a single axes so the _colorbar_info instead exists on the MultivarColorbar object itself, but performs the same role in terms of the layout engine.
• For a multivariate colorbar, they use the container's tight bbox and its original position, then give each colorbar axes its own sub-bbox from _get_tight_packing_inside.

Minimal example

import matplotlib.pyplot as plt
import numpy as np

im_A = np.arange(12).reshape((3, 4)) % 4
im_B = np.arange(12).reshape((3, 4)) % 3
im_C = np.arange(12).reshape((3, 4)) % 5
fig, axes = plt.subplots(1, 2, figsize=(12, 4))
# -------  colorbar_multivar  ------------
mim = axes[0].imshow((im_A, im_B, im_C), cmap='3VarAddA')
cbs = fig.colorbar_multivar(mim)
cbs[0].set_label('A')
mim.norm.vmin = (-1, -1, -1)
# -------  colorbar_bivar  ------------
mim = axes[1].imshow((im_A, im_B), cmap='BiOrangeBlue')
cbs = fig.colorbar_bivar(mim)
cbs.set_ylabel('A')
mim.norm.vmin = (-1, -1)

Positioning example colorbar_multivar()

im_A = np.arange(200)[np.newaxis, :]*np.ones((200, 200))
im_B = np.arange(200)[:, np.newaxis]*np.ones((200, 200))
im_C = 0.9*im_A + 0.9*im_B

im_A = np.sin(im_A**0.5)**2
im_B = np.sin(im_B**0.5)**2
im_C = np.sin(im_C**0.5)**2

fig, axes = plt.subplots(2, 2, figsize = (10, 6), dpi = 100, layout="constrained")
axes = axes.ravel()
locs = ['right', 'left',  'top', 'bottom']

im = (im_A, im_B, im_C)
for i, loc in enumerate(locs):
    cim = axes[i].pcolormesh(im, cmap='3VarAddA', vmax=(1, 1, 1))
    cb = fig.colorbar_multivar(cim, location=loc, n_major=2)
    cb[0].set_label('A')
    cb[1].set_label('B')
    cb[2].set_label('C')

fig.show()

Positioning example colorbar_bivar()

im_A = np.arange(200)[np.newaxis, :]*np.ones((200, 200))
im_B = np.arange(200)[:, np.newaxis]*np.ones((200, 200))

im_A = np.sin(im_A**0.5)**2
im_B = np.sin(im_B**0.5)**2

fig, axes = plt.subplots(2, 2, figsize = (10, 6), dpi = 100, layout="constrained")
axes = axes.ravel()
locs = ['right', 'left',  'top', 'bottom']

im = (im_A, im_B)
for i, loc in enumerate(locs):
    cim = axes[i].pcolormesh(im, cmap='BiOrangeBlue', vmax=(1, 1))
    cb = fig.colorbar_bivar(cim, location=loc, fraction = 0.3)
    cb.set_ylabel('A')
    cb.set_xlabel('B')

fig.show()

The last two examples use layout="constrained", while the first example does not.
Using layout="constrained" makes it easier to prevent labels from overlapping figures, etc, as the figure becomes crowded.

I'll do incremental reviews, because it's too large to do it in one go.

@timhoffm Do you want to look more at this, or should I make a commit with fixes?

I'll try to show up for next weeks meeting

@trygvrad Sorry, this is really hard to review. There's too much going on, and it's very hard to keep an overview. I tried to narrow the scope by looking at individual commits, but that doesn't work either because the commits revise each other.

Would it be possible to split this into multiple subsequent PRs? E.g.

• Optional preparatory refactoring (if so just argue why we want the change)
• Bivar colorbar
• Multivar colorbar
• Optional fix constrained_layout

Or whatever helps to make smaller chunks. AI should be able to sort this if you give reasonalbe direction.

If that sounds like a reasonable approach, please apply my comments so far, and then let's split the result.

I also question if it is necessary to touch colorbar.py or if this could be independent. I appreciate there is some wrangling in constrained_layout, but that seems minor. If it were independent, then it would make the review burden substantially less since we would be sure you aren't poking into the delicate dance that is normal matplotlib colorbars.

For what it is worth, I think your three colorbars should just be three colorbars, perhaps wrapped in a helper.

The bi-variate colorbar should just be an axes, and probably should just be treated like a normal axes rather than a colorbar. It really takes up too much room to be a bare decoration.

For what it is worth, I think your three colorbars should just be three colorbars, perhaps wrapped in a helper.

The bi-variate colorbar should just be an axes, and probably should just be treated like a normal axes rather than a colorbar. It really takes up too much room to be a bare decoration.

Not sure. Do we have reasonable capability to layout multiple colorbars next to an Axes?
For bi-variate: Positioning is complex. It seems like it’s often used for geographical plots and thee as an inset. Aa a baseline, I’d still say that treating as a decoration is reasonable. Bivar colormaps should typically be square and smaller than the data Axes. That’s not a good fit for a regular Axes layout.

I don't think we have a turnkey way to make three colorbars and lay them out, so a helper is great.

For bivariate, a colorbar axes does three things.

1. makes a colormap graphic to fill the axes
2. labels just one axis, and removes ticks and labels from the minor axis
3. Participates in layout in (probably too many) various ways.
   a. Steals space via gridspec nesting
   b. steals space and is just placed beside the axes using positioning
   i. is a fixed layout
   ii. is moved around by constrained layout.

1 and 2 seems like they are easily separated. Without looking too hard I think this PR does that, or if it doesn't should try and do so as much as possible.

3 is obviously a bit convoluted, and maybe requires the interaction between the new and traditional colorbars.

Thank you for the feedback @timhoffm @jklymak :)

Or whatever helps to make smaller chunks. AI should be able to sort this if you give reasonalbe direction.

I will try to do this, asking AI is probably a good idea.

I also question if it is necessary to touch colorbar.py

Might as well also see if I can make some new files instead of touching colorbar.py, that might make it easier to review as well.