Skip to content

Bivar colorbar - #32606

Draft
trygvrad wants to merge 4 commits into
matplotlib:mainfrom
trygvrad:bivar-colorbar
Draft

trygvrad wants to merge 4 commits into
matplotlib:mainfrom
trygvrad:bivar-colorbar

Conversation

@trygvrad

@trygvrad trygvrad commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

This PR has a long history. It is part of Bivariate and Multivariate Colormapping and contains changes that were previously part of #31214 which is being separated into multiple parts with the use of AI. This is part 2 of 4 and Depends on #32605. Only the last commit ("Add bivariate colorbars") is new in this PR.

PR summary

  • Adds Figure.colorbar_bivar / SubFigure.colorbar_bivar and pyplot.colorbar_bivar.
  • New module matplotlib.colorbar_multivariate with BivarColorbar, make_bivar_axes, make_bivar_axes_gridspec.
  • colorbar.py is not changed (see discussion in Multivar colorbar #31214). The colorbar Axes is created by the existing colorbar.make_axes / make_axes_gridspec (with aspect=1 and no orientation), so placement, gridspec and constrained layout behave as for a normal colorbar.
  • Drawn with pcolormesh, so the axis scales follow the norms (log etc.); first data variable on the y-axis, second on the x-axis.
  • Interactive pan/zoom on the colorbar changes the norms, as for a normal colorbar.
  • Public API kept small (see discussion in Multivar colorbar #31214): only ax (read-only) and aspect (settable), plus set_xlabel/set_ylabel, xaxis/yaxis, update_normals, remove. No alpha.
  • aspect is preserved under constrained layout for colorbars at the top/bottom (layout inverts the aspect of horizontal colorbars; BivarColorbar compensates).
  • Figure.colorbar now raises a clear error when given a bivariate colormap, pointing to colorbar_bivar.
  • Toolbar zoom no longer assumes every ax._colorbar has an orientation (backend_bases.py).
  • Two Axes3D docstring cross-references made explicit (they became ambiguous with the new set_ylabel).
  • New test file test_colorbar_multivariate.py; baseline images moved from Multivar colorbar #31214 unchanged.
  • Release note with a plot in doc/release/next_whats_new/colorbar_bivar.rst; new API page colorbar_multivariate_api.rst.

There is no example in the docs yet, that will come in a separate PR.

Here is an example:

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()
image

AI Disclosure

The split of #31214 into smaller PRs, and the changes requested in review there, were
made with the assistance of an AI coding assistant (Claude). All changes were reviewed
and tested by me.

PR quality check

  • Use an expressive title, e.g. "Fix title font property precedence"
  • New and changed code is tested
  • Plotting related features are demonstrated in an example
  • New features and API changes have release notes
  • Documentation complies with general and docstring guidelines

- Colorizer: an existing MultiNorm passed as *norm* is used as is instead
  of being wrapped in a new MultiNorm, which raised a ValueError.
- MultiNorm.autoscale_None only emits the 'changed' signal when the limits
  of a constituent norm actually changed.
- Colorbar.remove no longer fails when the mappable has no Axes.

Changes implemented with the assistance of AI and manually evaluated

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@trygvrad

Copy link
Copy Markdown
Contributor Author

One question here:
This makes a new file colorbar_multivariate.py which is also used by the subsequent PRs #32607, #32608 for colorbar_multivar.
The bivar colorbar and mulitbar colorbars are sufficiently different that we could place them in separate files. Let me know if you would prefer this.

Comment thread lib/matplotlib/figure.py Outdated
Comment on lines +1467 to +1470
fig = ( # Figure of first Axes; logic copied from make_axes.
[*ax.flat] if isinstance(ax, np.ndarray)
else [*ax] if np.iterable(ax)
else [ax])[0].get_figure(root=False)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's factor this our into a helper colorbar._figure_of_first_axes() so that we can write

Suggested change
fig = ( # Figure of first Axes; logic copied from make_axes.
[*ax.flat] if isinstance(ax, np.ndarray)
else [*ax] if np.iterable(ax)
else [ax])[0].get_figure(root=False)
fig = colorbar._figure_of_first_axes(ax)

Reuse is a secondary benefit. More important is abstracting the logical details away and giving the concept a clear name to reduce complexity here.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On a more general note, this colorbar_bivar has a lot of code overlap with colorbar. That hints towards a common underlying concept. Could we extract that, give it a name and reuse it for both functions?

Comment thread lib/matplotlib/colorbar_multivariate.py Outdated
The mappable whose colormap and norm will be used.

location : None or {'left', 'right', 'top', 'bottom'}
Set the bivariate colorbars's location

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Set the bivariate colorbars's location
The location of the bivariate colorbar relative to the Axes.
If not None, this information is used to determaine
'auto' *ticklocations*.

Comment thread lib/matplotlib/colorbar_multivariate.py Outdated
location=None,
ticklocations=('auto', 'auto'),
aspect=1.0,
):

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
):
):

Comment thread lib/matplotlib/colorbar_multivariate.py Outdated
Comment on lines +244 to +246
def update_normals(self, mappable=None):
"""Redraw the colorbar after the norm or colormap of the mappable changed."""
self._draw_all()

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we still need this, when it delegates everything to _draw_all? Possibly yes, to satisfy the signature, and maybe for symmetry with Colorbar? A brief comment on this would be helpful.

@timhoffm

Copy link
Copy Markdown
Member

the bivar colorbar and mulitbar colorbars are sufficiently different that we could place them in separate files. Let me know if you would prefer this.

Yes, I think that's a good idea. I would put everyting in as provisional so that we can still reconsider when we see that a different organization is better.

We could also consider then to rename make_bivar_axes to make_axes, because then we have matplotlib.colorbar.make_axes, matplotlib.colorbar_bivar.make_axes, which is a nice symmetry.

@timhoffm

Copy link
Copy Markdown
Member

Overall thanks a lot for splitting. This is so much easier to review 🎉

trygvrad and others added 2 commits November 19, 2026 23:04
Add `Figure.colorbar_bivar` and `pyplot.colorbar_bivar`, which draw the
colorbar of a bivariate colormap as a 2D image, with one data variable
along each axis.

The new `BivarColorbar` class lives in the new module
`matplotlib.colorbar_bivar`. Its Axes is created by the existing
`colorbar.make_axes` / `colorbar.make_axes_gridspec`, so it takes part in
layout (including constrained layout) like a regular colorbar, and
`colorbar.py` itself is not changed.

Changes implemented with the assistance of AI and manually evaluated

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants