Binding documentation #1113

kindofluke · 2018-08-23T21:02:11Z

This pull request is to facilitate discussion of the binding documentation for which documentation help was requested in #1060

this has been my approach:

With adding input elements and bindings the page should just be called interactions.
Add simple dropdown example
add an example using filter
enumerate all of the avail input elements.
bind to "scales" magic for panning and zooming
headers are all out of wack
spelling and proofread

I am attaching a small screen recording of the two examples:

Opening the PR for general feedback I don't think its ready but I need some ideas on next steps.

Having issues with RST header sizing.

…tion

jakevdp

Great start overall! A few comments throughout.

jakevdp · 2018-08-23T21:09:08Z

doc/user_guide/interactions.rst

+
+- the :class:`selection` object which captures interactions from the mouse or through other inputs to effect the chart. Inputs can either be events like moust clicks or drags. Inputs can also be elemnts like a drop-down, radio button or slider. Selections can be used alone but if you want to have change any element of your chart you will need to connect them to a *condition*. 
+- the :class:`condition` function takes the selection input and changes an element of the chart based on that input. 
+- the :class:`bind` property of a selection which establishes a two-way binding between the selection and an input element of your chart. 


Replace :class:`selection` with :func:`selection` and :class:`condition` with :func:`condition` .

bind is neither a class nor a function in Altair, so there's no appropriate sphinx directive to refer to it. You can just use ``bind``.

jakevdp · 2018-08-23T21:09:59Z

doc/user_guide/interactions.rst

@@ -236,9 +251,101 @@ over them with your mouse:
    multi_mouseover = alt.selection_multi(on='mouseover', toggle=False, empty='none')
    make_example(multi_mouseover)

+Binding: Adding Data Driven Inputs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+With an understanding of the selection types and conditions, you can now add data-driven input elements to the charts using the  :class:`bind`. As specified by `Vega-lite binding <https://vega.github.io/vega-lite/docs/bind.html#input-element-binding>`_, selections can be bound two-ways:


:class:`bind` -> ``bind`` attribute?

jakevdp · 2018-08-23T21:13:00Z

doc/user_guide/interactions.rst

+    )
+
+
+    scatter


rather than assigning the chart to scatter and putting scatter below, just leave out the assignment altogether.

jakevdp · 2018-08-23T21:14:35Z

doc/user_guide/interactions.rst

+^^^^^^^^^^^^^^^^^^^^^
+With single selections, an input element can be added to the chart to establish a binding between the input and the selection. 
+
+For instance, using our example from above a dropdown can be used to highlight cars from a specific :origin: :


I'm not familiar with this :origin: syntax in RST. What does it do?

Maybe change :origin: to ``origin``? Or just origin?

jakevdp · 2018-08-23T21:16:09Z

doc/user_guide/interactions.rst

+
+For instance, using our example from above a dropdown can be used to highlight cars from a specific :origin: :
+
+.. altair-plot::


blank line is required after the altair-plot directive

jakevdp · 2018-08-23T21:16:31Z

doc/user_guide/interactions.rst

+
+Bindings and input elements can also be used to filter data on the client side. Reducing noise in the chart and allowing the user to see just certain selected elements:
+
+.. altair-plot::


Add blank line

great catch. I only found one other reference (on the weather chart which was funny given that I missed it before) I think we should be there.

jakevdp · 2018-08-23T21:17:00Z

doc/user_guide/interactions.rst

+    )
+
+
+    scatter


Don't assign to scatter (as above)

jakevdp · 2018-08-23T21:17:06Z

doc/user_guide/interactions.rst

+^^^^^^^^^^^^^
+With interval selections, the bind property can be set to the value of :"scales":. In these cases, the binding will automatically respond to the panning and zooming along the chart:
+
+.. altair-plot::


jakevdp · 2018-08-23T21:17:14Z

doc/user_guide/interactions.rst

+                        alt.Color('Origin:N', legend=None),
+                        alt.value('lightgray'))
+
+    scatter = alt.Chart(cars).mark_point().encode(


remove assignment

jakevdp · 2018-08-23T21:24:59Z

If you're willing to tackle it, it might be useful to add some examples of the various input bindings in the gallery. The only one we have now is a bit more complicated than I'd like it to be.

jakevdp · 2018-08-23T21:25:14Z

(That would also lead to fewer N/A entries in the table!)

kindofluke · 2018-08-23T21:26:08Z

@jakevdp I also was going to add this as just a good interaction example. (you are the original author of the vega example but I can't quite get the interval select to work when you select from the scatter and the bars adjust.

GIST Seattle Weather

kindofluke · 2018-08-23T21:27:04Z

I totally agree. I will try to make a compound chart that has drop down radio buttons, and the rest.

jakevdp · 2018-08-23T21:28:21Z

We do have a version of that in the gallery: https://altair-viz.github.io/gallery/seattle_weather_interactive.html

kindofluke · 2018-08-23T22:26:48Z

🤦 totally missed this.

kindofluke · 2018-08-24T01:43:01Z

Do you think it is possible to change the x or y fields through a selection?

I was thinking of this example Scatter Plot With Varying Dimension.

I think this is possible with with an expression referring to the signal value. If it is possible it could be really helpful as example of a selection not referring to an encoding. If not, I am still going to use this movie dataset because it's rich scatter plot that benefits from filters and highlights based on inputs.

I can do radio buttons to highlight movies of a certain imdb rating. Maybe a slider to filter the gross total of each film. I probably won't recreate the null values though that is a nice feature.

jakevdp · 2018-08-24T02:06:30Z

Do you think it is possible to change the x or y fields through a selection?

No, that's not possible in Vega-Lite.

jakevdp · 2018-08-24T02:07:09Z

You can work around it by stacking the two columns, adding an indicator variable, and filtering on that indicator variable.

kindofluke · 2018-08-24T02:18:48Z

Addressed most of your comments in the latest and added an example based on movies.

the example is having a problem with a radio buttons (at least on my browser) I am going to look at that tomorrow (getting late)

jakevdp · 2018-08-24T02:39:43Z

One of the issues with bindings is that they are not initialized properly, and do not apply any selection or filtering until the user interacts with them. This is particularly problematic in the case of multiple bindings, because you have to click all of them at least once before they will interact properly. That's one reason I haven't done much with docs or examples of bindings up to this point.

It's being addressed in vega-lite: see vega/vega-lite#4139

…user guide

kindofluke · 2018-08-24T22:23:20Z

Ok, I reformatted the example to avoid the initialization problem and focus on teaching how the bindings can work in different ways.

I recommend building the gallery page to view it.

The issue I ran into was that the dates in the data file are "4-Mar-74" which means i really needed a function to parse them and I couldn't use an expression. I thought I found a clever workaround to download the data into a dataframe first but it appears that did not work in CI (it did work locally).

I will try and fix the build error but for now you can sample it.

jakevdp · 2018-08-24T23:00:54Z

Yeah, we try to avoid anything requiring HTTP access in the example scripts, so that tests can be run in contexts with no web access.

Vega-Lite will parse the date properly if it's used in a temporal encoding within the chart.

If you're not using the column in an encoding but you still want it parsed as a date, you can use the alt.UrlData(url, format=alt.DataFormat(parse={'Release_Date': 'date'))

* fix the links

kindofluke · 2018-08-28T00:52:24Z

OK Everything is all set now I think.

We have a solid example of all the bindings and a decent write up of how the bindings actually work and connect to the selections.

Let me know what you think happy to keep tinkering or we can brainstorm some more examples.

jakevdp

Looks good! A couple more minor comments and then we can merge.

jakevdp · 2018-08-28T18:12:29Z

doc/user_guide/interactions.rst

@@ -1,19 +1,31 @@
 .. currentmodule:: altair

-.. _user-guide-selections:
+.. _user-guide-interactions:


I think the user-guide-selections cross reference is used a couple times elsewhere in the docs. Since you're renaming it here, it should be renamed elsewhere as well.

Sorry I missed this in previous. Updated found one reference as stated above.

jakevdp · 2018-08-28T18:13:45Z

doc/user_guide/interactions.rst

+^^^^^^^^^^^^^^^^^^^^^
+With single selections, an input element can be added to the chart to establish a binding between the input and the selection. 
+
+For instance, using our example from above a dropdown can be used to highlight cars from a specific :origin: :


Maybe change :origin: to ``origin``? Or just origin?

1. Find all references to `user-guide-selections` and update to refer to the new page name 2. change coding style on chart reference in interactions.

kindofluke · 2018-08-29T20:05:05Z

All set on latest commit. If I am too much trouble you can throw me another one from #1060.

jakevdp · 2018-08-29T20:27:23Z

Looks good – thanks so much for all your work on this!

Luke Shulman added 3 commits August 16, 2018 18:02

First pass at Adjusting page for bindings.

0002440

Having issues with RST header sizing.

minor updates

07484d7

Merge remote-tracking branch 'upstream/master' into binding-documenta…

3478c0d

…tion

jakevdp reviewed Aug 23, 2018

View reviewed changes

Adding commit of multiple interactions

c38551d

Adding movie based multiple interactions example

e0bf3cc

Luke Shulman added 2 commits August 24, 2018 18:13

Updating the interations example while also fixing references in the …

bb3f188

…user guide

better scale config

68f9213

Luke Shulman added 3 commits August 27, 2018 20:34

Fixing and removing the html request with altair formatting.

259e6b8

* Retitle the page.

1fb57fa

* fix the links

Remove unused libraries

622e079

jakevdp reviewed Aug 28, 2018

View reviewed changes

Luke Shulman added 2 commits August 29, 2018 15:59

Edits based on pr

93add7c

1. Find all references to `user-guide-selections` and update to refer to the new page name 2. change coding style on chart reference in interactions.

removing one line

91919cc

jakevdp merged commit 701c656 into vega:master Aug 29, 2018

jakevdp mentioned this pull request Aug 29, 2018

DOC: improvements checklist #1060

Closed

13 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Binding documentation #1113

Binding documentation #1113

kindofluke commented Aug 23, 2018 •

edited

Loading

jakevdp left a comment

jakevdp Aug 23, 2018

jakevdp Aug 23, 2018

jakevdp Aug 23, 2018

jakevdp Aug 23, 2018

jakevdp Aug 28, 2018

jakevdp Aug 23, 2018

jakevdp Aug 23, 2018

kindofluke Aug 29, 2018

jakevdp Aug 23, 2018

jakevdp Aug 23, 2018

jakevdp Aug 23, 2018

jakevdp commented Aug 23, 2018

jakevdp commented Aug 23, 2018

kindofluke commented Aug 23, 2018

kindofluke commented Aug 23, 2018

jakevdp commented Aug 23, 2018

kindofluke commented Aug 23, 2018

kindofluke commented Aug 24, 2018

jakevdp commented Aug 24, 2018

jakevdp commented Aug 24, 2018

kindofluke commented Aug 24, 2018

jakevdp commented Aug 24, 2018 •

edited

Loading

kindofluke commented Aug 24, 2018

jakevdp commented Aug 24, 2018

kindofluke commented Aug 28, 2018

jakevdp left a comment

jakevdp Aug 28, 2018

kindofluke Aug 29, 2018

jakevdp Aug 28, 2018

kindofluke commented Aug 29, 2018

jakevdp commented Aug 29, 2018


		For instance, using our example from above a dropdown can be used to highlight cars from a specific :origin: :

		.. altair-plot::


		Bindings and input elements can also be used to filter data on the client side. Reducing noise in the chart and allowing the user to see just certain selected elements:

		.. altair-plot::

Binding documentation #1113

Binding documentation #1113

Conversation

kindofluke commented Aug 23, 2018 • edited Loading

jakevdp left a 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

jakevdp commented Aug 23, 2018

jakevdp commented Aug 23, 2018

kindofluke commented Aug 23, 2018

kindofluke commented Aug 23, 2018

jakevdp commented Aug 23, 2018

kindofluke commented Aug 23, 2018

kindofluke commented Aug 24, 2018

jakevdp commented Aug 24, 2018

jakevdp commented Aug 24, 2018

kindofluke commented Aug 24, 2018

jakevdp commented Aug 24, 2018 • edited Loading

kindofluke commented Aug 24, 2018

jakevdp commented Aug 24, 2018

kindofluke commented Aug 28, 2018

jakevdp left a 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

kindofluke commented Aug 29, 2018

jakevdp commented Aug 29, 2018

kindofluke commented Aug 23, 2018 •

edited

Loading

jakevdp commented Aug 24, 2018 •

edited

Loading