Multivar imshow by trygvrad · Pull Request #30597 · matplotlib/matplotlib

trygvrad · 2025-09-24T19:26:53Z

Exposes the functionality of MultiNorm, BivarColormap and MultivarColormap to the top level plotting functions ax.imshow(), ax.pcolor() and ax.pcolormesh(). This closes #30526, see Bivariate and Multivariate Colormapping
As a side-effect of the pcolor/pcolormesh implementation, Collection also gets the new functionality.

In short, this PR allows you to plot multivariate data more easily, but it does not:

Create equivalents to fig.colorbar() for BivarColormap and MultivarColormap to work with ColorizingArtist
Select bivariate and multivariate colormaps to include in matplotlib
Examples demonstrating the new functionality

These will come in later PRs. See Bivariate and Multivariate Colormapping

Examples demonstrating new functionality:

import numpy as np
import matplotlib as mpl
import matplotlib.pyplot as plt
cmap = mpl.bivar_colormaps['BiPeak']
x_0 = np.arange(25, dtype='float32').reshape(5, 5) % 5
x_1 = np.arange(25, dtype='float32').reshape(5, 5).T % 5
x_0, x_1 = x_0 + 0.3*x_1, x_0*-0.3 + x_1, 

fig, axes = plt.subplots(1, 3, figsize=(6, 2))
axes[0].imshow(x_0, cmap=cmap[0])
axes[1].imshow(x_1, cmap=cmap[1])
axes[2].imshow((x_0, x_1), cmap=cmap)
axes[0].set_title('data 0')
axes[1].set_title('data 1')
axes[2].set_title('data 0 and 1')

fig, axes = plt.subplots(1, 6, figsize=(10, 2.3))
axes[0].imshow((x_0, x_1), cmap='BiPeak', interpolation='nearest')
axes[1].matshow((x_0, x_1), cmap='BiPeak')
axes[2].pcolor((x_0, x_1), cmap='BiPeak')
axes[3].pcolormesh((x_0, x_1), cmap='BiPeak')

x = np.arange(5)
y = np.arange(5)
X, Y = np.meshgrid(x, y)
axes[4].pcolormesh(X, Y, (x_0, x_1), cmap='BiPeak')

patches = [
    mpl.patches.Wedge((.3, .7), .1, 0, 360),             # Full circle
    mpl.patches.Wedge((.7, .8), .2, 0, 360, width=0.05),  # Full ring
    mpl.patches.Wedge((.8, .3), .2, 0, 45),              # Full sector
    mpl.patches.Wedge((.8, .3), .2, 22.5, 90, width=0.10),  # Ring sector
]
colors_0 = np.arange(len(patches)) // 2
colors_1 = np.arange(len(patches)) % 2
p = mpl.collections.PatchCollection(patches, cmap='BiPeak', alpha=0.5)
p.set_array((colors_0, colors_1))
axes[5].add_collection(p)
axes[0].set_title('imshow')
axes[1].set_title('matshow')
axes[2].set_title('pcolor')
axes[3].set_title('pcolormesh (C)')
axes[4].set_title('pcolormesh (X, Y, C)')
axes[5].set_title('PatchCollection')
fig.tight_layout()

"closes #30526" is in the body of the PR description to link the related issue
new and changed code is tested
[N/A] Plotting related features are demonstrated in an example
[N/A] New Features and API Changes are noted with a directive and release note
[N/A] Documentation complies with general and docstring guidelines

trygvrad · 2025-11-02T22:50:03Z

I fixed the circleci doc error for this.
It would be great if someone could take a look :)
@QuLogic @story645 @ksunden @timhoffm

story645 · 2025-11-20T20:45:47Z

+    fig, axes = plt.subplots(2, 3)
+
+    # interpolation='nearest' to reduce size of baseline image
+    axes[0, 0].imshow(x_1, interpolation='nearest',  alpha=0.5)


are the other interpolations tested?

Nope!,
I'm changing one of tests so that it is :)

feeling silly but can't find the test with this change

It's in the following test test_multivariate_visualizations()

line 10101 does imshow without specifying interpolation: axes[0].imshow((x_0, x_1, x_2), cmap='3VarAddA')

doesn't imshow usually default to nearest though? https://matplotlib.org/devdocs/api/_as_gen/matplotlib.axes.Axes.imshow.html#matplotlib-axes-axes-imshow

Like what happens if interpolation is set to none?

ksunden

General thoughts on return types:

Doing things like float | tuple[float, ...] as is done for several things here (vmin/vmax, clip, etc) is potentially problematic.

Humans may easily work with that, but type checkers will likely yell that they didn't check for all possible outcomes

None is a bit of a special case in being more acceptable (easier to check, etc)

Consider moving these in new code to always return a tuple (even if single element) This keeps the branching needed to a minimum and is not too cumbersome to work for in the single variable case.

Obviously, existing APIs need to maintain back-compat, so this is limited to new code.

Consider whether conceptually an empty tuple is what is truly meant by the None case, but if it is not, retain None

trygvrad · 2025-12-01T13:09:26Z

General thoughts on return types:
Doing things like float | tuple[float, ...] as is done for several things here (vmin/vmax, clip, etc) is potentially problematic.
Humans may easily work with that, but type checkers will likely yell that they didn't check for all possible outcomes

We discussed change the behaviour of colorizer to always return tuples on the call last week.

The relevant moving parts here are:

Norm (Normalize, MultiNorm): members: vmin, vmax, clip
Colorizer: members: get/set_clim, get/set_clip, vmin, vmax, clip
_ColorizingInterface: members: get/set_clim, get/set_clip

The Norm ABC must be typed as follows for backwards compatibility:
def vmin(self) -> float | tuple[float | None, ...] | None: ...

For the Colorizer, I think it makes sense to force tuples on the getter, but allow both on the setter:

    def get_clim(self) -> tuple[tuple[float | None, ...], tuple[float | None, ...]]: ...
    def set_clim(self, vmin: float | tuple[float, ...] | None = ..., vmax: float | tuple[float, ...] | None = ...) -> None: ...

    def get_clim(self):
        """
        Return the values (min, max) that are mapped to the colormap limits.

        This function is not available for multivariate data.
        """
        if self._colorizer.norm.n_components > 1:
            raise AttributeError("`.get_clim()` is unavailable when using a colormap "
                                 "with multiple components. Use "
                                 "`.colorizer.get_clim()` instead.")
        return self.colorizer.norm.vmin, self.colorizer.norm.vmax

One reason why I favor option B, is that set_clim is already sufficiently complicated, because for scalar data it allows both signatures:
.set_clim(vmin=vmin, vmax=vmax)
.set_clim((vmin, vmax))
and the 2nd option is ambiguous if there are two colors

@ksunden @story645 Could you let me know what you think?

story645

Sorry for the very long delay in reviewing. Minor nits but I think this is fine otherwise.

story645 · 2026-01-06T23:41:47Z

+    fig, axes = plt.subplots(2, 3)
+
+    # interpolation='nearest' to reduce size of baseline image
+    axes[0, 0].imshow(x_1, interpolation='nearest',  alpha=0.5)


feeling silly but can't find the test with this change

trygvrad · 2026-02-20T20:49:08Z

@timhoffm @ksunden @story645
I think the remaining test failures are not related to the changes here, and that this PR is ready to be approved/merged.

The next step in Bivariate and Multivariate Colormapping (view) will be to add equivalents to fig.colorbar(), and I will start working on this, and make a draft PR such that we can start discussing API names, layout etc :)

timhoffm · 2026-02-21T21:59:32Z

+    fig, axes = plt.subplots(1, 6, figsize=(10, 2))
+
+    axes[0].imshow((x_0, x_1), cmap='BiPeak', interpolation='nearest')
+    axes[1].matshow((x_0, x_1), cmap='BiPeak')


Do we want matshow to support multivar colors? Technically, that's possible, because it's a wrapper around imshow, but semantically it's currently defined as "Plot the values of a 2D matrix or array as color-coded image."

I haven't thought much about this, but it seems that the multivar extension is not helpful for matrix visualization. If that's the case, we should enforce in matshow that no multivar input is supported.

My thinking was that matshow is not necessary to include in the first iteration. If we want to introduce it later we can make an issue. Not sure if it would be a "good first issue" or not, but it might yield the additional benefit of having someone else familiarize themselves with this side of the project.

Agreed, a formal introduction to matshow needs additional consideration and should be investigated separately.

the question here is whether we implicitly allow multivariate mapping by doing nothing, or whether we explicitly check and prohibit multivariate mapping in matshow. I’m inclined towards the latter.

matshow() starts with a line:

Z = np.asanyarray(Z)

So since we can guarantee that the output is a np.array, we can easily check the size.
I added the following check.

Z = np.asanyarray(Z) if Z.ndim != 2: if Z.ndim != 3 or Z.shape[2] not in (1, 3, 4): raise TypeError(f"Invalid shape {Z.shape} for image data")

(This allows data of shape (M, N, 1), as I found that that is currently allowed on main).

but it seems that the multivar extension is not helpful for matrix visualization

Someone could be visualizing index variables in a matrix same as they're visualizing index variables in a choropleth. I question if it's a good idea, but I think the general philosophy of this library should be to allow anything that isn't explicitly wrong.

trygvrad · 2026-02-22T14:54:49Z

@timhoffm I pushed the requested changes, thank you for the feedback :D

timhoffm

Only two minor style issues.

This is fundamentally ready, but I think we cannot yet merge because we haven't branched 3.12 off yet (everything on main still targets 3.11).

This by itself should not go in without #30527 and potentially the other remaining topics in the project: https://github.com/orgs/matplotlib/projects/9/views/1.

trygvrad · 2026-02-27T18:06:26Z

This is fundamentally ready, but I think we cannot yet merge because we haven't branched 3.12 off yet (everything on main still targets 3.11).

:D

This by itself should not go in without #30527 and potentially the other remaining topics in the project: Bivariate and Multivariate Colormapping (view).

Agreed

story645 · 2026-03-01T00:14:55Z

This by itself should not go in without #30527 and potentially the other remaining topics in the project: Bivariate and Multivariate Colormapping (view).\n\nAgreed

Since there are a bunch of things that should go in together, do we want to experiment with a feature branch? I know we initially rejected the idea, but @QuLogic seems to be having some success with the font-overhaul branch.

timhoffm · 2026-03-01T07:25:03Z

I'm -0.2 on feature branches. The advantage is that you can commit parts and then base other work on this without affecting the main branch. But this is also the disadvantage: If the feature changes code in areas that is also touched by the main branch, merging gets a nightmare quickly. The text overhaul branch works well because is in a very particular part of the code (and generally every change we make in that area is likely to change text rendering so should be on that branch).

Multivar colormapping more broadly touches the code and is less suited for a feature branch. So far, we've been quite successful in incremental merges to main. It's just that we don't want to expose a multivar imshow as long as we don't have a suitable colorbar for that. And timing is accidentally so that the 3.11 release is between the readiness of the two parts.

…how, pcolor, pcolormesh, and Collection

@story645

thank you @story645 @ksunden

Co-authored-by: Kyle Sunden <[email protected]>

Co-authored-by: Tim Hoffmann <[email protected]>

trygvrad · 2026-06-07T14:26:04Z

@timhoffm @ksunden
As discussed at the meeting on Thursday, I have now rebased this PR.
Once this is merged, we can more easily review #31214

timhoffm

Mostly small changes that I noticed when re-reading the PR. Let's still get them in. Please add them as an additional commit for easier review. We'll squash-merge in the end.

timhoffm · 2026-06-09T10:48:03Z


-        %(cmap_doc)s
+
+        %(multi_cmap_doc)s


multi_cmap_doc should be rewritten from

Multivariate data is only accepted if a multivariate colormap (BivarColormap or MultivarColormap) is used.

to

Multivariate colormaps (BivarColormap or MultivarColormap) require multivariate data.

because we should phrase from the perspective of the documented parameter (here: cmap).

Also, it states "This parameter is ignored if X is RGB(A)."

How do we know RGB(A), i.e. shape (M, N, 3) or (M, N, 4) if there is (K, N, M) as multivariate data. Is this now a heuristic that the first or last dimension is low?

timhoffm · 2026-06-09T10:54:52Z

+        C = mcolorizer._ensure_multivariate_data(args[-1],
+                                                 colorizer.cmap.n_variates)


I feel _ensure_multivariate_data is not a good name because:

"ensure" has more connotation of validation, not necessarily conversion

this does not necessarily output multivariate data.

Good naming is hard and I propose to do this as a follow-up as this is internal and has been here before the PR.

trygvrad · 2026-06-10T12:02:52Z

@timhoffm
I am putting my replies here so that I can resolve the comments above without hiding the answers for future reference.

What about structured arrays, are they supported too? Do we possibly need one place to define "multivariate data" that can be referenced?

Yes we support structured data as well. On a related note the internal _ImageBase class requires structured data, and as requested I updated the docstring of this so that it reads:

            - a (M, N) array interpreted as scalar (greyscale) image,
              with one of the dtypes `~numpy.float32`, `~numpy.float64`,
              `~numpy.float128`, `~numpy.uint16` or `~numpy.uint8`.
            - a (M, N) structured array with K fields for multivariate colormapping.
              This must be used with a `.BivarColormap` (K=2) or generally with a
              K-component `.MultivarColormap`.
            - (M, N, 4) RGBA image with a dtype of `~numpy.float32`,
              `~numpy.float64`, `~numpy.float128`, or `~numpy.uint8`.

How should we add the option of structured data to the top level functions?
Should we include the two ways to include multivariate data on one line, i.e. something like this?:

            - a (K, M, N) scalar array or a structured (M, N) array with K fields:
              a K-component M*N mesh for multivariate colormapping. This must be 
              used with a `.BivarColormap` (K=2) or generally with a K-component 
              `.MultivarColormap`.

Also, did we discuss (K, M, N) vs. (M, N, K)? (Sorry in case I bring up topics that we may have discussed before)

Yes, this has been discussed, and it this keeps coming back up. I believe the primary discussions on this was at the weekly meeting around this time. I know I have made multiple posts on this before, but I have a difficult time finding them among all the different PRs.
If we want to discuss this again I suggest we bring it up at a weekly meeting and make sure that this time we write some things in the meeting notes :)

Also, it states "This parameter is ignored if X is RGB(A)."

I'm changing this to Scalar colormaps are ignored if *X* is RGB(A). which better reflects the current behaviour both on main and in this pr.

plt.imshow(np.random.random((6, 7, 3), cmap='not_a_colormap')

will cause an exception on main, while only if the cmap argument is a valid scalar colormap is the paramater ignored, i.e.:

plt.imshow(np.random.random((6, 7, 3), cmap='viridis')

How do we know RGB(A), i.e. shape (M, N, 3) or (M, N, 4) if there is (K, N, M) as multivariate data. Is this now a heuristic that the first or last dimension is low?

The multivariate pipeline is triggered by a valid multivariate colormap, thus we have:

i.e.:

plt.imshow(np.random.random((3, 3, 3))                        →   interpreted as rgb image
plt.imshow(np.random.random((3, 3, 3), cmap='viridis')        →   interpreted as rgb image
plt.imshow(np.random.random((3, 3, 3), cmap='not_a_cmap')     →   raises an error
plt.imshow(np.random.random((3, 3, 3), cmap='3VarAddA')       →   uses a multivariate colormap

github-actions Bot added topic: color/color & colormaps topic: images topic: collections and mappables labels Sep 24, 2025

trygvrad force-pushed the multivar_imshow branch from be62c09 to 0f557d5 Compare September 24, 2025 21:00

github-actions Bot added the topic: pyplot API label Sep 24, 2025

trygvrad force-pushed the multivar_imshow branch from 0f557d5 to e2aab93 Compare September 24, 2025 21:10

QuLogic added this to Bivariate and Multivariate Colormapping Sep 25, 2025

QuLogic added this to the v3.12.0 milestone Sep 25, 2025

QuLogic added the status: waiting for other PR label Oct 30, 2025

github-actions Bot added the status: needs rebase label Oct 30, 2025

trygvrad moved this to In Progress in Bivariate and Multivariate Colormapping Oct 30, 2025

trygvrad force-pushed the multivar_imshow branch from e2aab93 to 23e6caf Compare October 30, 2025 20:29

github-actions Bot removed topic: color/color & colormaps status: needs rebase labels Oct 30, 2025

trygvrad removed the status: waiting for other PR label Nov 2, 2025

trygvrad force-pushed the multivar_imshow branch 2 times, most recently from 1efde4a to 35746f5 Compare November 2, 2025 22:12

github-actions Bot added the Documentation: API files in lib/ and doc/api label Nov 2, 2025

trygvrad force-pushed the multivar_imshow branch from 35746f5 to c334208 Compare November 2, 2025 22:30

github-actions Bot added the topic: color/color & colormaps label Nov 2, 2025

story645 reviewed Nov 20, 2025

View reviewed changes

ksunden previously requested changes Nov 20, 2025

View reviewed changes

github-actions Bot added the status: needs rebase label Nov 24, 2025

trygvrad force-pushed the multivar_imshow branch from d890452 to b570ecc Compare December 1, 2025 14:19

github-actions Bot removed the status: needs rebase label Dec 1, 2025

trygvrad force-pushed the multivar_imshow branch from b570ecc to 053e524 Compare December 1, 2025 14:28

github-actions Bot added the status: needs rebase label Dec 8, 2025

story645 approved these changes Jan 6, 2026

View reviewed changes

trygvrad force-pushed the multivar_imshow branch from ea43447 to 435d92a Compare February 20, 2026 19:24

timhoffm reviewed Feb 21, 2026

View reviewed changes

timhoffm approved these changes Feb 23, 2026

View reviewed changes

Comment thread lib/matplotlib/colorizer.py Outdated

Comment thread lib/matplotlib/colorizer.py Outdated

Comment thread lib/matplotlib/colorizer.py Outdated

trygvrad mentioned this pull request Feb 27, 2026

Multivar colorbar #31214

Open

trygvrad moved this from In Progress to Ready to be merged in Bivariate and Multivariate Colormapping Feb 27, 2026

github-actions Bot added the status: needs rebase label Mar 2, 2026

trygvrad force-pushed the multivar_imshow branch from 83f4167 to 6626f26 Compare April 23, 2026 22:23

github-actions Bot removed the status: needs rebase label Apr 23, 2026

github-actions Bot added the status: needs rebase label May 28, 2026

trygvrad and others added 8 commits June 6, 2026 21:47

expose multivariate plotting functionality to top level functions ims…

4a2cfc9

…how, pcolor, pcolormesh, and Collection

updates from code review

ca83ad3

thank you @story645 @ksunden

Apply suggestions from code review

02016b5

Co-authored-by: Kyle Sunden <[email protected]>

improved consistency of return types for better typing

ddcfe37

implementing feedback from story645

fce7799

doc fix for _ColorizerInterface.get_clim()

5393cba

update based on feedback from @timhoffm

b8caed7

Apply suggestions from code review

fdb3725

Co-authored-by: Tim Hoffmann <[email protected]>

trygvrad force-pushed the multivar_imshow branch from 6626f26 to fdb3725 Compare June 6, 2026 21:08

github-actions Bot removed the status: needs rebase label Jun 6, 2026

multivar imshow additional test

d49ef95

trygvrad force-pushed the multivar_imshow branch from fac9556 to d49ef95 Compare June 6, 2026 23:56

timhoffm reviewed Jun 9, 2026

View reviewed changes

updates based on feedback from @timhoffm

b701032

		C = mcolorizer._ensure_multivariate_data(args[-1],
		colorizer.cmap.n_variates)

Uh oh!

Conversation

trygvrad commented Sep 24, 2025 • edited by timhoffm Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

trygvrad commented Nov 2, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ksunden left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

trygvrad commented Dec 1, 2025

Uh oh!

story645 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

trygvrad commented Feb 20, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

trygvrad commented Feb 22, 2026

Uh oh!

timhoffm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

trygvrad commented Feb 27, 2026

Uh oh!

story645 commented Mar 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

timhoffm commented Mar 1, 2026

trygvrad commented Sep 24, 2025 •

edited by timhoffm

Loading

story645 commented Mar 1, 2026 •

edited

Loading