Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document vega dataframe support #7024

Merged
merged 1 commit into from
Jul 27, 2024
Merged

Document vega dataframe support #7024

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 66 additions & 11 deletions examples/reference/panes/Vega.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,37 +6,43 @@
"metadata": {},
"outputs": [],
"source": [
"import pandas as pd\n",
"import panel as pn\n",
"\n",
"pn.extension('vega')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The ``Vega`` pane renders Vega-based plots (including those from Altair) inside a panel. It optimizes the plot rendering by using binary serialization for any array data found on the Vega/Altair object, providing huge speedups over the standard JSON serialization employed by Vega natively. Note that to use the ``Vega`` pane in the notebook the Panel extension has to be loaded with 'vega' as an argument to ensure that vega.js is initialized.\n",
"The ``Vega`` pane renders Vega-based plots (including those from Altair) inside a panel. It optimizes plot rendering by using binary serialization for any array data found in the Vega/Altair object, providing significant speedups over the standard JSON serialization employed by Vega natively. Note that to use the ``Vega`` pane in the notebook, the Panel extension must be loaded with 'vega' as an argument to ensure that vega.js is initialized.\n",
"\n",
"#### Parameters:\n",
"\n",
"For details on other options for customizing the component see the [layout](../../how_to/layout/index.md) and [styling](../../how_to/styling/index.md) how-to guides.\n",
"For details on other options for customizing the component, see the [layout](../../how_to/layout/index.md) and [styling](../../how_to/styling/index.md) how-to guides.\n",
"\n",
"* **``debounce``** (int or dict): The debounce timeout to apply to selection events, either specified as a single integer value (in milliseconds) or a dictionary that declares a debounce value per event. Debouncing ensures that events are only dispatched N milliseconds after a user is done interacting with the plot.\n",
"* **``object``** (dict or altair Chart): Either a dictionary containing a Vega or Vega-Lite plot specification, or an Altair Chart\n",
"* **``theme``** (str): A theme to apply to the plot, must be one of 'excel', 'ggplot2', 'quartz', 'vox', 'fivethirtyeight', 'dark', 'latimes', 'urbaninstitute', 'googlecharts'.\n",
"* **``show_actions``** (boolean): Whether to show chart actions menu such as save, edit etc.\n",
"* **``object``** (dict or altair Chart): Either a dictionary containing a Vega or Vega-Lite plot specification, or an Altair Chart.\n",
"* **``show_actions``** (boolean): Whether to show the chart actions menu, such as save, edit, etc.\n",
"* **``theme``** (str): A theme to apply to the plot. Must be one of 'excel', 'ggplot2', 'quartz', 'vox', 'fivethirtyeight', 'dark', 'latimes', 'urbaninstitute', or 'googlecharts'.\n",
"\n",
"Readonly parameters:\n",
"\n",
"* **``selection``** (Selection): The Selection object exposes parameters which reflect the selections declared on the plot into Python. \n",
"* **``selection``** (Selection): The Selection object exposes parameters that reflect the selections declared on the plot into Python.\n",
"\n",
"___\n",
"\n",
"___"
"The ``Vega`` pane supports both [`vega`](https://vega.github.io/vega/docs/specification/) and [`vega-lite`](https://vega.github.io/vega-lite/docs/spec.html) specifications, which may be provided in raw form (i.e., a dictionary) or by defining an ``altair`` plot.\n",
"\n",
"---"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The ``Vega`` pane supports both ``vega`` and ``vega-lite`` specs which may be provided in a raw form (i.e. a dictionary) or by defining an ``altair`` plot.\n",
"### Vega and Vega-lite\n",
"\n",
"To display ``vega`` and ``vega-lite`` specification simply construct a ``Vega`` pane directly or pass it to ``pn.panel``:"
]
Expand Down Expand Up @@ -91,7 +97,7 @@
"metadata": {},
"outputs": [],
"source": [
"vgl_pane.object = {\n",
"vega_disasters = {\n",
" \"$schema\": \"https://vega.github.io/schema/vega-lite/v5.json\",\n",
" \"data\": {\n",
" \"url\": \"https://raw.githubusercontent.com/vega/vega/master/docs/data/disasters.csv\"\n",
Expand Down Expand Up @@ -127,13 +133,32 @@
" },\n",
" \"color\": {\"field\": \"Entity\", \"type\": \"nominal\", \"legend\": None}\n",
" }\n",
"}"
"}\n",
"vgl_pane.object = vega_disasters"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Lets reset the plot back to the original:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"vgl_pane.object = vegalite"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Responsive Sizing\n",
"\n",
"The `vega-lite` specification can also be responsively sized by declaring the width or height to match the container:"
]
},
Expand All @@ -143,7 +168,7 @@
"metadata": {},
"outputs": [],
"source": [
"responsive_spec = dict(vgl_pane.object, width='container')\n",
"responsive_spec = dict(vega_disasters, width='container', title=\"Responsive Plot\")\n",
"\n",
"vgl_responsive_pane = pn.pane.Vega(responsive_spec)\n",
"vgl_responsive_pane"
Expand All @@ -156,6 +181,36 @@
"Please note that the `vega` specification does not support setting `width` and `height` to `container`."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### DataFrame Data Values\n",
"\n",
"For convenience we support a Pandas DataFrame as `data` `values`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"dataframe_spec = {\n",
" \"title\": \"A Simple Bar Chart from a Pandas DataFrame\",\n",
" 'config': {\n",
" 'mark': {'tooltip': None},\n",
" 'view': {'height': 200, 'width': 500}\n",
" },\n",
" 'data': {'values': pd.DataFrame({'x': ['A', 'B', 'C', 'D', 'E'], 'y': [5, 3, 6, 7, 2]})},\n",
" 'mark': 'bar',\n",
" 'encoding': {'x': {'type': 'ordinal', 'field': 'x'},\n",
" 'y': {'type': 'quantitative', 'field': 'y'}},\n",
" '$schema': 'https://vega.github.io/schema/vega-lite/v3.2.1.json'\n",
"}\n",
"pn.pane.Vega(dataframe_spec)"
]
},
{
"cell_type": "markdown",
"metadata": {},
Expand Down
Loading