MultiNorm class #29876

trygvrad · 2025-04-06T14:05:33Z

PR summary

This PR continues the work of #28658 and #28454, aiming to close #14168. (Feature request: Bivariate colormapping)

This is part one of the former PR, #29221. Please see #29221 for the previous discussion

Features included in this PR:

A MultiNorm class. This is a subclass of colors.Normalize and holds n_variate norms.
Testing of the MultiNorm class

Features not included in this PR:

changes to colorizer.py needed to expose the MultiNorm class
Exposes the functionality provided by MultiNorm together with BivarColormap and MultivarColormap to the plotting functions axes.imshow(...), axes.pcolor, and `axes.pcolormesh(...)
Testing of the new plotting methods
Examples in the docs

lib/matplotlib/colors.py

lib/matplotlib/scale.py

lib/matplotlib/colors.py

QuLogic · 2025-04-17T08:30:28Z

lib/matplotlib/colors.py

+    in the case where an invalid string is used. This cannot use
+    `_api.check_getitem()`, because the norm keyword accepts arguments
+    other than strings.


I'm confused because this function is only called for isinstance(norm, str).

So this function exists because the norm keyword accepts Normalize objects in addition to strings.
This is fundamentally the same error you get if you give an invalid norm to a Colorizer object.

In main, the @norm.setter on colorizer.Colorizer reads:

@norm.setter def norm(self, norm): _api.check_isinstance((colors.Normalize, str, None), norm=norm) if norm is None: norm = colors.Normalize() elif isinstance(norm, str): try: scale_cls = scale._scale_mapping[norm] except KeyError: raise ValueError( "Invalid norm str name; the following values are " f"supported: {', '.join(scale._scale_mapping)}" ) from None norm = _auto_norm_from_scale(scale_cls)() ...

The _get_scale_cls_from_str() exists in this PR because this functionality is now needed by both colorizer.Colorizer.norm() and colors.MultiNorm.
Note this PR does not include changes to colorizer.Colorizer.norm() so that it makes use of _get_scale_cls_from_str(). These changes follow in the next PR: #29877 .

lib/matplotlib/colors.pyi

lib/matplotlib/colors.py

anntzer

Just some minor points, plus re-pinging @timhoffm in case he has an opinion re: n_input / input_dims naming?

trygvrad · 2025-05-04T09:14:39Z

Thank you for the feedback @anntzer !
Hopefully we can hear if @timhoffm has any thoughts on n_input / input_dims naming within the coming week.

timhoffm · 2025-05-05T11:41:04Z

See #29876 (comment)

trygvrad · 2025-05-07T17:57:37Z

Thank you @timhoffm
The PR should now be as we agreed (#29876 (comment)) :)

lib/matplotlib/colors.py

trygvrad · 2025-06-01T11:37:52Z

@QuLogic Thank you again and apologies for my tardiness (I was sick)
@timhoffm Do you think you could approve this PR now?

lib/matplotlib/colors.py

trygvrad · 2025-06-06T16:12:24Z

This is on hold until we sort out #30149 (Norm Protocol)
see #29876 (comment)

lib/matplotlib/colors.py

lib/matplotlib/tests/test_colors.py

lib/matplotlib/colors.py

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

timhoffm

Thanks @trygvrad! I think we're almost there. You can see the progress in moving from architecture and design questions to docs. :)

lib/matplotlib/colors.py

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

trygvrad · 2025-07-29T18:35:30Z

I changed vmin, vmax and clip to only accept iterables or None.

It dawned on me that it will be useful to allow None, with the behavior that it does not modify the vmin/vmax/clip on the constituent norms. This will be useful for use as a default, but also be useful for users that want to combine multiple norms into a MultiNorm without modifying the limits of the norms.

i.e.

n2 = mpl.colors.Normalize(vmax=2)
n3 = mpl.colors.Normalize(vmax=3)

mn0 = mpl.colors.MultiNorm((n2, n3), vmax=None) # does not modify vmax on the constituent norms
print(mn0.vmax, n2.vmax, n3.vmax) # prints (2.0, 3.0) 2.0 3.0
mn0 = mpl.colors.MultiNorm((n2, n3), vmax=[None, 4]) # vmax will now be None on n2 and 4 on n3
print(mn0.vmax, n2.vmax, n3.vmax) # prints (None, 4.0) None 4.0

timhoffm

Thanks @trygvrad for the patience and effort to go through all the design decisions together!

QuLogic · 2025-07-30T22:57:40Z

lib/matplotlib/colors.py

+        Parameters
+        ----------
+        norms : list of (str or `Normalize`)
+            The constituent norms. The list must have a minimum length of 2.


I understand 0, but is there a reason we can't gracefully degrade to 1D-Normalize behaviour if passed only 1?

I'm thinking of someone doing MultiNorm(norms) where norms is some dynamically deduced thing, and having to special-case 1 seems annoying.

@timhoffm Do you agree with @QuLogic that we should allow a single norm?
I'm fine with it either way

I don't see a practical use case for 1-element. This "dynamically deducing" seems a bit unlikely. But OTOH there's also no benefit in reqiring at least 2. So a list of length 1 is ok to accept.

I'm changing it to accept iterables of lenght 1 :)

lib/matplotlib/colors.py

lib/matplotlib/colors.pyi

lib/matplotlib/colors.py

QuLogic · 2025-07-30T23:18:15Z

lib/matplotlib/colors.py

+
+
+    @staticmethod
+    def _ensure_multicomponent_data(data, n_components):


Is this unused?

It is unused here, but will be needed later. A copy is stored in https://github.com/trygvrad/matplotlib/tree/MultiNorm-addendum, so I am removing it from this PR.

lib/matplotlib/colors.py

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

trygvrad · 2025-08-01T11:00:47Z

I changed vmin, vmax and clip to only accept iterables or None.

It dawned on me that it will be useful to allow None, with the behavior that it does not modify the vmin/vmax/clip on the constituent norms. This will be useful for use as a default, but also be useful for users that want to combine multiple norms into a MultiNorm without modifying the limits of the norms.

@timhoffm @anntzer I had made these changes, but actually committing them had slipped my mind. They are in now 😅

I'm on vacation now, so my schedule is a bit scrambled. @QuLogic I'll take a look at the rest of your comments soon :)

lib/matplotlib/colors.py

anntzer · 2025-08-01T12:25:32Z

@timhoffm @anntzer I had made these changes, but actually committing them had slipped my mind. They are in now 😅

I'm on vacation now, so my schedule is a bit scrambled. @QuLogic I'll take a look at the rest of your comments soon :)

Sorry I dropped the ball on this. I can try to have a look but not before the middle of the month or so.

lib/matplotlib/colors.py

lib/matplotlib/colors.pyi

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

trygvrad · 2025-08-14T10:31:43Z

@QuLogic all the comments should have been addressed now, do you have the time to take another pass at it?

QuLogic · 2025-08-15T01:02:02Z

@QuLogic all the comments should have been addressed now, do you have the time to take another pass at it?

There are still a couple of comments that are unresolved/have no reply, at least.

trygvrad · 2025-08-15T09:06:41Z

@QuLogic @story645 thank you for your comments and patience on this, I believe i have addressed all the comments now, but please correct me again if there are some I have overlooked. Otherwise I look forward to your future comments :)

QuLogic · 2025-08-16T00:19:34Z

lib/matplotlib/colors.py

+                return norm
+            else:
+                raise ValueError(
+                    "Each norm assgned to MultiNorm must be "


Suggested change

"Each norm assgned to MultiNorm must be "

"Each norm assigned to MultiNorm must be "

QuLogic · 2025-08-16T00:19:50Z

lib/matplotlib/tests/test_colors.py

+                       match="not a valid"):
+        mcolors.MultiNorm(["linear", "bad_norm_name"])
+    with pytest.raises(ValueError,
+                       match="Each norm assgned to MultiNorm"):


Suggested change

match="Each norm assgned to MultiNorm"):

match="Each norm assigned to MultiNorm"):

QuLogic · 2025-08-16T00:20:13Z

lib/matplotlib/colors.py

+            The input data, as an iterable or a structured numpy array.
+
+            - If iterable, must be of length `n_components`. Each element can be a
+              scalar or array-like and is normalized through the correspong norm.


Suggested change

scalar or array-like and is normalized through the correspong norm.

scalar or array-like and is normalized through the corresponding norm.

QuLogic · 2025-08-16T00:20:28Z

lib/matplotlib/colors.py

+            The input data, as an iterable or a structured numpy array.
+
+            - If iterable, must be of length `n_components`. Each element can be a
+              scalar or array-like and is mapped through the correspong norm.


Suggested change

scalar or array-like and is mapped through the correspong norm.

scalar or array-like and is mapped through the corresponding norm.

QuLogic · 2025-08-16T00:29:27Z

lib/matplotlib/colors.py

+        """
+        The number of normalized components.
+
+        This is number of elements of the parameter to ``__call__`` and of


Suggested change

This is number of elements of the parameter to ``__call__`` and of

This is the number of elements of the parameter to ``__call__`` and of

QuLogic · 2025-08-16T00:29:33Z

lib/matplotlib/colors.py

+        """
+        The number of distinct components supported (1).
+
+        This is number of elements of the parameter to ``__call__`` and of


Suggested change

This is number of elements of the parameter to ``__call__`` and of

This is the number of elements of the parameter to ``__call__`` and of

github-actions bot added topic: color/color & colormaps topic: transforms and scales labels Apr 6, 2025

This was referenced Apr 6, 2025

Preparations for multivariate plotting #29877

Open

Multivariate plotting in imshow, pcolor and pcolormesh #29221

Open

oscargus reviewed Apr 6, 2025

View reviewed changes

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

oscargus reviewed Apr 6, 2025

View reviewed changes

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

oscargus reviewed Apr 6, 2025

View reviewed changes

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

anntzer reviewed Apr 7, 2025

View reviewed changes

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

anntzer reviewed Apr 7, 2025

View reviewed changes

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

anntzer reviewed Apr 7, 2025

View reviewed changes

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

github-actions bot removed the topic: transforms and scales label Apr 10, 2025

QuLogic reviewed Apr 17, 2025

View reviewed changes

trygvrad force-pushed the multivariate-plot-prapare branch from 55b85e3 to f42d65b Compare April 17, 2025 15:18

anntzer reviewed May 1, 2025

View reviewed changes

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

anntzer reviewed May 1, 2025

View reviewed changes

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

anntzer reviewed May 1, 2025

View reviewed changes

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

anntzer reviewed May 1, 2025

View reviewed changes

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

anntzer reviewed May 1, 2025

View reviewed changes

QuLogic reviewed May 23, 2025

View reviewed changes

timhoffm reviewed Jun 2, 2025

View reviewed changes

QuLogic reviewed Jun 4, 2025

View reviewed changes

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

trygvrad force-pushed the multivariate-plot-prapare branch from 6b86d63 to 32247f5 Compare June 4, 2025 21:01

trygvrad mentioned this pull request Jun 6, 2025

Creation of the Norm Protocol #30149

Closed

story645 added the status: waiting for other PR label Jun 6, 2025

trygvrad mentioned this pull request Jun 15, 2025

Abstract base class for Normalize #30178

Merged

timhoffm reviewed Jul 21, 2025

View reviewed changes

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

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

updated types and errors for MultiNorm

270cb64

timhoffm reviewed Jul 24, 2025

View reviewed changes

Apply suggestions from code review

da1ac73

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

trygvrad force-pushed the multivariate-plot-prapare branch from 2707405 to da1ac73 Compare July 24, 2025 20:40

Updated return type of MultiNorm

347df5b

timhoffm reviewed Jul 27, 2025

View reviewed changes

trygvrad and others added 2 commits July 29, 2025 19:46

Apply suggestions from code review

22e9093

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

updated docstrings in MultiNorm

81372c6

trygvrad force-pushed the multivariate-plot-prapare branch from 4f72962 to 81372c6 Compare July 29, 2025 17:54

timhoffm approved these changes Jul 30, 2025

View reviewed changes

QuLogic reviewed Jul 30, 2025

View reviewed changes

trygvrad and others added 3 commits August 1, 2025 12:54

Apply suggestions from code review

f1cdc10

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

changed so that vmin/vmax must be iterable

e6d59ed

Update colors.pyi

2d9d00c

timhoffm reviewed Aug 1, 2025

View reviewed changes

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

trygvrad added 2 commits August 5, 2025 17:00

change to handling of bad norm names in MultiNorm

68c5527

Update colors.py

aa99db3

QuLogic reviewed Aug 7, 2025

View reviewed changes

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

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

lib/matplotlib/colors.pyi Outdated Show resolved Hide resolved

Apply suggestions from code review

f61c06b

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

trygvrad force-pushed the multivariate-plot-prapare branch from ff2eb20 to f61c06b Compare August 7, 2025 21:25

change minimum length of multiNorm to 1.

c0a0d6d

QuLogic reviewed Aug 16, 2025

View reviewed changes



		@staticmethod
		def _ensure_multicomponent_data(data, n_components):

	"Each norm assgned to MultiNorm must be "
	"Each norm assigned to MultiNorm must be "

	match="Each norm assgned to MultiNorm"):
	match="Each norm assigned to MultiNorm"):

	scalar or array-like and is normalized through the correspong norm.
	scalar or array-like and is normalized through the corresponding norm.

	scalar or array-like and is mapped through the correspong norm.
	scalar or array-like and is mapped through the corresponding norm.

	This is number of elements of the parameter to ``__call__`` and of
	This is the number of elements of the parameter to ``__call__`` and of

Uh oh!

MultiNorm class #29876

Are you sure you want to change the base?

MultiNorm class #29876

Conversation

trygvrad commented Apr 6, 2025

PR summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

anntzer left a comment

Choose a reason for hiding this comment

Uh oh!

trygvrad commented May 4, 2025

Uh oh!

timhoffm commented May 5, 2025

Uh oh!

trygvrad commented May 7, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

trygvrad commented Jun 1, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

trygvrad commented Jun 6, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

timhoffm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

trygvrad Aug 1, 2025 •

edited

Loading