Multivar imshow #30597

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 coloses #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-10-30T20:29:22Z

lib/matplotlib/cbook.py

+        if len(x.dtype.descr) == 1:
+            # Arrays with dtype 'object' get returned here.
+            # For example the 'c' kwarg of scatter, which supports multiple types.
+            # `plt.scatter([3, 4], [2, 5], c=[(1, 0, 0), 'y'])`
+            return x
+        else:
+            # In case of a dtype with multiple fields
+            # for example image data using a MultiNorm
+            try:
+                mask = np.empty(x.shape, dtype=np.dtype('bool, '*len(x.dtype.descr)))
+                for dd, dm in zip(x.dtype.descr, mask.dtype.descr):
+                    mask[dm[0]] = ~np.isfinite(x[dd[0]])
+                xm = np.ma.array(x, mask=mask, copy=False)
+            except TypeError:
+                return x
    return xm


Does this get recycled in other places and if so should it be factored into it;s own private function?

I don't think this is used anywhere else

story645 · 2025-11-20T20:19:11Z

lib/matplotlib/axes/_axes.py

+            Only 'data' is available when using `~matplotlib.colors.BivarColormap`
+            or `~matplotlib.colors.MultivarColormap`


what do you mean by data?

'data' refers to the keyword argument interpolation_stage

interpolation_stage : {'auto', 'data', 'rgba'}, default: 'auto' Supported values: - 'data': Interpolation is carried out on the data provided by the user This is useful if interpolating between pixels during upsampling. - 'rgba': The interpolation is carried out in RGBA-space after the color-mapping has been applied. This is useful if downsampling and combining pixels visually. - 'auto': Select a suitable interpolation stage automatically. This uses 'rgba' when downsampling, or upsampling at a rate less than 3, and 'data' when upsampling at a higher rate. See :doc:`/gallery/images_contours_and_fields/image_antialiasing` for a discussion of image antialiasing. Only 'data' is available when using `~matplotlib.colors.BivarColormap` or `~matplotlib.colors.MultivarColormap`

I'm changing the last lines to:

When using a `~matplotlib.colors.BivarColormap` or `~matplotlib.colors.MultivarColormap`, 'data' is the only valid interpolation_stage.

in an attempt to increase clarity

story645 · 2025-11-20T20:22:18Z

lib/matplotlib/axes/_axes.py

+        C : 2D or 3D array-like
            The color-mapped values.  Color-mapping is controlled by *cmap*,
-            *norm*, *vmin*, and *vmax*.
+            *norm*, *vmin*, and *vmax*. 3D arrays are supported only if the
+            cmap supports v channels, where v is the size along the first axis.



I think (?, ?, ?) notation might help make this clearer?

good idea. Does the following work for you?

Parameters ---------- C : 2D (I, J) or 3D (v, I, J) array-like The color-mapped values. Color-mapping is controlled by *cmap*, *norm*, *vmin*, and *vmax*. 3D arrays are supported only if the cmap supports v channels. X, Y : array-like, optional The coordinates of the corners of quadrilaterals of a pcolormesh:: (X[i+1, j], Y[i+1, j]) (X[i+1, j+1], Y[i+1, j+1]) ●╶───╴● │ │ ●╶───╴● (X[i, j], Y[i, j]) (X[i, j+1], Y[i, j+1]) Note that the column index corresponds to the x-coordinate, and the row index corresponds to y. For details, see the :ref:`Notes <axes-pcolormesh-grid-orientation>` section below. If ``shading='flat'`` the dimensions of *X* and *Y* should be one greater than those of *C*, and the quadrilateral is colored due to the value at ``C[i, j]``. If *X*, *Y* and *C* have equal dimensions, a warning will be raised and the last row and column of *C* will be ignored.

I'm using uppercase I and J in C : 2D (I, J) or 3D (v, I, J) array-like as these refer to the length, while the lowercase versions are used further down for the corresponding indexes.

story645 · 2025-11-20T20:26:40Z

lib/matplotlib/axes/_axes.py

+        if colorizer is None:
+            cmap = mcolorizer._ensure_cmap(cmap, accept_multivariate=True)
+            C = mcolorizer._ensure_multivariate_data(args[-1], cmap.n_variates)
+        else:
+            C = mcolorizer._ensure_multivariate_data(args[-1],
+                                                     colorizer.cmap.n_variates)


Suggested change

if colorizer is None:

cmap = mcolorizer._ensure_cmap(cmap, accept_multivariate=True)

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

else:

C = mcolorizer._ensure_multivariate_data(args[-1],

colorizer.cmap.n_variates)

if colorizer is None:

cmap = mcolorizer._ensure_cmap(cmap, accept_multivariate=True)

colorizer =

C = mcolorizer._ensure_multivariate_data(args[-1],

colorizer.cmap.n_variates)

is there a reason to not instantiate the colorizer here?

I believe it was designed this way to ensure error handling was done in the same way as previously, but I was able to rework it to a cleaner state by doing

mcolorizer.ColorizingArtist._check_exclusionary_keywords(colorizer, vmin=vmin, vmax=vmax, norm=norm, cmap=cmap)

before the creation of the QuadMesh rather than

collection._check_exclusionary_keywords(colorizer, vmin=vmin, vmax=vmax)

after.

story645 · 2025-11-20T20:27:41Z

lib/matplotlib/axes/_axes.py

+        if colorizer is None:
+            cmap = mcolorizer._ensure_cmap(cmap, accept_multivariate=True)
+            C = mcolorizer._ensure_multivariate_data(args[-1], cmap.n_variates)
+        else:
+            C = mcolorizer._ensure_multivariate_data(args[-1],
+                                                     colorizer.cmap.n_variates)
+


potentially turn into a helper function if it repeats?

The following lines are repeated for pcolor and pcolormesh:

mcolorizer.ColorizingArtist._check_exclusionary_keywords(colorizer, vmin=vmin, vmax=vmax, norm=norm, cmap=cmap) if colorizer is None: colorizer = mcolorizer.Colorizer(cmap=cmap, norm=norm) C = mcolorizer._ensure_multivariate_data(args[-1], colorizer.cmap.n_variates)

We could make this a helper function :)
If so, should it be part of the Axes class? and do you have a suggestion for a name?

EDIT: this is after modifying it in accordance with one of your comments above :)

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

lib/matplotlib/tests/test_axes.py

+    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 :)

story645 · 2025-11-20T20:50:22Z

lib/matplotlib/image.py

+                raise ValueError("'data' is the only valid interpolation_stage "
+                                 "when using multiple color channels, not "
+                                 f"{interpolation_stage}")


flip this around to start with the error then reason then solution

story645 · 2025-11-20T20:53:06Z

lib/matplotlib/image.py

+                A_resampled = [_resample(self, a.astype(_get_scaled_dtype(a)),
+                                         out_shape, t)
+                               for a in arrs]


Suggested change

A_resampled = [_resample(self, a.astype(_get_scaled_dtype(a)),

out_shape, t)

for a in arrs]

A_resampled = [_resample(self,

a.astype(_get_scaled_dtype(a)), out_shape, t)

for a in arrs]

just that the line break here is weird

story645 · 2025-11-20T20:55:02Z

lib/matplotlib/image.py

+                mask = (np.where(self._getmaskarray(A), np.float32(np.nan),
+                                 np.float32(1))


Suggested change

mask = (np.where(self._getmaskarray(A), np.float32(np.nan),

np.float32(1))

mask = (np.where(self._getmaskarray(A), np.float32(np.nan), np.float32(1))

story645 · 2025-11-20T20:58:50Z

lib/matplotlib/image.py

    return fig
+
+
+def _get_scaled_dtype(A):


make it an inline function inside _make_image

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

lib/matplotlib/axes/_axes.pyi

ksunden · 2025-11-20T20:33:58Z

lib/matplotlib/colorizer.pyi

    def norm(self) -> colors.Norm: ...
    @norm.setter
-    def norm(self, norm: colors.Norm | str | None) -> None: ...
+    def norm(self, norm: colors.Norm | str | tuple[str] | None) -> None: ...


tuple[str, ...]

lib/matplotlib/pyplot.py

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?

…how, pcolor, pcolormesh, and Collection

@story645

thank you @story645 @ksunden

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

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 requested changes Nov 20, 2025

View reviewed changes

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

trygvrad and others added 3 commits December 1, 2025 14:55

expose multivariate plotting functionality to top level functions ims…

50f55a8

…how, pcolor, pcolormesh, and Collection

updates from code review

b935040

thank you @story645 @ksunden

Apply suggestions from code review

0a1597b

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

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

improved consistency of return types for better typing

053e524

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

		Only 'data' is available when using `~matplotlib.colors.BivarColormap`
		or `~matplotlib.colors.MultivarColormap`

		mask = (np.where(self._getmaskarray(A), np.float32(np.nan),
		np.float32(1))

Uh oh!

Multivar imshow #30597

Are you sure you want to change the base?

Multivar imshow #30597

Uh oh!

Conversation

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

Uh oh!

Uh oh!

trygvrad commented Nov 2, 2025

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!

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!

trygvrad Nov 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ksunden left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

trygvrad commented Dec 1, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

trygvrad commented Sep 24, 2025 •

edited

Loading

trygvrad Nov 30, 2025 •

edited

Loading