Indicate color clipping and control clipping colors

[philippjfr]

As the title says, adds a plot option to extend the colorbar in a particular. Here's an example:

%%opts Image [colorbar=True]
hv.Layout([hv.Image(np.random.rand(10,10))(plot=dict(cbar_extend=opt))
           for opt in ['min', 'max', 'both']])

Can also consider automatically enabling this if your data falls outside the specified range but that's another discussion.

[jbednar]

I don't get it -- what does it mean to extend the colorbar? It doesn't seem extended, it just now has a pointy end. Do you mean, make the colorbar visually indicate that it extends beyond the area shown, without actually changing the colorbar or the colormapping? If so that's not what the option name or the name of this issue suggests, and seems very confusing.

[philippjfr]

True, the name isn't great, it's what matplotlib uses.

[philippjfr]

This would also be more useful with an option to supply different colors for values that are above and below the range (and for NaN values). We can brainstorm about a nice way to specify that.

[jlstevens]

pointy_cbar sounds more descriptive to me! ;-p

[jbednar]

I'm not sure it makes sense to provide direct control over this option, in HoloViews. Seems like HoloViews should just automatically turn it on if the user has selected a colormap that ends up clipping at a particular end of the colorbar, so that the visual representation is a reliable indicator of something meaningful. As it is, there's no relation between whether the user has explicitly enabled a pointy colorbar and anything about the actual plot, so indeed Jean-Luc's suggestion of calling it pointy_cbar is accurate!

[jlstevens]

Using this to indicate clipping when clipping occurs does make a lot more sense. We would still need a parameter to turn this behaviour on and off though...

[jlstevens]

Also I assume one problem this this suggestion is we might not know if clipping has occurred without inspecting the data range first? Sounds tricky...you might have to compare the data min/max with the limits to know if it should be pointy or not.

[philippjfr]

Sounds tricky...you might have to compare the data min/max with the limits to know if it should be pointy or not.

It might be fairly straightforward and the overhead wouldn't be huge, so might be worth doing. Coupled with a way to specify special colors for min, max and NaN values that would be a nice addition.

[jlstevens]

It might be fairly straightforward and the overhead wouldn't be huge..

Sure. As long as there is a way to turn it off and keep the current behaviour in case it ever becomes a problem. I agree it would be a nice feature and I'm wondering if there might be a way to specify the NaN values and clipping colors at the same time...

[jbednar]

That makes sense: the user can optionally enable having pointy cbars indicate such clipping. That way, whenever there is such a pointy cbar, it does accurately reflect something about the current plot, rather than just being some meaningless style option. Yet those who don't ever want pointy cbars can turn them off.

[philippjfr]

So since I actually needed this for some plots of mine I've gone ahead and implemented it. If you've got a better suggestion for the clipping_colors parameter please suggest it and tell me and I also still need a name for the option that turns the clipping indicators on and off in general.

[jlstevens]

Apparently ('w', 1) is used because the colorbar code in matplotlib takes the color and a separate alpha. I would much prefer to pretend matplotlib is consistent and support standard matplotlib colors, including the RGBA tuples.

[philippjfr]

Sure, shouldn't be hard.

[jlstevens]

I understand what I expect to happen to NaN values but an example of how to set the min and max colors would be nice (in the docstring).

[philippjfr]

Agreed.

[jlstevens]

Philipp tells me you would specify a max clipping like this:

{'min': 'r', 'Nan': 'w'}

Would setting these colors make the colorbar pointy as appropriate (if the data is clipped?). If so wouldn't an empty dictionary correspond to the current behaviour without pointy colorbars?

[philippjfr]

If so wouldn't an empty dictionary correspond to the current behaviour without pointy colorbars?

No, not specifying a special color just sets the min and max color in the cmap as the clipping color, as in the example above.

[jlstevens]

So why not have something like:

cbar_extension = {'min': 'default', 'max':'default'}

To indicate pointy colorbars with the min/max of the colormap where you can then specify your own custom colors instead of 'default'?

[philippjfr]

Sounds good, if we can come up with a better name for the parameter.

[jbednar]

Maybe cbar_clip?

[jlstevens]

Given that colorbar is a parameter name, colorbar_clip would appear next to it. For that reason I might like the longer name.

[jbednar]

Sure, if "clip" is accurate as a description about what it does (which I've somewhat lost track of by this point. :-)

[philippjfr]

We already have cbar_width and cbar_padding so it should at least be consistent.

Edit: Of course we could decide to rename those as well.

[jlstevens]

We already have cbar_width and cbar_padding so it should at least be consistent.

In that case we should alias colorbar with cbar to enable/disable color bars.

[philippjfr]

I'd suggest just calling it clipping_colors or color_clipping. Adding the pointy bit to the color bar is just a secondary side effect. Even without the colorbar enabled this will control the out-of-range colors so it's not really a colorbar option.

Edit: I guess why I was hesitant about the {'max': 'default'} suggestion is for the same reason, this parameter doesn't necessarily have anything to do with the colorbar, so enabling it that way feels a bit weird.

[jlstevens]

clipping_colors seems fine. So could you still use it to disable pointy colorbars?

[jbednar]

See #689 for proposed UI.

[philippjfr]

Ready to merge once clipping color support is fixed in bokeh: bokeh/bokeh#5323

[jlstevens]

RGBA tuples are fine though are any other color specifications allowed? E.g hex strings?

[philippjfr]

Yes, docstring should be updated to reflect that.

[jlstevens]

Looks good. Happy to merge when the tests pass.

[jlstevens]

Tests have all passed. Merging.

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.