New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added an example in the user guide on using operations on 2d elements. #2316

Merged
merged 3 commits into from Feb 9, 2018

Conversation

Projects
None yet
4 participants
@drs251
Contributor

drs251 commented Feb 7, 2018

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.

@jlstevens

This comment has been minimized.

Member

jlstevens commented Feb 7, 2018

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:"

This comment has been minimized.

@jbednar

jbednar Feb 7, 2018

Member

we'll

(or "let's")

This comment has been minimized.

@drs251

drs251 Feb 7, 2018

Contributor

Fixed it (but now I see I made a typo in the commit message...)

@drs251

This comment has been minimized.

Contributor

drs251 commented Feb 7, 2018

Does anyone see why the checks are not passing now? Everything was successful with the first commit.

@philippjfr

This comment has been minimized.

Member

philippjfr commented Feb 7, 2018

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",

This comment has been minimized.

@philippjfr

philippjfr Feb 9, 2018

Member

Some things that should maybe be clarified:

  1. 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 use element.data to access the element's data, however, since HoloViews can wrap a wide range of data formats dimension_values() provides an API that lets you access the data without having to worry about the type of the data.

  2. While it is true that dimension_values allows 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 as element.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",

This comment has been minimized.

@philippjfr

philippjfr Feb 9, 2018

Member

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",

This comment has been minimized.

@philippjfr

philippjfr Feb 9, 2018

Member

Change these two lines to:

label = element.label + " ({} filtered)".format(self.p.type_)
element = element.clone((xs, ys, new_data), label=label)
@philippjfr

This comment has been minimized.

Member

philippjfr commented Feb 9, 2018

I've made some comments, but otherwise looks great. Really appreciate the contribution.

@drs251

This comment has been minimized.

Contributor

drs251 commented Feb 9, 2018

@philippjfr OK, I applied your suggestions, and I think I learned some stuff in the process 😆

@philippjfr

This comment has been minimized.

Member

philippjfr commented Feb 9, 2018

Looks great, thanks for making those changes so quickly!

@philippjfr philippjfr added the docs label Feb 9, 2018

@philippjfr philippjfr merged commit 05d2ca4 into ioam:master Feb 9, 2018

3 checks passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
coverage/coveralls Coverage decreased (-0.01%) to 81.32%
Details
s3-reference-data-cache Test data is cached.
Details

@drs251 drs251 deleted the drs251:2d_operation_docs branch Feb 9, 2018

@philippjfr philippjfr added this to the 1.9.3 milestone Feb 11, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment