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

Polishing and improving the tutorials added in 1.7 #1384

Merged
merged 25 commits into from May 8, 2017

Conversation

Projects
None yet
2 participants
@jlstevens
Member

jlstevens commented Apr 28, 2017

This PR aims to improve our new tutorials before 1.7.1 is released, hopefully getting the improved versions of the tutorials live before then. The tutorials to improve are: DynamicMap, Streams and Linked_Streams and they are expected to be read in that order.

I think any of us can use this PR to make the improvements we feel are necessary. Obviously anything that might be controversial should be discussed first!

My first commit improves the listing of available linked stream classes.

@jlstevens jlstevens added the docs label Apr 28, 2017

"\n",
"<center><div class=\"alert alert-info\" role=\"alert\">To use and visualize <b>DynamicMap</b> or <b>Stream</b> objects you need to be running a live Jupyter server.<br>This tutorial assumes that it will be run in a live notebook environment.<br>\n",
"When viewed statically, DynamicMaps will only show the first available Element,<br></div></center>\n",
"\n",
"## Available Linked Streams\n",
"\n",
"There a huge number of ways one might want to interact with a plot. The HoloViews streams module aims to offer many of the most common interactions you might want to specify while making it easy to extend it with custom linked Streams. \n",
"There are a huge number of ways one might want to interact with a plot. The HoloViews streams module aims to expose many of the most common interactions you might want want to engage in, while also supporting extensibility via ustom linked Streams. \n",

This comment has been minimized.

@philippjfr

philippjfr Apr 28, 2017

Member

"engage in" seems awkward, maybe "utilize" or "employ"

Also "ustom linked Streams"

This comment has been minimized.

@jlstevens

jlstevens Apr 28, 2017

Member

'employ' sounds good and I'll fix the typo now.

@jlstevens

This comment has been minimized.

Member

jlstevens commented May 1, 2017

I've updated the notebook format version because the diffs were getting too miserable - all because of a minor version bump in the format.

@jlstevens

This comment has been minimized.

Member

jlstevens commented May 1, 2017

I am skipping over the 'Unlinking streams' section and going through the rest of the tutorial. I think that section needs a better example to illustrate why you might want to unlink.

@jlstevens

This comment has been minimized.

Member

jlstevens commented May 1, 2017

However if it is a DynamicMap we have to make a copy with the Dynamic utility and declare link_inputs=False.

@philippjfr Maybe clone should support a link_inputs argument everywhere such that it does nothing for normal elements but works appropriately for DynamicMap?

@jlstevens

This comment has been minimized.

Member

jlstevens commented May 1, 2017

I've updated the last section:

  • Transient events are not covered in the basic Streams tutorial. I think introducing them in Linked Streams makes sense.
  • I updated the code in the example, using if None not in [x,y]: instead of if x and y:. This is both more explicit (and makes more sense with the text) and more correct as x=0 and y=0 are perfectly valid (but falsey) stream parameter values.
@jlstevens

This comment has been minimized.

Member

jlstevens commented May 1, 2017

I'm done making edits to the linked streams tutorial for now. There are two things I would like to see:

  1. A better example for unlinking streams.
  2. A better conclusion, maybe ending with a nice example.
  3. Possibly an example showing selection?

I'm happy to review the tutorial and have another pass once these things are added.

@jlstevens

This comment has been minimized.

Member

jlstevens commented May 5, 2017

I've now replaced the crosshairs with a better example of dimensioned streams:

image

There are two things to mention though:

  • The bit about casting to HoloMap needs dimension defaults to be added (to be more interesting, otherwise the area has no width)
  • This could then motivate the linked streams tutorial, if @philippjfr would like to include the linked version:
xs = np.linspace(-3, 3, 400)

def function(xs, time):
    "Some time varying function"
    return np.exp(np.sin(xs+np.pi/time))

def integral(limit, time):
    limit = -3 if limit is None else limit
    curve = hv.Curve((xs, function(xs, time)))[limit:]
    area = hv.Area((xs, function(xs, time)))[:limit]
    summed = area.dimension_values('y').sum() * 0.015  # Numeric approximation
    return (area * curve * hv.VLine(limit) * hv.Text(limit + 0.8, 2.0, '%.2f' % summed))

hv.DynamicMap(integral, kdims=['time'], streams=[Stream.define('Time', time=1.0)(), 
                                                 streams.PointerX().rename(x='limit')])

@philippjfr It might be nice to make such a link between the tutorials. Do you have a use for this example in the linked streams tutorial?

@jlstevens

This comment has been minimized.

Member

jlstevens commented May 7, 2017

I will rebase now so I can make edits to the new operation tutorial if necessary.

@jlstevens

This comment has been minimized.

Member

jlstevens commented May 8, 2017

From commit 290fcd5 onwards I will be assuming that ElementOperation will be renamed to Operation i.e #1421 will be merged.

@jlstevens

This comment has been minimized.

Member

jlstevens commented May 8, 2017

In addition I am assuming issue #1386 will be addressed having removed all mention of key argument in _process.

@jlstevens

This comment has been minimized.

Member

jlstevens commented May 8, 2017

I'm done making edits on the Operations tutorial for now. I am very happy with the examples it uses and I think the main issue now is merging the required PRs I mention above.

@jlstevens

This comment has been minimized.

Member

jlstevens commented May 8, 2017

In my last commit, I add a new section about what to do when you don't have an operation that maps over elements: I recommend always using param.ParameterizedFunction and documented appropriately.

@jlstevens

This comment has been minimized.

Member

jlstevens commented May 8, 2017

Note that I added np.clip(limit,-3,3) to the new linked streams 'integral' example. This behaves better but may be unnecessary if we decide to limit linked pointer position values to the axis bounds - which I think we should.

@philippjfr @jbednar @ceball This PR is ready now, all feedback on these three new tutorials (Streams, Linked Streams, Operations) is welcome!

@jlstevens

This comment has been minimized.

Member

jlstevens commented May 8, 2017

As one final note, adding the following code (thanks @philippjfr !) is the same as applying np.clip:

clipjs = "if (x_range.type.endsWith('Range1d')) { if (cb_obj.x < x_range.start) { data['x'] = x_range.start } else if (cb_obj.x > x_range.end) { data['x'] = x_range.end }}"
hv.plotting.bokeh.callbacks.PointerXYCallback.code = clipjs
hv.plotting.bokeh.callbacks.PointerXYCallback.models.append('x_range')

We can decide whether to make this the default (and tidy up the code) in a separate PR.

]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now try hovering over the ``Image`` above again and watch the cross-sections update as you move the cursor."
"Now if we display a ``Layout`` consisting of the ``Image`` acting as the source together with the ``DynamicMap``, the point shown on the right tracks the cursor position when hovering voer the image on the left:"

This comment has been minimized.

@philippjfr

philippjfr May 8, 2017

Member

Typo: hovering over

@philippjfr

This comment has been minimized.

Member

philippjfr commented May 8, 2017

Looks great, all good improvements. Merging.

@philippjfr philippjfr merged commit 0c558db into master May 8, 2017

0 of 2 checks passed

continuous-integration/travis-ci/pr The Travis CI build is in progress
Details
continuous-integration/travis-ci/push The Travis CI build is in progress
Details

@philippjfr philippjfr deleted the improving_new_tutorials branch May 25, 2017

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