Merge Colorbar and ColorbarBase. #20354

anntzer · 2021-06-03T14:14:20Z

ColorbarBase differs from Colorbar in that it is not associated with a
ScalarMappable (but constructed from explicit cmap/norm), but we already
document in Figure.colorbar that the preferred way to draw colorbars not
associated with an existing artist is to create an empty ScalarMappable
to provide norm and cmap.

Hence, likewise merge Colorbar and ColorbarBase (creating the
ScalarMappable on-the-fly if no mappable is passed to the constructor),
which should make the APIs clearer. (Note that we are already
discouraging users to directly call either class' constructors,
anyways). We could deprecate the backcompat APIs (i.e., the
ColorbarBase alias, the cmap and norm kwargs, and the different
semantics of add_lines), but that can be done later; this PR should be
entirely backcompatible.

(See also #17189.)

PR Summary

PR Checklist

Has pytest style unit tests (and pytest passes).
Is Flake 8 compliant (run flake8 on changed files to check).
New features are documented, with examples if plot related.
Documentation is sphinx and numpydoc compliant (the docs should build without error).
Conforms to Matplotlib style conventions (install flake8-docstrings and run flake8 --docstring-convention=all).
New features have an entry in doc/users/next_whats_new/ (follow instructions in README.rst there).
API changes documented in doc/api/next_api_changes/ (follow instructions in README.rst there).

jklymak · 2021-06-03T14:30:08Z

I'll put as draft until at least #20327 gets in.

anntzer · 2021-06-03T14:47:38Z

Yup, no hurries.

story645 · 2021-06-10T20:09:54Z

lib/matplotlib/colorbar.py

+
+            norm = colors.Normalize(clip=False)
+
+        To show the colors versus index instead of on a 0-1 scale, use::


not sure what versus index means here

that's copypasted from the previous docstring, so let's not change that here.

story645 · 2021-06-10T20:17:57Z

lib/matplotlib/colorbar.py

-        norm=colors.NoNorm()
+    In order to draw a colorbar not associated with other elements in the
+    figure, e.g. when showing a colormap by itself, one can create an empty
+    `.ScalarMappable`, or directly pass *cmap* and *norm* instead of *mappable*


what happens if for reasons you set everything to none?

You get the usual defaults (cmap from rcParams["image.cmap"], linear norm).

story645 · 2021-06-10T20:19:32Z

lib/matplotlib/colorbar.py

@@ -489,6 +503,37 @@ def __init__(self, ax, *, cmap=None,
            self.formatter = format  # Assume it is a Formatter or None
        self.draw_all()

+        if isinstance(mappable, contour.ContourSet) and not mappable.filled:
+            self.add_lines(mappable)  # FIXME


what needs to be fixed here?

oopsie, nothing anymore, that was from before I implemented the overloading in add_lines.

jklymak · 2021-06-10T23:19:41Z

lib/matplotlib/colorbar.py

+                lambda self, CS, erase=True: (self, CS, erase))(
+                    self, *args, **kwargs)
+        except TypeError:
+            self, levels, colors, linewidths, erase = (


This is new, and probably needs a test. I don't actually understand what this lambda does and I find it quite unreadable. Same with the lambda above. You have used this lambda trick elsewhere, is it possible to encapsulate it as an _api function that has some semantics?

Also, does this need an API change note? I am not clear on what API is even being changed here, but this seems somewhat unrelated to merging these two classes?

Actually this is completely related to the merging of the two classes (and doesn't need an API change: it's here strictly for backcompat).
Previously, ColorbarBase.add_lines() had signature add_lines(self, levels, colors, linewidths, erase=True), whereas Colorbar.add_lines() had signature add_lines(self, CS, erase=True). Therefore, if we want to merge the two classes while maintaining backcompat, we need to support both calling conventions. In order to do so, we make add_lines() take *args, **kwargs, and then parse them using the helper lambdas: if self, *args, **kwargs can be passed to lambda self, levels, colors, linewidths, erase=True: <thing>, then the user called it using the ColorbarBase signature; otherwise, the user called it using the Colorbar signature. The helper lambdas then perform two tasks: 1) if the call has a valid parameter list, then assign the right values to levels, colors, etc., and 2), if the call has an invalid parameter list, generate a standard error message, using Python's standard machinery ("expected 4 args but got 2" or "got an unexpected arg 'foo'" or whatnot).
Perhaps that can go into an _api helper, but let's do that another time? (There's only one other use of the pattern in the library now, AFAICT, in QuadMesh.)

Also note, both of these forms are inconsistent with Axes.add_lines :( So there are at least 3 different signatures floating around

I'm not really sure add_lines should be public, but deprecating it is not the point of this PR.

OK, can you at least add a comment explaining what is going on? Again, this trick is very unintuitive to me, and if we are going to have very hard-to-follow code in the codebase, it at least needs comments explaining what the magical wand does.

Actually, perhaps #20420 can go in first and I'll rebase this on top of it...

jklymak · 2021-06-10T23:19:52Z

lib/matplotlib/colorbar.py

+
+        try:
+            ax = self.mappable.axes
+        except AttributeError:


I guess you aren't testing removing an axes with no mappable?

I guess you meant a mappable with no axes? (there's always a mappable, once this PR goes in) Sure, that seems easy enough to add.

greglucas

I think this is a good simplification. I also agree with your final paragraph that some of the signatures should be deprecated in follow-up PRs.

I'm not sure what you typically do for old whats_new broken references.

/home/circleci/project/doc/users/prev_whats_new/whats_new_3.0.rst:63: WARNING: py:obj reference target not found: colorbar.ColorbarBase.minorticks_on
/home/circleci/project/doc/users/prev_whats_new/whats_new_3.0.rst:63: WARNING: py:obj reference target not found: colorbar.ColorbarBase.minorticks_off
/home/circleci/project/doc/users/prev_whats_new/whats_new_3.3.0.rst:287: WARNING: py:obj reference target not found: ColorbarBase.set_label

greglucas · 2021-06-11T12:45:30Z

lib/matplotlib/colorbar.py

+                lambda self, CS, erase=True: (self, CS, erase))(
+                    self, *args, **kwargs)
+        except TypeError:
+            self, levels, colors, linewidths, erase = (


Also note, both of these forms are inconsistent with Axes.add_lines :( So there are at least 3 different signatures floating around

anntzer · 2021-06-11T15:44:50Z

The refs should be fixed now.

anntzer · 2021-06-18T08:17:18Z

Modified to use #20420.

jklymak

This seems great to me. I didn't really understand why there was a subclass, and getting rid of it makes life easier...

I guess discouraging ColorbarBase should happen at some point, and probably deserves an API-change note (i.e. ColorbarBase is now just an alias for Colorbar, and ColorbarBase will be removed in future Matplotlib)

greglucas · 2021-06-18T14:27:29Z

lib/matplotlib/colorbar.py

+            colors = [c[0] for c in CS.tcolors]
+            linewidths = [t[0] for t in CS.tlinewidths]
+        else:
+            self, levels, colors, linewidths, erase = params.values()


I'm a bit confused that this path isn't covered by the tests... Above you say the other one is the deprecated signature, but it appears to be the only one used, so should this path be the deprecated signature instead?

Yeah, good point - if we are gong to have the funky signature matching they should probably be tested....

Good points; I went back to the old approach (of having one of the signatures forward to the other), so coverage should be fine now; and I tweaked the wording to not have to decide which of the signatures (if any) we really prefer. (I also removed the __signature__ patching.) We can always decide on the preferred signature in a followup PR...

ColorbarBase differs from Colorbar in that it is not associated with a ScalarMappable (but constructed from explicit cmap/norm), but we already document in Figure.colorbar that the preferred way to draw colorbars not associated with an existing artist is to create an empty ScalarMappable to provide `norm` and `cmap`. Hence, likewise merge Colorbar and ColorbarBase (creating the ScalarMappable on-the-fly if no mappable is passed to the constructor), which should make the APIs clearer. (Note that we are already discouraging users to directly call either class' constructors, anyways). We could deprecate the backcompat APIs (i.e., the `ColorbarBase` alias, the `cmap` and `norm` kwargs, and the different semantics of `add_lines`), but that can be done later; this PR should be entirely backcompatible.

greglucas

I like this consolidation as well.

anntzer added the topic: color/colorbar label Jun 3, 2021

jklymak marked this pull request as draft June 3, 2021 14:30

jklymak added the status: waiting for other PR label Jun 3, 2021

anntzer marked this pull request as ready for review June 10, 2021 19:43

anntzer force-pushed the cbb branch from 6e76ae6 to 1afd7cf Compare June 10, 2021 19:43

anntzer removed the status: waiting for other PR label Jun 10, 2021

jklymak assigned jklymak and unassigned jklymak Jun 10, 2021

jklymak self-requested a review June 10, 2021 19:54

story645 reviewed Jun 10, 2021

View reviewed changes

anntzer force-pushed the cbb branch from 1afd7cf to 7ca1f75 Compare June 10, 2021 22:21

jklymak reviewed Jun 10, 2021

View reviewed changes

anntzer force-pushed the cbb branch from 7ca1f75 to 47056b1 Compare June 11, 2021 07:55

greglucas reviewed Jun 11, 2021

View reviewed changes

anntzer force-pushed the cbb branch from 47056b1 to 0002ba8 Compare June 11, 2021 15:44

anntzer mentioned this pull request Jun 12, 2021

Add a select_overload helper for signature-overloaded functions. #20420

Merged

7 tasks

anntzer force-pushed the cbb branch from 0002ba8 to 6e29934 Compare June 18, 2021 08:17

anntzer force-pushed the cbb branch from 6e29934 to 5f1165f Compare June 18, 2021 10:38

jklymak approved these changes Jun 18, 2021

View reviewed changes

greglucas reviewed Jun 18, 2021

View reviewed changes

anntzer force-pushed the cbb branch from 5f1165f to 91903b5 Compare June 18, 2021 17:36

anntzer force-pushed the cbb branch from 91903b5 to b84775c Compare June 18, 2021 17:37

greglucas approved these changes Jun 18, 2021

View reviewed changes

greglucas merged commit b71ee62 into matplotlib:master Jun 18, 2021

QuLogic added this to the v3.5.0 milestone Jun 19, 2021

anntzer deleted the cbb branch June 19, 2021 09:06


		norm = colors.Normalize(clip=False)

		To show the colors versus index instead of on a 0-1 scale, use::

Uh oh!

Merge Colorbar and ColorbarBase. #20354

Merge Colorbar and ColorbarBase. #20354

Uh oh!

Conversation

anntzer commented Jun 3, 2021

PR Summary

PR Checklist

Uh oh!

jklymak commented Jun 3, 2021

Uh oh!

anntzer commented Jun 3, 2021

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!

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!

greglucas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anntzer commented Jun 11, 2021

Uh oh!

anntzer commented Jun 18, 2021

Uh oh!

jklymak left a comment

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!

greglucas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!