Added an example in the user guide on using operations on 2d elements. #2316
Conversation
|
Thank you very much! These kind of doc contributions are always very welcome as users are best able to point out and fix the pain points. |
| "- The image data returned by ``dimension_values()`` must be flipped along the first axis due to conflicting conventions.\n", | ||
| "- ``Image`` and related classes come with convenient methods to convert between matrix indices and data coordinates and vice versa: ``matrix2sheet()`` and ``sheet2matrix()``. This is useful when searching for features such as peaks.\n", | ||
| "\n", | ||
| "A very powerful aspect of operations is the fact that they understand Holoviews data structures. This means it is very straight-forward to apply an operation to every element in a container. As an example, well apply an additional high-pass filter to our HoloMap:" |
There was a problem hiding this comment.
Fixed it (but now I see I made a typo in the commit message...)
|
Does anyone see why the checks are not passing now? Everything was successful with the first commit. |
|
We struggle with transient test failures because matplotlib output sometimes varies. I'll restart the build. |
| "\n", | ||
| "There are some peculiarities when applying operations to two-dimensional elements:\n", | ||
| "\n", | ||
| "- Understanding the ``dimension_values()`` method: In principle, one could use ``element.data`` to access the element's data, however, using ``dimension_values()`` means one does not have to worry about different data formats for different elements. The first parameter specifies the dimension to be returned. Values 0 and 1 refer to the horizontal and vertical axis, respectively. For ``Image`` and ``Raster`` elements, 2 refers to the magnitude, while for ``RGB``, 2, 3 and 4 refer to the red, green and blue channels. Setting ``expanded=False`` yields only the axis, while the default setting ``expanded=True`` returns a value for every pixel. Specifying ``flat=False`` means that the data's matrix shape will be preserved, which is what we need for this kind of filter.\n", |
There was a problem hiding this comment.
Some things that should maybe be clarified:
-
While it is true that the data format depends on the element type, all elements also support a variety of different formats, which are defined by the
datatype. In the background a number of Interface classes allow elements to access and manipulate the data in different formats, be that numpy arrays, dask arrays, xarrays or whatever else. We need to add a user guide about interfaces eventually so maybe just say something like: "In principle, one could useelement.datato access the element's data, however, since HoloViews can wrap a wide range of data formatsdimension_values()provides an API that lets you access the data without having to worry about the type of the data. -
While it is true that
dimension_valuesallows using integers to reference which values you want, it is primarily about the dimensions. On a 2D Element 0 and 1 correspond to the two key dimensions, while subsequent values refer to the value dimensions, basically it's defined aselement.dimensions()[index]. So maybe say something like:
On a 2D element like an Image or Raster the first two dimensions reference the key dimensions, so passing an index of 0 or 1 will return the x- and y-axis values respectively. Any subsequent dimensions will be value dimensions, e.g. on an Image index value 2 will refer to the intensity values and on an RGB index values 2, 3, and 4 will return the Red, Green and Blue intensities instead.
| " y_coords = element.dimension_values(1, expanded=False)\n", | ||
| " \n", | ||
| " # setting flat=False will preserve the matrix shape\n", | ||
| " data = element.dimension_values(2, flat=False)[::-1]\n", |
There was a problem hiding this comment.
Change this to:
data = element.dimension_values(2, flat=False)
And then apply my suggestion below.
| " \n", | ||
| " # make an exact copy of all setting and axes etc., just with different data:\n", | ||
| " element = element.clone(data=new_data)\n", | ||
| " element = element.relabel(element.label + \" ({} filtered)\".format(self.p.type_))\n", |
There was a problem hiding this comment.
Change these two lines to:
label = element.label + " ({} filtered)".format(self.p.type_)
element = element.clone((xs, ys, new_data), label=label)
|
I've made some comments, but otherwise looks great. Really appreciate the contribution. |
|
@philippjfr OK, I applied your suggestions, and I think I learned some stuff in the process 😆 |
|
Looks great, thanks for making those changes so quickly! |
|
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. |
This is in response to issue #1108. Even though the documentation has improved massively since I first started using Holoviews, I was having some trouble applying operations to Images recently, so I thought it might be nice to have an example of this in the documentation. I also think it's neat to show the ability to apply an operation to a container in this section, which is an amazing and convenient feature, imo. Just let me know what you think.