Add ability to define Links between plots #2832

philippjfr · 2018-06-26T17:27:31Z

This PR adds the concept of a Link to HoloViews. Conceptually the Link is somewhat similar to a Stream in that it subscribes to changes and events on some source object and in turn triggers some event in response to it. However unlike a Stream it will not transmit that event from the frontend to the backend, instead it directly triggers some action on the target object. It therefore allows complex linked behaviors to be executed without involving a Python kernel.

This has several major benefits:

The linked action can be performed even in a static plot
The data does not have to be sent across a websocket (and then trigger an event which again sends stuff back across a websocket)
It is much faster and more responsive than python callback

The design/implementation of the Link also borrows very heavily from the inspiration of the Stream classes which has proven itself to be very solid and flexible. Each Link has a corresponding LinkCallback which defines what happens in case an event on the source is triggered. In the case of bokeh (currently the only supported backend for Links), the LinkCallback defines a (hopefully) small amount of JS which defines the action to be performed. In addition just like a StreamCallback it defines which models the callback should have access to and on which events/changes should trigger it. In this way we can concisely declare the linkage between two visualizations.

As a simple example I've prototyped a PathTableLink, what this does is show a table of the currently selected Path.

path = hv.Path([np.random.rand(10, 2), np.random.rand(10, 2)], ['xs', 'ys']).options(tools=['tap'])
table = hv.Table([], ['xs', 'ys'])
hv.links.PathTableLink(path, table)
path + table

Write documentation about links
Add at least 2-3 example Link classes along with reference examples
Add unit tests

philippjfr · 2018-06-26T18:27:51Z

@jbednar @jlstevens Before I work on this much more thoughts and comments would be appreciated. While implementing linked tables and paths using streams I found that things were simply much too slow when editing large-ish paths/polygons. I've also been thinking about something like this for a while when looking at altair since they provide various ways of linking plots, e.g. see their interactive histogram: https://altair-viz.github.io/gallery/selection_histogram.html

philippjfr · 2018-06-27T19:53:24Z

Here is another example of a Link I just prototyped:

philippjfr · 2018-06-27T20:13:55Z

It also provides a good mechanism to declare the new bokeh RangeTool:

%%opts Curve [shared_axes=False]
dates = pd.date_range('2015-01-01', '2017-09-26')
data = np.random.randn(1000).cumsum()
tgt = hv.Curve((dates, data), 'Date').options(width=800)
src = hv.Curve((dates, data), 'Date').options(width=800, height=100)
RangeLink(src, tgt)
(tgt + src).cols(1)

jlstevens · 2018-06-28T13:03:36Z

holoviews/links.py

@@ -0,0 +1,45 @@
+from collections import defaultdict


Couple of suggestions where this might live:

Maybe hv.util.links?

Or maybe hv.plotting.links (this might be better actually)

Let's go with hv.plotting.links.

jlstevens · 2018-06-28T13:04:20Z

holoviews/links.py

+class PathTableLink(Link):
+    """
+    Links the currently selected Path to a Table.
+    """


This is a rather specific example that is more of a specialized, custom link. Ideally we can find some very general link types that make sense to everybody.

Yes, still thinking about a few examples, the RangeToolLink I demonstrated above is definitely one that will be generally useful.

jlstevens · 2018-06-28T13:06:39Z

holoviews/plotting/bokeh/plot.py

@@ -355,6 +356,39 @@ def sync_sources(self):
        self.handles['shared_sources'] = shared_sources
        self.handles['source_cols'] = source_cols

+    def init_links(self):


The three methods below are tightly coupled to each other but only loosely coupled to BokehPlot (only other use of self is self.traverse). For this reason I would consider moving them to one of the appropriate Link classes.

jbednar · 2018-06-28T13:09:27Z

This looks fabulous, both for speed and for making things work in static exports! A user guide for how to write a Link class would be really helpful, because even though it's an advanced topic, it's something people would be very motivated to do so that they could make some amazing static plots to cover common cases in their domain.

Will it be possible to use Link and Stream together, so that plots are linked in static exports but some other (less crucial) Python-derived functionality is available when there is a live server?

philippjfr · 2018-06-28T13:11:30Z

Will it be possible to use Link and Stream together, so that plots are linked in static exports but some other (less crucial) Python-derived functionality is available when there is a live server?

Absolutely, e.g. take the Path-Table link, you could click on a path, it would then show the vertices in the table, and then you could subscribe to the currently shown vertices with a stream.

jlstevens · 2018-06-28T13:21:45Z

Overall I think this approach is fine as it isn't too different from what we do for streams. I'll know better once I see some docs with general examples: right now RangeLink is the most compelling demo (and I think it ought to be called RangeToolLink). Though, that does make it bokeh specific so maybe it should live in the bokeh plotting sub package?

jlstevens · 2018-06-28T13:26:54Z

One thing that would be good would be to ensure the docs talk to people familiar with BokehJS but not holoviews so the reader can easily apply their bokeh knowledge to building new types of link.

philippjfr · 2018-06-28T14:12:42Z

One thing that would be good would be to ensure the docs talk to people familiar with BokehJS

That's definitely sensible and at least one example should cover that. One thing I haven't quite made clear yet is that Links are not necessarily required to contain JS code, e.g. the RangeToolLink is pure Python and just adds the RangeTool to one plot and links it to the ranges on another. Similarly we had already discussed an explicit DataLink, which could also be trivially implemented using this approach without any CustomJS.

jbednar · 2018-06-28T14:23:44Z

Excellent. Definitely need good docs to make this clear.

philippjfr · 2018-07-02T16:21:00Z

Okay, I've now added demo examples, a user guide and unit tests. I've decided against switching Links to ParameterizedFunctions because they can be called multiple times which would cause issues and they are more complex to explain to users.

This is ready to review now and can be polished further in later PRs.

jlstevens · 2018-07-02T17:11:28Z

examples/user_guide/Linking_Plots.ipynb

+    "from holoviews.plotting.links import DataLink\n",
+    "\n",
+    "scatter1 = hv.Scatter(np.random.randn(1000, 2))\n",
+    "scatter2 = hv.Scatter(np.random.randn(1000, 2)*2, 'x2', 'y2')\n",


Would be good to use some structured data here to make the nature of the data link clearer. The data could be real data or artificial data structured in some way so you can understand how 'rows' are linked between the plots.

jlstevens · 2018-07-02T17:14:52Z

examples/user_guide/Linking_Plots.ipynb

+   "metadata": {},
+   "source": [
+    "When working with the bokeh backend in HoloViews complex interactivity can be achieved using very little code, whether that is shared axes, which zoom and pan together or shared datasources, which allow for linked cross-filtering. Separately it is possible to create custom interactions by attaching LinkedStreams to a plot and thereby triggering events on interactions with the plot. The Streams based interactivity affords a lot of flexibility to declare custom interactivity on a plot, however it always requires a live Python kernel to be connected either via the notebook or bokeh server. The ``Link`` classes described in this user guide however allow declaring interactions which do not require a live server, opening up the possibility of declaring complex interactions in a plot.\n",
+    "\n",


... of declaring complex interactions in a plot that can be exported to a static HTML file?

Sounds good.

jlstevens · 2018-07-02T17:15:43Z

examples/user_guide/Linking_Plots.ipynb

+    "## What is a Link?\n",
+    "\n",
+    "A Link defines some connection between a source and target object in their visualization. It is quite similar to a Stream as it allows defining callbacks in response to some change or event on the source object, however, unlike a Stream, it does not transfer data and make it available to user defined subscribers. Instead a Link directly causes some action to occur on the target, for JS based backends this usually means that a corresponding JS callback will effect some change on the target in response to a change on the source.\n",
+    "\n",


... however, unlike a Stream, it does not transfer data between the browser and a Python process?

Yep, seems clearer.

jlstevens · 2018-07-02T17:18:45Z

examples/user_guide/Linking_Plots.ipynb

+    "A Link defines some connection between a source and target object in their visualization. It is quite similar to a Stream as it allows defining callbacks in response to some change or event on the source object, however, unlike a Stream, it does not transfer data and make it available to user defined subscribers. Instead a Link directly causes some action to occur on the target, for JS based backends this usually means that a corresponding JS callback will effect some change on the target in response to a change on the source.\n",
+    "\n",
+    "One of the simplest examples of a Link is the DataLink which links the data from two sources as long as they match in length, e.g. below we create two elements with data of the same length. By declaring a ``DataLink`` between the two we can ensure they are linked and can be selected together:"
+   ]


It isn't clear to me how a DataLink extends beyond selections. Maybe another datalink example showing simultaneous (linked) updates would make it clearer?

DataLink is primarily for linked selections and for slight efficiency gains, not sure what you mean by linked updates.

In that case I'm not sure how the data is linked. Sounds like the selections are linked (unless this achieves some other useful behavior). So SelectionLink?

jlstevens · 2018-07-02T17:21:55Z

examples/user_guide/Linking_Plots.ipynb

+   "metadata": {},
+   "source": [
+    "In this case we are interested in the 'source' handle, but we still have to tell it which events should trigger the callback. Bokeh callbacks can be grouped into two types model property changes and and events. For more detail on these two types of callbacks see the [Bokeh user guide](https://bokeh.pydata.org/en/latest/docs/user_guide/interaction/callbacks.html#userguide-interaction-jscallbacks).\n",
+    "\n",


'into two types model property changes'? I suspect some punctuation is missing here...

jlstevens · 2018-07-02T17:23:31Z

examples/user_guide/Linking_Plots.ipynb

+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In this case we are interested in the 'source' handle, but we still have to tell it which events should trigger the callback. Bokeh callbacks can be grouped into two types model property changes and and events. For more detail on these two types of callbacks see the [Bokeh user guide](https://bokeh.pydata.org/en/latest/docs/user_guide/interaction/callbacks.html#userguide-interaction-jscallbacks).\n",


'and and events'

jlstevens · 2018-07-02T17:24:11Z

examples/user_guide/Linking_Plots.ipynb

+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now we have the ``Link`` class we need to write the implementation in the form of a ``LinkCallback``. A ``LinkCallback`` should declare the ``source_model`` we want to listen to events on and a ``target_model``, declaring which model should be altered in response. To find out which models we can attach the ``Link`` to we can create a ``Plot`` instance and look at the ``plot.handles``, e.g. here we create a ``ScatterPlot`` and can see it has a 'source', which represents the ``ColumnDataSource``."


Right after '... write the implementation in the form of a LinkCallback' I would point to the two types of bokeh callback with the link (html this time!) to the bokeh docs. This helps make it more concrete by linking to bokeh earlier.

I agree, I was hoping to find a way to make the link clearer. I also wish bokeh docs had some more detailed section about the kind of events that are available.

jlstevens · 2018-07-02T17:27:19Z

examples/user_guide/Linking_Plots.ipynb

+    "We now want to change the ``glyph``, which defines the position of the ``HLine``, so we declare the ``target_model`` as ``'glyph'``. Having defined both the source and target model and the events we can finally start writing the JS callback that should be triggered. To declare it we simply define the ``source_code`` class attribute. To understand how to write this code we need to understand how the source and target models we have declared can be referenced from within the callback.\n",
+    "\n",
+    "The ``source_model`` will be made available by prefixing it with ``source_``, while the target model is made available with the prefix ``target_``. This means that the ``ColumnDataSource`` on the ``source`` can be referenced as ``source_source``, while the glyph on the target can be referenced as ``target_glyph``.\n",
+    "\n",


source_source? Would formatting like source_source help?

Ah 'prefixing' so source_source?

Yes, that helps. I've also considered renaming the handle to source -> cds, since source_cds would be much clearer, but I suspect someone is relying on that. So maybe we could alias it for now.

I'll go ahead with this, source_source just looks stupid and confusing.

I think renaming it this way will look less confusing and will also be clearer to understand...

jlstevens · 2018-07-02T17:29:23Z

examples/user_guide/Linking_Plots.ipynb

+    "    target_model = 'glyph'\n",
+    "    \n",
+    "    source_code = \"\"\"\n",
+    "        var inds = source_source.selected.indices;\n",


Ok, so source_source is a real thing. I think I'm getting the idea but I am finding this rather confusing at the moment.

It's very similar to the way streams work, but I'll have another go at clarifying this.

jlstevens · 2018-07-02T17:31:14Z

examples/user_guide/Linking_Plots.ipynb

+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "Link._callbacks['bokeh'][MeanHLineLink] = MeanHLineCallback"


Would be nice to have a better API for registering these things together than using _callbacks directly like this.

True, LinkedStreams should probably mirror that API since it's identical.

jlstevens · 2018-07-02T17:36:41Z

I've had a pass through the user guide. My main, high level comments:

Would be good to mark the section about writing your own links as an 'advanced' topic. This is not something I expect most people to do and people shouldn't be worried if they can't understand how to write their own links. The first half about usage should be friendly, showing people how to use the links we offer but the second half is more for people working at the developer level.
It might be nice to show how to write a Link without JS using the bokeh Python API (if possible!). One of the things you mentioned is you shouldn't have to write JS in all cases.

jlstevens · 2018-07-02T17:40:35Z

examples/gallery/demos/bokeh/image_range_tool.ipynb

+   ]
+  }
+ ],
+ "metadata": {


Please clear out all this metadata...

jlstevens · 2018-07-02T17:41:09Z

examples/gallery/demos/bokeh/image_range_tool.ipynb

+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Declare plot"


It is a neat example but it needs a sentence here to explain what is going on and what the user should try to see the linked ranges in action...

Agreed, at some point someone will have to go through all the demos and add some explanation. But you're right that new examples should have some text.

Same issue with timeseries_range_tool.ipynb...

philippjfr · 2018-07-02T17:41:28Z

Would be good to mark the section about writing your own links as an 'advanced' topic.

Agreed. I'll expand the section about usage a bit more and maybe think of a third Link example to include.

It might be nice to show how to write a Link without JS using the bokeh Python API

I'll try to think of one more, RangeTool and linking data were the two obvious cases but maybe an explicit RangeLink might also be useful. There is only so much you can do at the Python API level.

jlstevens · 2018-07-02T18:51:15Z

I'm generally happy with the design and docs though I do think some polish will be needed in a subsequent PR. Once the comments above are addressed, I am happy to see this PR merged with the understanding that more tweaks will follow.

One other suggestion to make the Link objects more useful was to add an unlink method to undo any previous linking behavior. That suggestions doesn't have to be added here but I do think it is a good idea.

philippjfr · 2018-07-03T13:58:47Z

Addressed most of the comments, merging now.

nayatti · 2020-06-04T07:02:25Z

Here is another example of a Link I just prototyped:

Hi, would it be possible to show the code of HistogramLink (and its callback if any)? I tried to make my own but it failed...

philippjfr added type: feature A major new feature tag: API tag: backend: bokeh status: WIP labels Jun 26, 2018

jlstevens reviewed Jun 28, 2018

View reviewed changes

jlstevens reviewed Jul 2, 2018

View reviewed changes

philippjfr added 19 commits July 3, 2018 13:13

Added initial Link implementation

8f1459d

Fixed bug in LinkCallback

45e418e

Improved LinkCallback

27653eb

Improved LinkedCallback capabilities

722c856

Refactored Link code

135edaf

Added Link examples

c4ed311

Improved Links

7c79a21

Added Links user guide

187a0ba

Added unit tests for links

f6ad388

Fixed flakes

3c3a909

Fixed bug in DataLink

2b119a7

Fixed image range link example

96f64c0

Made data range link more obvious

9502d1d

Aliased source handle to cds

2212cc2

Improvements for links

e8b6046

Fixes/updates to Link docs and examples

ec7b47c

Enabled LinkCallback validation

d61bec7

Slightly expanded Linking Plots user guide

8a33c7a

Fixed flake

a8df15b

philippjfr force-pushed the link_feature branch from ae0e558 to a8df15b Compare July 3, 2018 12:13

philippjfr merged commit 3cb7c83 into master Jul 3, 2018

philippjfr deleted the link_feature branch July 4, 2018 11:12

ea42gh mentioned this pull request Jul 18, 2018

How to plot full screen img or without scroll bar #2879

Open

philippjfr added this to the v1.11.0 milestone Nov 5, 2018

Add ability to define Links between plots #2832

Add ability to define Links between plots #2832

Conversation

philippjfr commented Jun 26, 2018 • edited Loading

philippjfr commented Jun 26, 2018 • edited Loading

philippjfr commented Jun 27, 2018

philippjfr commented Jun 27, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jbednar commented Jun 28, 2018

philippjfr commented Jun 28, 2018

jlstevens commented Jun 28, 2018

jlstevens commented Jun 28, 2018

philippjfr commented Jun 28, 2018

jbednar commented Jun 28, 2018

philippjfr commented Jul 2, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

philippjfr Jul 2, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

philippjfr Jul 2, 2018 • edited Loading

Choose a reason for hiding this comment

jlstevens commented Jul 2, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

philippjfr commented Jul 2, 2018 • edited Loading

jlstevens commented Jul 2, 2018

philippjfr commented Jul 3, 2018

nayatti commented Jun 4, 2020

philippjfr commented Jun 26, 2018 •

edited

Loading

philippjfr commented Jun 26, 2018 •

edited

Loading

philippjfr commented Jun 27, 2018 •

edited

Loading

philippjfr commented Jul 2, 2018 •

edited

Loading

philippjfr Jul 2, 2018 •

edited

Loading

philippjfr Jul 2, 2018 •

edited

Loading

philippjfr commented Jul 2, 2018 •

edited

Loading