Regrid doc elaboration for image data

[joelostblom]

Hi @jbednar I am following up on your SO comment to add to the documentation what I think could be helpful to understand datashading operations on image data with the clim option.

I added a short paragraph which reflects my current understanding of the topic (which is likely incomplete) and a short example to show the difference between automatic color range rescaling and how to fix the range. Since the rescaling will not show up in the static documentation I also made this gif, but not sure what the policy is for including images vs the notebook output.

One thing I still find somewhat confusing is that the datashade() function doesn't seem to be able to pass .opts(clim=()) onto the bokeh backend (like regrid does). Instead I can pass clims=() directly to the datashade() function, but when I try to do this I get an error:

WARNING:param.dynamic_operation: Callable raised "ValueError('span is not (yet) valid to use with eq_hist')".
Invoked as dynamic_operation(height=400, scale=1.0, width=400, x_range=None, y_range=None)

[philippjfr]

Thanks a lot for this clarification.

One thing I still find somewhat confusing is that the datashade() function doesn't seem to be able to pass .opts(clim=()) onto the bokeh backend (like regrid does).

This is because datashade is actually two operations in one, rasterize (which is equivalent but more general than regrid) which does the aggregation and returns a 2D array wrapped in an Image element and shade which does the colormapping server-side and returns an RGB element. Once the image is colormapped to an RGB you cannot provide clims to it and re-colormap it.

I'd suggest you use rasterize instead of regrid in the your explanation since it is the more general operation and applies to all kinds of elements unlike regrid which applies only to Image elements.

[joelostblom]

@philippjfr Thanks for the info!

This is because datashade is actually two operations in one, rasterize (which is equivalent but more general than regrid) which does the aggregation and returns a 2D array wrapped in an Image element and shade which does the colormapping server-side and returns an RGB element. Once the image is colormapped to an RGB you cannot provide clims to it and re-colormap it.

Ah, that makes sense. So right now it is not possible to control the colormap range in a plot created from datashade()?

I'd suggest you use rasterize instead of regrid in the your explanation since it is the more general operation and applies to all kinds of elements unlike regrid which applies only to Image elements.

Hmm, doesn't that mean that my explanation is incorrect then? I wrote: "When working with already gridded data, such as images, it is not always necessary to perform the rasterization/aggregation step", but since you suggest to use rasterize instead of regrid it sounds like aggregation will be performed also on images. Rather, it is shade that does not need to be done on images, which is just the RGB mapping? How would you repharse that? I can't explain it by saying that image data is already RGB since I can also show images that are not RGB tuples without calling shade.

Is there any performance penalty associated with using rasterize over regrid as it is more general (it didn't seem to be noticeable when I tested with a small image)?

[philippjfr]

Ah, that makes sense. So right now it is not possible to control the colormap range in a plot created from datashade()?

It is, I think you should be able to pass clims directly to the datashade/shade operations (unfortunate the name doesn't match tbh).

Hmm, doesn't that mean that my explanation is incorrect then?

Yes, sorry should have commented, I'll try to think of some clearer wording. This is definitely something quite a few people have been confused about so we should definitely try to get it across as clearly as possible.

Is there any performance penalty associated with using rasterize over regrid as it is more general (it didn't seem to be noticeable when I tested with a small image)?

Possibly but very minor.

[jbednar]

Looks good, thanks!. I made edits to avoid the use of regrid, which as @philippjfr suggests isn't normally called by users, as regrid is precisely the same as rasterize when used for images, and there's no need for people to learn the specialized name since rasterize does it all.

when I try to do this I get an error:

That error is accurate; supporting span (the datashader equivalent of clim is indeed not yet supported for eq_hist; it would take some special work to figure out how to map those limits onto the variably spaced color scale created by eq_hist). Doable, but not yet done by anyone.

In the meantime, you can avoid the issue either by using rasterize rather than datashade, or by changing the datashade/shade normalization to something other than eq_hist (log, linear, etc.).

[jbednar]

The GIF is useful. For now, maybe just embed it like any other image, directly in the Markdown? We're still working out some general way to show output as GIFs while not confusing notebook users with double output.

[philippjfr]

For now, maybe just embed it like any other image, directly in the Markdown? We're still working out some general way to show output as GIFs while not confusing notebook users with double output.

We generally upload gifs to assets.holoviews.org and link to them, I would not suggest embedding a base64 encoded gif in markdown. If you think we should do that I'm happy to upload the gif and will paste the link to it here.

[jbednar]

Rather, it is shade that does not need to be done on images,

shade doesn't need to be done on anything; it's always optional, image or not. Shading does always need to be done on anything non-RGB, but if you don't use shade, Bokeh will do the shading (i.e., colormapping). So shading is independent of anything discussed here.

[joelostblom]

Great, thank you both for the comments! I made updates accordingly. I think the only thing missing now is the gif.

Thanks for the explanation regarding clims with datashade. I think that could be clarified in the error message, for example changing from:

Callable raised "ValueError('span is not (yet) valid to use with eq_hist')"

to

Callable raised "ValueError('span is not (yet) valid to use with eq_hist, use lin or log instead')"

or even automatically changing to lin or log and print a warning which the user can silence by explicitly setting the parameter.

[philippjfr]

Here's a permanent link to the gif: http://assets.holoviews.org/gifs/guides/user_guide/Large_Data/rasterize_color_range.gif

[joelostblom]

@philippjfr Thanks, should I suppress the notebook output somehow so that there is not a double plot showing up?

[philippjfr]

@philippjfr Thanks, should I suppress the notebook output somehow so that there is not a double plot showing up?

I'll leave that up to you but that seems like a reasonable solution until we figure out a more general one (as @jbednar mentioned this is a recurring problem in a lot of our docs/notebooks).

[joelostblom]

I included the gif and made one last change to include the earlier comment from @jbednar which I found helpful to understand the differences in shading/colormapping between rasterize and datashade.

[philippjfr]

Looks great, thanks for contributing!

[joelostblom]

Thanks for helping me contribute!

[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.