Reorganize Widgets User guide #1654
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # Explanation | ||
|
|
||
| Explanation guides provide in-depth understanding of key concepts in hvPlot. These guides help you understand the reasoning behind design decisions and when to use different approaches. | ||
|
|
||
| ```{toctree} | ||
| :titlesonly: | ||
| :hidden: | ||
| :maxdepth: 2 | ||
|
|
||
| grouping_options | ||
| ``` |
|
There was a problem hiding this comment. Let's try to add "drill-down" somewhere in the text since this is the overarching operation allowed by hvPlot here. There was a problem hiding this comment. It seems to me you're writing a How-To guide that is a collection of smaller How-To guides. At least, it already feels longer than most How-To guides Panel has? It's fine by me but keep in mind that you are creating multiple How-Tos in one. Can you update the cells so they can be run independently? I.e. a user can copy/paste one code block and it just works. There was a problem hiding this comment. To respond to the first paragraph, it does look like 3 How-tos in one but they are all within the same theme (using groupby for widget interactivity) and they logically flow from one to the other. And tbh it's not a long notebook. There was a problem hiding this comment. When you write a how-to like that, please have a look at the reference doc of what you document, here |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,166 @@ | ||
| { | ||
| "cells": [ | ||
| { | ||
| "cell_type": "markdown", | ||
| "id": "770e0358", | ||
| "metadata": {}, | ||
| "source": [ | ||
| "# How to Explore Multidimensional Datasets with Widgets\n", | ||
| "\n", | ||
| "This guide shows you how to use hvPlot's automatic widget creation to interactively explore datasets with multiple dimensions. When you use the `groupby` parameter, hvPlot automatically creates widgets that let you drill-down into and explore your data dynamically." | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "markdown", | ||
| "id": "a30afa69", | ||
| "metadata": {}, | ||
| "source": [ | ||
| ":::{note}\n", | ||
| "When viewing on a static website, the widgets will be inoperable. To explore this functionality fully, download the notebook and run it in a live python environment.\n", | ||
| ":::" | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "markdown", | ||
| "id": "a1a16b3c", | ||
| "metadata": {}, | ||
| "source": [ | ||
| "## Basic Widget Creation with groupby\n", | ||
| "\n", | ||
| "When you use [`groupby`](option-groupby), hvPlot automatically selects the appropriate widget type based on your data. For categorical data like the 'species' column (composed of strings), hvPlot creates a drop-down menu (from a [Panel Select widget](https://panel.holoviz.org/reference/widgets/Select.html))." | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "code", | ||
| "execution_count": null, | ||
| "id": "ee6a096e", | ||
| "metadata": {}, | ||
| "outputs": [], | ||
| "source": [ | ||
| "import hvplot.pandas # noqa\n", | ||
| "\n", | ||
| "penguins = hvplot.sampledata.penguins(\"pandas\").dropna()\n", | ||
| "penguins.hvplot.scatter(\n", | ||
| " x='bill_length_mm',\n", | ||
| " y='bill_depth_mm',\n", | ||
| " groupby='species',\n", | ||
| " width=400\n", | ||
| ")" | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "markdown", | ||
| "id": "ee650c0d", | ||
| "metadata": {}, | ||
| "source": [ | ||
| "### Widget Types for Different Data Types\n", | ||
| "\n", | ||
| "hvPlot automatically chooses the appropriate widget type based on your data:\n", | ||
| "\n", | ||
| "- **Categorical/String data** → Drop-down Select widget (as shown above)\n", | ||
| "- **Numerical data** → [IntSlider widget](https://panel.holoviz.org/reference/widgets/IntSlider.html) for continuous exploration\n", | ||
| "- **Datetime data** → [DatetimeSlider widget](https://panel.holoviz.org/reference/widgets/DatetimeSlider.html) for temporal exploration\n", | ||
| "\n", | ||
| "For numerical columns like `year`, hvPlot creates a slider widget that lets you explore different values from the different years." | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "code", | ||
| "execution_count": null, | ||
| "id": "495f9a91", | ||
| "metadata": {}, | ||
| "outputs": [], | ||
| "source": [ | ||
| "import hvplot.pandas # noqa\n", | ||
| "\n", | ||
| "penguins = hvplot.sampledata.penguins(\"pandas\").dropna()\n", | ||
| "penguins.hvplot.scatter(\n", | ||
| " x='bill_length_mm',\n", | ||
| " y='bill_depth_mm',\n", | ||
| " groupby='year',\n", | ||
| " color='species',\n", | ||
| " width=400\n", | ||
| ")" | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "markdown", | ||
| "id": "ab1368b8", | ||
| "metadata": {}, | ||
| "source": [ | ||
| "## Customizing Widget Placement\n", | ||
| "\n", | ||
| "You can control where the widget appears using the [`widget_location`](option-widget_location) option. This is useful for creating layouts that work better with your specific visualization needs." | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "code", | ||
| "execution_count": null, | ||
| "id": "86fe3e21", | ||
| "metadata": {}, | ||
| "outputs": [], | ||
| "source": [ | ||
| "import hvplot.pandas # noqa\n", | ||
| "\n", | ||
| "penguins = hvplot.sampledata.penguins(\"pandas\").dropna()\n", | ||
| "penguins.hvplot.scatter(\n", | ||
| " x='bill_length_mm',\n", | ||
| " y='bill_depth_mm',\n", | ||
| " groupby='species',\n", | ||
| " widget_location='top_left'\n", | ||
| ")" | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "markdown", | ||
| "id": "3300b323", | ||
| "metadata": {}, | ||
| "source": [ | ||
| "## Exploring Multiple Dimensions\n", | ||
|
There was a problem hiding this comment. Reading the title I expected There was a problem hiding this comment. I don't understand what you mean? Edit: I get it now 🙃 |
||
| "\n", | ||
| "The penguins dataset has several categorical dimensions you can explore. We can group by multiple dimensions at once to explore different combinations of the data:" | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "code", | ||
| "execution_count": null, | ||
| "id": "530888e6", | ||
| "metadata": {}, | ||
| "outputs": [], | ||
| "source": [ | ||
| "import hvplot.pandas # noqa\n", | ||
| "\n", | ||
| "penguins = hvplot.sampledata.penguins(\"pandas\").dropna()\n", | ||
| "# group by island and sex\n", | ||
| "penguins.hvplot.scatter(\n", | ||
| " x='flipper_length_mm',\n", | ||
| " y='body_mass_g',\n", | ||
| " groupby=['island', 'sex'],\n", | ||
| " color='species',\n", | ||
| " width=400,\n", | ||
| ")" | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "markdown", | ||
| "id": "462915a5-3a79-4792-811c-f4df6eb59825", | ||
| "metadata": {}, | ||
| "source": [ | ||
| ":::{admonition} Next Steps\n", | ||
| ":class: seealso\n", | ||
| "\n", | ||
| "- For more advanced widget customization using Panel, see the [Panel Widgets Reference](../ref/api_compatibility/panel_widgets.ipynb)\n", | ||
| "- To understand the differences between `groupby`, `by`, and `color` parameters, see the [Grouping and Coloring Options Explanation](../explanation/grouping_options.ipynb)\n", | ||
| ":::" | ||
| ] | ||
| } | ||
| ], | ||
| "metadata": { | ||
| "language_info": { | ||
| "name": "python", | ||
| "pygments_lexer": "ipython3" | ||
| } | ||
| }, | ||
| "nbformat": 4, | ||
| "nbformat_minor": 5 | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # How-To Guides | ||
|
|
||
| How-to guides are practical, problem-oriented instructions that help you accomplish specific tasks with hvPlot. These guides assume you're already familiar with the basics and want to solve particular problems or achieve specific goals. | ||
|
|
||
| ```{toctree} | ||
| :titlesonly: | ||
| :hidden: | ||
| :maxdepth: 2 | ||
|
|
||
| Explore Multidimensional datasets <explore_with_widgets> | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,146 @@ | ||
| { | ||
| "cells": [ | ||
| { | ||
| "cell_type": "markdown", | ||
| "id": "16cbd331", | ||
| "metadata": {}, | ||
| "source": [ | ||
| "# Panel Widgets\n", | ||
| "\n", | ||
| "This reference shows advanced widget functionality using Panel for fine-grained control over hvPlot interactivity. Panel provides extensive customization options beyond hvPlot's built-in widget support." | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "markdown", | ||
| "id": "06bb92b5", | ||
| "metadata": {}, | ||
| "source": [ | ||
| ":::{warning}\n", | ||
| "The Panel APIs shown here may change in future versions.\n", | ||
| ":::\n", | ||
| ":::{note}\n", | ||
| " When viewing on a static website, the widgets will be inoperable. To explore this functionality fully, download the notebook and run it in a live python environment.\n", | ||
| ":::" | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "code", | ||
| "execution_count": null, | ||
| "id": "2830d9e5", | ||
| "metadata": {}, | ||
| "outputs": [], | ||
| "source": [ | ||
| "import panel as pn\n", | ||
| "import hvplot.pandas # noqa\n", | ||
| "\n", | ||
| "penguins = hvplot.sampledata.penguins(\"pandas\").dropna()" | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "markdown", | ||
| "id": "945104bd", | ||
| "metadata": {}, | ||
| "source": [ | ||
| "## Using Widgets as Plot Arguments\n", | ||
| "\n", | ||
| "Panel widgets can be used directly as arguments to hvPlot methods, allowing users to interactively select plot parameters like axes and plot types." | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "code", | ||
| "execution_count": null, | ||
| "id": "fbda9b9e", | ||
| "metadata": {}, | ||
| "outputs": [], | ||
| "source": [ | ||
| "x = pn.widgets.Select(name='x', options=['bill_length_mm', 'bill_depth_mm'])\n", | ||
| "y = pn.widgets.Select(name='y', options=['flipper_length_mm', 'body_mass_g'])\n", | ||
| "kind = pn.widgets.Select(name='kind', value='scatter', options=['scatter', 'bivariate'])\n", | ||
| "\n", | ||
| "plot = penguins.hvplot(x=x, y=y, kind=kind, colorbar=False, width=600)\n", | ||
| "pn.Row(pn.WidgetBox(x, y, kind), plot)" | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "markdown", | ||
| "id": "2534030a", | ||
| "metadata": {}, | ||
| "source": [ | ||
| "## Using Functions with `pn.depends`\n", | ||
| "\n", | ||
| "For more complex interactions, you can create functions decorated with `pn.depends` that respond to widget changes." | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "code", | ||
| "execution_count": null, | ||
| "id": "990e3783", | ||
| "metadata": {}, | ||
| "outputs": [], | ||
| "source": [ | ||
| "x = pn.widgets.Select(name='x', options=['bill_length_mm', 'bill_depth_mm'])\n", | ||
| "y = pn.widgets.Select(name='y', options=['flipper_length_mm', 'body_mass_g'])\n", | ||
| "kind = pn.widgets.Select(name='kind', value='scatter', options=['scatter', 'bivariate'])\n", | ||
| "by_species = pn.widgets.Checkbox(name='By species')\n", | ||
| "color = pn.widgets.ColorPicker(value='#ff0000')\n", | ||
| "\n", | ||
| "@pn.depends(by_species, color)\n", | ||
| "def by_species_fn(by_species, color):\n", | ||
| " return 'species' if by_species else color\n", | ||
| "\n", | ||
| "plot = penguins.hvplot(x=x, y=y, kind=kind, c=by_species_fn, colorbar=False, width=400, legend='top_right')\n", | ||
| "\n", | ||
| "pn.Row(pn.WidgetBox(x, y, kind, color, by_species), plot)" | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "markdown", | ||
| "id": "db5027d9", | ||
| "metadata": {}, | ||
| "source": [ | ||
| "## Widget Callbacks and Interactions\n", | ||
| "\n", | ||
| "You can also add callbacks to create more sophisticated widget interactions, such as enabling/disabling widgets based on other widget values." | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "code", | ||
| "execution_count": null, | ||
| "id": "9535677a", | ||
| "metadata": {}, | ||
| "outputs": [], | ||
| "source": [ | ||
| "def update(event):\n", | ||
| " if kind.value == 'bivariate':\n", | ||
| " color.disabled = True\n", | ||
| " by_species.disabled = True\n", | ||
| " else:\n", | ||
| " color.disabled = False\n", | ||
| " by_species.disabled = False\n", | ||
| "\n", | ||
| "kind.param.watch(update, 'value');" | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "markdown", | ||
| "id": "28cd0a30", | ||
| "metadata": {}, | ||
| "source": [ | ||
| ":::{admonition} Additional Resources\n", | ||
| ":class: seealso\n", | ||
| "- [Panel HoloViews Pane Documentation](https://panel.pyviz.org/reference/panes/HoloViews.html)\n", | ||
| "- [Panel Widgets Reference Gallery](https://panel.pyviz.org/reference/index.html)\n", | ||
| "- [Panel API Documentation](https://panel.pyviz.org/api/)\n", | ||
| ":::" | ||
| ] | ||
| } | ||
| ], | ||
| "metadata": { | ||
| "language_info": { | ||
| "name": "python", | ||
| "pygments_lexer": "ipython3" | ||
| } | ||
| }, | ||
| "nbformat": 4, | ||
| "nbformat_minor": 5 | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When you reference e.g.
groupbycan you add a link to the reference doc like[groupby](option-groupby)? That won't work for users running the notebook locally but that's fine.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
OK