Polishing and improving the tutorials added in 1.7

[jlstevens]

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.

[philippjfr]

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

Also "ustom linked Streams"

[jlstevens]

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

[jlstevens]

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]

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]

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]

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]

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]

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

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]

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

[jlstevens]

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

[jlstevens]

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

[jlstevens]

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]

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]

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]

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.

[philippjfr]

Typo: hovering over

[philippjfr]

Looks great, all good improvements. Merging.