Skip to content

Multivar imshow #30597

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
trygvrad wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Multivar imshow #30597

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
50f55a8
expose multivariate plotting functionality to top level functions ims…
trygvrad Sep 24, 2025
b935040
updates from code review
trygvrad Nov 30, 2025
0a1597b
Apply suggestions from code review
trygvrad Dec 1, 2025
053e524
improved consistency of return types for better typing
trygvrad Dec 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/api/colors_api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ Multivariate Colormaps
BivarColormap
SegmentedBivarColormap
BivarColormapFromImage
MultivarColormap

Other classes
-------------
Expand Down
64 changes: 45 additions & 19 deletions lib/matplotlib/axes/_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6150,6 +6150,7 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None,
- (M, N): an image with scalar data. The values are mapped to
colors using normalization and a colormap. See parameters *norm*,
*cmap*, *vmin*, *vmax*.
- (v, M, N): if coupled with a cmap that supports v scalars
- (M, N, 3): an image with RGB values (0-1 float or 0-255 int).
- (M, N, 4): an image with RGBA values (0-1 float or 0-255 int),
i.e. including transparency.
Expand All @@ -6159,15 +6160,16 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None,

Out-of-range RGB(A) values are clipped.

%(cmap_doc)s

%(multi_cmap_doc)s

This parameter is ignored if *X* is RGB(A).

%(norm_doc)s
%(multi_norm_doc)s

This parameter is ignored if *X* is RGB(A).

%(vmin_vmax_doc)s
%(multi_vmin_vmax_doc)s

This parameter is ignored if *X* is RGB(A).

Expand Down Expand Up @@ -6246,6 +6248,10 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None,
See :doc:`/gallery/images_contours_and_fields/image_antialiasing` for
a discussion of image antialiasing.

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

alpha : float or array-like, optional
The alpha blending value, between 0 (transparent) and 1 (opaque).
If *alpha* is an array, the alpha blending values are applied pixel
Expand Down Expand Up @@ -6351,6 +6357,7 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None,
if aspect is not None:
self.set_aspect(aspect)

X = mcolorizer._ensure_multivariate_data(X, im.norm.n_components)
im.set_data(X)
im.set_alpha(alpha)
if im.get_clip_path() is None:
Expand Down Expand Up @@ -6506,9 +6513,10 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,

Parameters
----------
C : 2D array-like
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*.
*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::
Expand Down Expand Up @@ -6555,11 +6563,11 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
See :doc:`/gallery/images_contours_and_fields/pcolormesh_grids`
for more description.

%(cmap_doc)s
%(multi_cmap_doc)s

%(norm_doc)s
%(multi_norm_doc)s

%(vmin_vmax_doc)s
%(multi_vmin_vmax_doc)s

%(colorizer_doc)s

Expand Down Expand Up @@ -6634,8 +6642,19 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
if shading is None:
shading = mpl.rcParams['pcolor.shading']
shading = shading.lower()
X, Y, C, shading = self._pcolorargs('pcolor', *args, shading=shading,
kwargs=kwargs)

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)

X, Y, C, shading = self._pcolorargs('pcolor', *args[:-1], C,
shading=shading, kwargs=kwargs)

linewidths = (0.25,)
if 'linewidth' in kwargs:
kwargs['linewidths'] = kwargs.pop('linewidth')
Expand Down Expand Up @@ -6670,9 +6689,7 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
coords = stack([X, Y], axis=-1)

collection = mcoll.PolyQuadMesh(
coords, array=C, cmap=cmap, norm=norm, colorizer=colorizer,
alpha=alpha, **kwargs)
collection._check_exclusionary_keywords(colorizer, vmin=vmin, vmax=vmax)
coords, array=C, colorizer=colorizer, alpha=alpha, **kwargs)
collection._scale_norm(norm, vmin, vmax)

coords = coords.reshape(-1, 2) # flatten the grid structure; keep x, y
Expand Down Expand Up @@ -6710,6 +6727,7 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
- (M, N) or M*N: a mesh with scalar data. The values are mapped to
colors using normalization and a colormap. See parameters *norm*,
*cmap*, *vmin*, *vmax*.
- (v, M, N): if coupled with a cmap that supports v scalars
- (M, N, 3): an image with RGB values (0-1 float or 0-255 int).
- (M, N, 4): an image with RGBA values (0-1 float or 0-255 int),
i.e. including transparency.
Expand Down Expand Up @@ -6746,11 +6764,11 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
expanded as needed into the appropriate 2D arrays, making a
rectangular grid.

%(cmap_doc)s
%(multi_cmap_doc)s

%(norm_doc)s
%(multi_norm_doc)s

%(vmin_vmax_doc)s
%(multi_vmin_vmax_doc)s

%(colorizer_doc)s

Expand Down Expand Up @@ -6873,16 +6891,24 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
shading = mpl._val_or_rc(shading, 'pcolor.shading').lower()
kwargs.setdefault('edgecolors', 'none')

X, Y, C, shading = self._pcolorargs('pcolormesh', *args,
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)

X, Y, C, shading = self._pcolorargs('pcolormesh', *args[:-1], C,
shading=shading, kwargs=kwargs)
coords = np.stack([X, Y], axis=-1)

kwargs.setdefault('snap', mpl.rcParams['pcolormesh.snap'])

collection = mcoll.QuadMesh(
coords, antialiased=antialiased, shading=shading,
array=C, cmap=cmap, norm=norm, colorizer=colorizer, alpha=alpha, **kwargs)
collection._check_exclusionary_keywords(colorizer, vmin=vmin, vmax=vmax)
array=C, colorizer=colorizer, alpha=alpha, **kwargs)
collection._scale_norm(norm, vmin, vmax)

coords = coords.reshape(-1, 2) # flatten the grid structure; keep x, y
Expand Down
32 changes: 19 additions & 13 deletions lib/matplotlib/axes/_axes.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,13 @@ from matplotlib.collections import (
QuadMesh,
)
from matplotlib.colorizer import Colorizer
from matplotlib.colors import Colormap, Normalize
from matplotlib.colors import (
Colormap,
BivarColormap,
MultivarColormap,
Norm,
Normalize,
)
from matplotlib.container import (
BarContainer, PieContainer, ErrorbarContainer, StemContainer)
from matplotlib.contour import ContourSet, QuadContourSet
Expand Down Expand Up @@ -500,14 +506,14 @@ class Axes(_AxesBase):
def imshow(
self,
X: ArrayLike | PIL.Image.Image,
cmap: str | Colormap | None = ...,
norm: str | Normalize | None = ...,
cmap: str | Colormap | BivarColormap | MultivarColormap | None = ...,
norm: str | Norm | None = ...,
*,
aspect: Literal["equal", "auto"] | float | None = ...,
interpolation: str | None = ...,
alpha: float | ArrayLike | None = ...,
vmin: float | None = ...,
vmax: float | None = ...,
vmin: float | tuple[float, ...] | None = ...,
vmax: float | tuple[float, ...] | None = ...,
colorizer: Colorizer | None = ...,
origin: Literal["upper", "lower"] | None = ...,
extent: tuple[float, float, float, float] | None = ...,
Expand All @@ -524,10 +530,10 @@ class Axes(_AxesBase):
*args: ArrayLike,
shading: Literal["flat", "nearest", "auto"] | None = ...,
alpha: float | None = ...,
norm: str | Normalize | None = ...,
cmap: str | Colormap | None = ...,
vmin: float | None = ...,
vmax: float | None = ...,
norm: str | Norm | None = ...,
cmap: str | Colormap | BivarColormap | MultivarColormap | None = ...,
vmin: float | tuple[float, ...] | None = ...,
vmax: float | tuple[float, ...] | None = ...,
colorizer: Colorizer | None = ...,
data=...,
**kwargs
Expand All @@ -536,10 +542,10 @@ class Axes(_AxesBase):
self,
*args: ArrayLike,
alpha: float | None = ...,
norm: str | Normalize | None = ...,
cmap: str | Colormap | None = ...,
vmin: float | None = ...,
vmax: float | None = ...,
norm: str | Norm | None = ...,
cmap: str | Colormap | BivarColormap | MultivarColormap | None = ...,
vmin: float | tuple[float, ...] | None = ...,
vmax: float | tuple[float, ...] | None = ...,
colorizer: Colorizer | None = ...,
shading: Literal["flat", "nearest", "gouraud", "auto"] | None = ...,
antialiased: bool = ...,
Expand Down
4 changes: 3 additions & 1 deletion lib/matplotlib/collections.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2352,6 +2352,8 @@ def set_array(self, A):
h, w = height, width
ok_shapes = [(h, w, 3), (h, w, 4), (h, w), (h * w,)]
if A is not None:
if hasattr(self, 'norm'):
A = mcolorizer._ensure_multivariate_data(A, self.norm.n_components)
shape = np.shape(A)
if shape not in ok_shapes:
raise ValueError(
Expand Down Expand Up @@ -2609,7 +2611,7 @@ def _get_unmasked_polys(self):
mask = (mask[0:-1, 0:-1] | mask[1:, 1:] | mask[0:-1, 1:] | mask[1:, 0:-1])
arr = self.get_array()
if arr is not None:
arr = np.ma.getmaskarray(arr)
arr = self._getmaskarray(arr)
if arr.ndim == 3:
# RGB(A) case
mask |= np.any(arr, axis=-1)
Expand Down
11 changes: 8 additions & 3 deletions lib/matplotlib/collections.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,12 @@ from numpy.typing import ArrayLike, NDArray
from . import colorizer, transforms
from .backend_bases import MouseEvent
from .artist import Artist
from .colors import Normalize, Colormap
from .colors import (
Colormap,
BivarColormap,
MultivarColormap,
Norm,
)
from .lines import Line2D
from .path import Path
from .patches import Patch
Expand All @@ -29,8 +34,8 @@ class Collection(colorizer.ColorizingArtist):
antialiaseds: bool | Sequence[bool] | None = ...,
offsets: tuple[float, float] | Sequence[tuple[float, float]] | None = ...,
offset_transform: transforms.Transform | None = ...,
norm: Normalize | None = ...,
cmap: Colormap | None = ...,
norm: Norm | None = ...,
cmap: Colormap | BivarColormap | MultivarColormap | None = ...,
colorizer: colorizer.Colorizer | None = ...,
pickradius: float = ...,
hatch: str | None = ...,
Expand Down
38 changes: 34 additions & 4 deletions lib/matplotlib/colorizer.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ def _scale_norm(self, norm, vmin, vmax, A):
"""
if vmin is not None or vmax is not None:
self.set_clim(vmin, vmax)
if isinstance(norm, colors.Normalize):
if isinstance(norm, colors.Norm):
raise ValueError(
"Passing a Normalize instance simultaneously with "
"vmin/vmax is not supported. Please pass vmin/vmax "
Expand Down Expand Up @@ -278,7 +278,10 @@ def get_clim(self):
"""
Return the values (min, max) that are mapped to the colormap limits.
"""
return self.norm.vmin, self.norm.vmax
if self.norm.n_components == 1:
return (self.norm.vmin, ), (self.norm.vmax, )
else:
return self.norm.vmin, self.norm.vmax

def changed(self):
"""
Expand Down Expand Up @@ -306,7 +309,10 @@ def vmax(self, vmax):

@property
def clip(self):
return self.norm.clip
if self.norm.n_components == 1:
return (self.norm.clip, )
else:
return self.norm.clip

@clip.setter
def clip(self, clip):
Expand Down Expand Up @@ -360,8 +366,14 @@ def to_rgba(self, x, alpha=None, bytes=False, norm=True):
def get_clim(self):
"""
Return the values (min, max) that are mapped to the colormap limits.

This function is not available for multivariate data.
"""
return self._colorizer.get_clim()
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

def set_clim(self, vmin=None, vmax=None):
"""
Expand All @@ -376,9 +388,15 @@ def set_clim(self, vmin=None, vmax=None):
tuple (*vmin*, *vmax*) as a single positional argument.

.. ACCEPTS: (vmin: float, vmax: float)

This function is not available for multivariate data.
"""
# If the norm's limits are updated self.changed() will be called
# through the callbacks attached to the norm
if self._colorizer.norm.n_components > 1:
raise AttributeError("`.set_clim(vmin, vmax)` is unavailable "
"when using a colormap with multiple components. Use "
"`.colorizer.set_clim(vmin, vmax)` instead")
self._colorizer.set_clim(vmin, vmax)

def get_alpha(self):
Expand Down Expand Up @@ -600,6 +618,18 @@ def get_array(self):
"""
return self._A

def _getmaskarray(self, A):
"""
Similar to np.ma.getmaskarray but also handles the case where
the data has multiple fields.

The return array always has the same shape as the input, and dtype bool
"""
mask = np.ma.getmaskarray(A)
if isinstance(self.norm, colors.MultiNorm):
mask = np.any(mask.view('bool').reshape((*A.shape, -1)), axis=-1)
return mask

def changed(self):
"""
Call this whenever the mappable is changed to notify all the
Expand Down
Loading
Loading