Multivariate plotting in imshow, pcolor and pcolormesh #29221

trygvrad · 2024-12-03T09:05:24Z

PR summary

This PR continues the work of #28658 and #28454, aiming to close #14168.

Features included in this PR:

A MultiNorm class. This is a subclass of colors.Normalize and holds n_variate norms.
Exposes the functionality provided by MultiNorm together with BivarColormap and MultivarColormap to the plotting functions axes.imshow(...), axes.pcolor, and `axes.pcolormesh(...)

import matplotlib.pyplot as plt
import numpy as np

im_A = np.arange(500)[np.newaxis, :]*np.ones((100, 500))
im_B = np.arange(100)[:, np.newaxis]*np.ones((100, 500))
im_A[:, :] = np.sin(im_A**0.5)**2
im_B[:, :] = np.sin(im_B**0.5)**2

fig, axes = plt.subplots(3, 1, figsize=(8, 6))

cm = axes[0].imshow(im_A, cmap='grey', vmin=0, vmax=1)
axes[0].set_title('A')

cm = axes[1].imshow(im_B, cmap='grey', vmin=0, vmax=1)
axes[1].set_title('B')

cm = axes[2].imshow((im_A, im_B),
                    cmap='BiOrangeBlue',
                    vmin=(0, 0), vmax=(1, 1))
axes[2].set_title('A & B')
for ax in axes:
    ax.set_xticks([])
    ax.set_yticks([])

Features not included in this PR:

Multivariate equivalent of fig.colorbar(...). I will make a draft for this, but I may need help with regards to the layout engine.
Examples. Some documentation is ready on a separate branch, see this, and this, but the PR that includes these will be made after we find a fig.colorbar(...) solution for bivariate/multivariate colormaps.
A selection of colormaps. I have written about this here and here. You can see the proposed colormaps/documentation here and [here](file:///home/trygvrad/trygvrad.github.io/mpl_docs/Bivariate colormap reference.html), but we will need a separate discussion on these (in particular regarding the names)
The multivariate implementation for axes.imshow(...) included here only accepts interpolation_stage=='rgba', and not interpolation_stage=='data'.

PR checklist

"closes Feature request: Bivariate colormapping #14168", but I suggest we keep Feature request: Bivariate colormapping #14168 open until we have a fig.colorbar(...) equivalent for multivariate colormaps.
new and changed code is tested
Plotting related features are demonstrated in an example
New Features and API Changes are noted with a directive and release note
Documentation complies with general and docstring guidelines

trygvrad · 2024-12-03T09:10:27Z

Also: this does not (yet) include changes to the docstrings, i.e. the following will need to change:

"""

Parameters
----------
X : array-like or PIL image
    The image data. Supported array shapes are:

    - (M, N): an image with scalar data. The values are mapped to
      colors using normalization and a colormap. See parameters *norm*,
      *cmap*, *vmin*, *vmax*.
    - (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.

    The first two dimensions (M, N) define the rows and columns of
    the image.

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

to include a line like

"""
etc.
    - (K, M, N): multiple images with scalar data when combined with a
    multivariate or bivariate colormap using a MultiNorm.
"""

trygvrad · 2025-01-06T13:11:08Z

I updated the docstrings, so now this PR should be ready for review.

There is an error with the docs on circleci, but I haven't found a link between the error and the changes made in this PR, so I believe it to be unrelated.

lib/matplotlib/axes/_axes.py

lib/matplotlib/cbook.py

lib/matplotlib/colorizer.py

lib/matplotlib/colors.py

lib/matplotlib/tests/test_multivariate_axes.py

trygvrad · 2025-02-08T10:19:34Z

@story645
Thank you for the feedback :)
I believe I have addressed all the comments now (I'll mark them as resolved in the coming days).

also: this will need a squash-merge

lib/matplotlib/axes/_axes.py

lib/matplotlib/colorizer.py

tacaswell · 2025-02-20T20:43:12Z

lib/matplotlib/colorizer.py

+            # pass scalar data
+            # and already formatted data
+            return data
+        elif data.dtype in [np.complex64, np.complex128]:


Option 1 please.

lib/matplotlib/colors.py

tacaswell · 2025-02-20T20:58:00Z

lib/matplotlib/image.py

        if A.ndim == 3 and A.shape[-1] == 1:
            A = A.squeeze(-1)  # If just (M, N, 1), assume scalar and apply colormap.
        if not (A.ndim == 2 or A.ndim == 3 and A.shape[-1] in [3, 4]):
+            if A.ndim == 3 and A.shape[0] == 2:


to verify, these are here as a hint to the user to use multi-variate color maps and data that would have failed before would still fail now?

Yes, that is the intention

tacaswell · 2025-02-20T21:01:12Z

lib/matplotlib/image.py

+                raise TypeError(f"Image data of dtype {A.dtype} cannot be "
+                                f"converted to float")
+        else:
+            for key in A.dtype.fields:


I think this fails to catch n_input >1 + non-float-like + non-structured data?

This might be true.
I'm trying to think of a data type that can not be cast to float and is not structured in order to test this

If you try something with data type object, it depends a bit on the shape, all the cases I have tried have been caught:

fig, ax = plt.subplots() im = np.empty((5,5), dtype='object') ax.imshow(im, cmap='BiOrangeBlue') > ValueError: Invalid data entry for mutlivariate data. The data must contain complex numbers, or have a first dimension 2, or be of a dtype with 2 fields im = np.empty((2,5,5), dtype='object') ax.imshow(im, cmap='BiOrangeBlue') > TypeError: Image data of dtype [('f0', 'O'), ('f1', 'O')] cannot be converted to a sequence of floats

Where the first error originates in colorizer._ensure_multivariate_data()

Do you have some idea of other tests I should run, or do we want to have specific tests for _normalize_image_array()?

lib/matplotlib/image.py

tacaswell · 2025-02-20T21:05:02Z

lib/matplotlib/image.py

        """
        Check validity of image-like input *A* and normalize it to a format suitable for
        Image subclasses.
        """
+        A = mcolorizer._ensure_multivariate_data(n_input, A)


minor thing. bit jarring that sometimes the API in f(n_input, A) and othertimes f(A, n_input). I think we should prefer f(A, n_input) everywhere for internal consistency and no-API change on existing functions (like the one we are in now).

This is a good comment :) I will try to address it soon

I changed the call signature of colorizer._ensure_multivariate_data(...) to colorizer._ensure_multivariate_data(A, n_input)

I looked to see if there were any other functions with a similar signature which should be flipped, but I did not find any in my quick search.

story645 · 2025-02-27T21:34:35Z

If you've got the bandwidth, @greglucas can you give this a look (skim) since you've been working on colormapping?

trygvrad · 2025-03-10T14:38:59Z

@greglucas It would be great to know if/when you will have time to look at this :)
Just let us know if you don't have the bandwidth right now, and we can poke someone else

trygvrad · 2025-03-27T21:23:37Z

@story645 @tacaswell would you two be willing to finish your review of this?
Or perhaps @ksunden?

EDIT: my apologies @story645 I didn't see you had just assigned this when I wrote my comment :)

story645 · 2025-04-01T19:28:27Z

@anntzer asked if the more cleanup/refactor/not directly necessary for implementation parts of this PR could be spun off into a different set and if this PR could get rebased to clean up the commit history.

anntzer · 2025-04-01T22:00:16Z

(Just to give an example, I'm currently splitting off #29807 into a bunch of smaller preparatory PRs: #29817, #29828, #29838, #29843, #29829.)

trygvrad · 2025-04-01T22:35:18Z

@anntzer I'll see what I can do.
I thinking of splitting it as:

1. MultiNorm class
2a. Add support for multivariate pcolor and pcolormesh + tests 
2b. Add support for multivariate imshow + tests

I'll also see if there are some misc changes that can be a separate PR between 1 and 2.
In any case, 1. will have to be merged before 2a and b. Would you like me to make all the branches at once, or does it make more sense to make the PR for 2a and b once 1. is merged?

anntzer · 2025-04-02T06:28:21Z

I guess it doesn't really matter, because we know the end result thanks to this PR anyways.
(I won't be able to review anything before next week, in any case.)

trygvrad · 2025-04-06T14:10:30Z

@anntzer @story645 I opened PRs:
#29876 → The MultiNorm class
#29877 → Other changes needed to expose the functionality.

Hopefully this is easier to review :)

If an image is shown, and the user hovers over the image, the value at that coordinate should be displayed. The number formating is handled by colorizer.Colorizer._format_cursor_data_override(). This is now updated to also handle the case where a MultiNorm is used (i.e. a bivariat or multivariate colormap), in which case multiple values are displayed.

The previous version of this test passed for numpy 1.x but not for 2.x. This should pass for both

Co-authored-by: Thomas A Caswell <tcaswell@gmail.com>

…ha in imshow

changed from colorizer._ensure_multivariate_data(n_input, A) to colorizer._ensure_multivariate_data(A, n_input)

github-actions bot added topic: color/color & colormaps topic: images topic: collections and mappables labels Dec 3, 2024

This was referenced Dec 13, 2024

2D Normalization & Colormapping for ScalerMappables #8738

Closed

Wishlist: Multidimensional colormaps #4369

Closed

github-actions bot added the status: needs rebase label Dec 20, 2024

github-actions bot added the Documentation: API files in lib/ and doc/api label Jan 6, 2025

trygvrad force-pushed the multivariate-norm branch from 5afd692 to 90680bd Compare January 6, 2025 08:56

github-actions bot removed the status: needs rebase label Jan 6, 2025

trygvrad force-pushed the multivariate-norm branch from 90680bd to 206c9b8 Compare January 6, 2025 10:52

tacaswell modified the milestones: v3.10.0-doc, v3.11.0 Jan 23, 2025

story645 reviewed Jan 28, 2025

View reviewed changes

github-actions bot added status: needs rebase topic: transforms and scales labels Feb 1, 2025

trygvrad force-pushed the multivariate-norm branch from d4215a3 to e30e7e6 Compare February 8, 2025 10:18

github-actions bot removed the status: needs rebase label Feb 8, 2025

trygvrad force-pushed the multivariate-norm branch from e30e7e6 to f936378 Compare February 20, 2025 19:18

tacaswell reviewed Feb 20, 2025

View reviewed changes

lib/matplotlib/axes/_axes.py Outdated Show resolved Hide resolved

tacaswell reviewed Feb 20, 2025

View reviewed changes

lib/matplotlib/axes/_axes.py Outdated Show resolved Hide resolved

tacaswell reviewed Feb 20, 2025

View reviewed changes

lib/matplotlib/colorizer.py Outdated Show resolved Hide resolved

tacaswell reviewed Feb 20, 2025

View reviewed changes

trygvrad force-pushed the multivariate-norm branch from 63e789a to 7fc99b5 Compare February 24, 2025 21:18

github-actions bot added the status: needs rebase label Feb 28, 2025

trygvrad force-pushed the multivariate-norm branch from 7fc99b5 to dc6dee7 Compare March 9, 2025 15:45

github-actions bot removed the status: needs rebase label Mar 9, 2025

apcamargo mentioned this pull request Mar 14, 2025

Support for bivariate colormaps pyapp-kit/cmap#90

Open

story645 assigned story645 and anntzer Mar 27, 2025

This was referenced Apr 6, 2025

MultiNorm class #29876

Open

Preparations for multivariate plotting #29877

Open

trygvrad and others added 12 commits April 13, 2025 13:13

MultiNorm class

1ad6e44

Multivariate plots for imshow, pcolor and pcolormesh

b00cf92

docstrings for multivariate plotting in imshow, pcolor and pcolormesh

7755c90

Additional tests for colors.MultiNorm

65f41c0

Incorporating feedback from @story645

5bab105

More feedback from @story645

5189e61

updated test for im.format_cursor_data

86c46a4

The previous version of this test passed for numpy 1.x but not for 2.x. This should pass for both

Apply suggestions from tacaswell

e63aa3d

Co-authored-by: Thomas A Caswell <tcaswell@gmail.com>

updated test image multivariate_imshow_alpha.png due to a fix for alp…

cbb1979

…ha in imshow

change call signature of colorizer._ensure_multivariate_data()

e1ee7dc

changed from colorizer._ensure_multivariate_data(n_input, A) to colorizer._ensure_multivariate_data(A, n_input)

updated reference images in response to fix on main

fa40bef

trygvrad force-pushed the multivariate-norm branch from 29093b3 to fa40bef Compare April 13, 2025 11:40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Multivariate plotting in imshow, pcolor and pcolormesh #29221

Multivariate plotting in imshow, pcolor and pcolormesh #29221

trygvrad commented Dec 3, 2024

trygvrad commented Dec 3, 2024

trygvrad commented Jan 6, 2025

trygvrad commented Feb 8, 2025 •

edited

Loading

tacaswell Feb 20, 2025

tacaswell Feb 20, 2025

trygvrad Feb 23, 2025

tacaswell Feb 20, 2025

trygvrad Feb 23, 2025

tacaswell Feb 20, 2025

trygvrad Feb 23, 2025

trygvrad Feb 24, 2025

story645 commented Feb 27, 2025

trygvrad commented Mar 10, 2025

trygvrad commented Mar 27, 2025 •

edited

Loading

story645 commented Apr 1, 2025

anntzer commented Apr 1, 2025

trygvrad commented Apr 1, 2025 •

edited

Loading

anntzer commented Apr 2, 2025

trygvrad commented Apr 6, 2025

Multivariate plotting in imshow, pcolor and pcolormesh #29221

Are you sure you want to change the base?

Multivariate plotting in imshow, pcolor and pcolormesh #29221

Conversation

trygvrad commented Dec 3, 2024

PR summary

PR checklist

trygvrad commented Dec 3, 2024

trygvrad commented Jan 6, 2025

trygvrad commented Feb 8, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

story645 commented Feb 27, 2025

trygvrad commented Mar 10, 2025

trygvrad commented Mar 27, 2025 • edited Loading

story645 commented Apr 1, 2025

anntzer commented Apr 1, 2025

trygvrad commented Apr 1, 2025 • edited Loading

anntzer commented Apr 2, 2025

trygvrad commented Apr 6, 2025

trygvrad commented Feb 8, 2025 •

edited

Loading

trygvrad commented Mar 27, 2025 •

edited

Loading

trygvrad commented Apr 1, 2025 •

edited

Loading