Clarifications to the interactive docs #3362
Conversation
| @@ -784,36 +791,6 @@ where the user can choose the colors of the chart interactively: | |||
| color_usa, color_europe, color_japan | |||
| ) | |||
|
|
|||
| .. _encoding-channel-binding: | |||
There was a problem hiding this comment.
I moved this to the bottom because I find the legend and scale examples less complicated so they could go first
| xcol_param | ||
| ) | ||
|
|
||
| It was possible to achieve something similar before the introduction of parameters in Altair 5 by using ``transform_fold`` and ``transform_filter``, but the spec for this is more complex (as can be seen in `this SO answer <https://stackoverflow.com/a/70950329/2166823>`_) so the solution above is to prefer. |
There was a problem hiding this comment.
I didn't include this section in this PR because I think it's not really relevant anymore now that Altair 5 has been out for a while and using params is so much simpler.
| @@ -874,8 +909,15 @@ Altair allows custom interactions by utilizing the `expression language of Vega | |||
| To simplify building these expressions in Python, Altair provides the ``expr`` module, which offers constants and functions to construct expressions using Python syntax. Both JavaScript-syntax and Python-syntax are supported within Altair to define an expression | |||
| and an introductory example of each is available in the :ref:`user-guide-calculate-transform` transform documentation so we recommend checking out that page before continuing. | |||
|
|
|||
| Expressions inside Parameters | |||
There was a problem hiding this comment.
I added a few headings to break this section up and make it more readable
| For now, | ||
| there are two possible workarounds. | ||
| You can either pass the geographic data | ||
| via a transform lookup instead of via :class:`Chart` | ||
| as in the :ref:`gallery_us_incomebrackets_by_state_facet` gallery example. | ||
| Or, | ||
| you can manually filter the data in pandas, | ||
| and create a small multiples chart via concatenation | ||
| as in the following example: |
There was a problem hiding this comment.
I thought this was worth mentioning as an alternative approach
| @@ -559,9 +566,11 @@ populous states. Using an ``alt.selection_point()`` we define a selection parame | |||
|
|
|||
|
|
|||
| The interaction is two-directional. If you click (shift-click for multi-selection) on a geometry or bar the selection receive an ``opacity`` of ``1`` and the remaining an ``opacity`` of ``0.2``. | |||
| It is also possible to create charts with interval selections, | |||
| as can be seen in the :ref:`gallery_interval_selection_map_quakes` gallery example. | |||
There was a problem hiding this comment.
This example is really cool, and a good place to redirect too for people who want to learn more
| Tile-based Maps | ||
| ^^^^^^^^^^^^^^^ | ||
|
|
||
| To use tile-based maps (such as OpenStreetMap) as the background for ``mark_geoshape``, | ||
| you can use the package `Altair Tiles <https://altair-viz.github.io/altair_tiles>`_ together with Altair. |
There was a problem hiding this comment.
@binste Now that altair_tiles is part of altair[all] I would be onboard with you adding some of the examples directly into this mark_geoshape page if you think that makes sense (as well as a few gallery examples for visibility).
There was a problem hiding this comment.
Thanks for linking to altair_tiles! Yeah, sounds like a good next step to add a simple example to the Altair docs. I have it on my list :)
| # category: interactive charts | ||
|
|
There was a problem hiding this comment.
I missed this in my previous PR
There was a problem hiding this comment.
Thanks for the improvements @joelostblom!
My only thought is that I'd like to talk about whether we want the docs to encourage people to build up expressions as stings, or to use alt.datum and alt.expr builders to create up expressions as Python objects. I think I'd prefer to lean toward using the Python builders so that people don't need to think about the JavaScript-style (but not actual JavaScript) syntax.
| y='Miles_per_Gallon:Q', | ||
| color='Origin:N' | ||
| ).transform_calculate( | ||
| x=f'datum[{xcol_param.name}]' |
There was a problem hiding this comment.
Should we encourage us of alt.datum here? I think this could be alt.datum[xcol_param.name]. Or does that not work?
There was a problem hiding this comment.
Unfortunately it doesn't because of some additional inserted quotation. I opened #3366 to track it
There was a problem hiding this comment.
Thanks for the review @jonmmease! I agree that it would be nice to use the python syntax more. I think the advantages are autocompletion and docstrings (although these seems to be very sparse at the moment). Currently it does not seem to work with signal/parameters so I opened #3366 for that
| y='Miles_per_Gallon:Q', | ||
| color='Origin:N' | ||
| ).transform_calculate( | ||
| x=f'datum[{xcol_param.name}]' |
There was a problem hiding this comment.
Unfortunately it doesn't because of some additional inserted quotation. I opened #3366 to track it
I have been working a bit more with expressions lately and have some suggestions for clarifications in the docs. I also tried to point to more advanced gallery examples in a couple of places and included mentions of dash-vega-components and altair-tiles in the relevant pages. Finally, I also added an example of how to bring selected points to the foreground.
The interactive page is becoming quite long so we might consider splitting it into two (or three if we move the JupyterChart section under "interactivity" too)? The bindings and widgets page is about half page so that could be a natural split point, but I don't know if that will break some links; then it's probably not worth it.
close #3360