Add JupyterChart section to Users Guide

altair/jupyter/jupyter_chart.py

@@ -145,6 +145,11 @@ def _on_change_chart(self, change):
 
         if params is not alt.Undefined:
             for param in new_chart.params:
+                if isinstance(param.name, alt.ParameterName):
+                    clean_name = param.name.to_json().strip('"')
+                else:
+                    clean_name = param.name
+
                 select = getattr(param, "select", alt.Undefined)
 
                 if select != alt.Undefined:
@@ -158,27 +163,27 @@ def _on_change_chart(self, change):
                         ):
                             # Point selection with no associated fields or encodings specified.
                             # This is an index-based selection
-                            selection_types[param.name] = "index"
-                            empty_selections[param.name] = IndexSelection(
-                                name=param.name, value=[], store=[]
+                            selection_types[clean_name] = "index"
+                            empty_selections[clean_name] = IndexSelection(
+                                name=clean_name, value=[], store=[]
                             )
                         else:
-                            selection_types[param.name] = "point"
-                            empty_selections[param.name] = PointSelection(
-                                name=param.name, value=[], store=[]
+                            selection_types[clean_name] = "point"
+                            empty_selections[clean_name] = PointSelection(
+                                name=clean_name, value=[], store=[]
                             )
                     elif select_type == "interval":
-                        selection_types[param.name] = "interval"
-                        empty_selections[param.name] = IntervalSelection(
-                            name=param.name, value={}, store=[]
+                        selection_types[clean_name] = "interval"
+                        empty_selections[clean_name] = IntervalSelection(
+                            name=clean_name, value={}, store=[]
                         )
                     else:
                         raise ValueError(f"Unexpected selection type {select.type}")
-                    selection_watches.append(param.name)
-                    initial_vl_selections[param.name] = {"value": None, "store": []}
+                    selection_watches.append(clean_name)
+                    initial_vl_selections[clean_name] = {"value": None, "store": []}
                 else:
                     clean_value = param.value if param.value != alt.Undefined else None
-                    initial_params[param.name] = clean_value
+                    initial_params[clean_name] = clean_value
 
         # Setup params
         self.params = Params(initial_params)

doc/user_guide/data.rst

@@ -627,6 +627,7 @@ data before usage in Altair using GeoPandas for example as such:
    customization
    configuration
    saving_charts
+   jupyter_chart
 
 
 .. toctree::

doc/user_guide/interactions.rst

@@ -991,11 +991,11 @@ For more information on how to fine-tune selections, including specifying other
 mouse and keystroke options, see the `Vega-Lite Selection documentation
 <https://vega.github.io/vega-lite/docs/selection.html>`_.
 
-Limitations
-~~~~~~~~~~~
-
-Some possible use cases for the above interactivity are not currently supported by Vega-Lite, and hence are not currently supported by Altair.  Here are some examples.
-
-1. If we are using a ``selection_point``, it would be natural to want to return information about the chosen data point, and then process that information using Python. This is not currently possible, so any data processing will have to be handled using tools such as ``transform_calculate``, etc. You can follow the progress on this in the following issue: https://github.com/altair-viz/altair/issues/1153.
-
-   - The dashboarding package ``Panel`` has added support for processing Altair selections with custom callbacks in their 0.13 release. This is currently the only Python dashboarding package that supports custom callbacks for Altair selections and you can read more about how to use this functionality in `the Panel documentation <https://pyviz-dev.github.io/panel/reference/panes/Vega.html#selections>`_.
+Access Params From Python
+~~~~~~~~~~~~~~~~~~~~~~~~~
+As of Vega-Altair 5.1, it's now possible to access the values of variable and selection parameters
+from Python using the :ref:`user-guide-jupyterchart` class.
+
+Additionally, the dashboarding package ``Panel`` includes support for processing Altair selections
+with custom callbacks. See the
+`Panel documentation <https://panel.holoviz.org/reference/panes/Vega.html#selections>`_.