diff --git a/doc/explanation/grouping_options.ipynb b/doc/explanation/grouping_options.ipynb new file mode 100644 index 000000000..c39bb3eec --- /dev/null +++ b/doc/explanation/grouping_options.ipynb @@ -0,0 +1,428 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "02909b6b", + "metadata": {}, + "source": [ + "# Understanding Grouping and Coloring Options\n", + "\n", + "This guide explains the key differences between hvPlot's three main approaches to handling categorical data: [groupby](option-groupby), [by](option-by), and [color/c](option-color). Understanding these differences is important for creating effective visualizations and choosing the right approach for your specific use case." + ] + }, + { + "cell_type": "markdown", + "id": "817592aa", + "metadata": {}, + "source": [ + "## Overview of the Three Approaches\n", + "\n", + "hvPlot provides three primary ways to handle categorical data in your plots:\n", + "\n", + "1. **`groupby`**: Creates interactive widgets with [HoloMap](https://holoviews.org/reference_manual/holoviews.html#holoviews.HoloMap) / [DynamicMap](https://holoviews.org/reference_manual/holoviews.html#holoviews.DynamicMap) containers\n", + "2. **`by`**: Creates multiple plot elements in [NdOverlay](https://holoviews.org/reference_manual/holoviews.html#holoviews.NdOverlay) or [NdLayout](https://holoviews.org/reference_manual/holoviews.html#holoviews.NdLayout) containers\n", + "3. **`color`/`c`**: Creates vectorized coloring within a single plot element\n", + "\n", + "Each approach produces different outputs, offers different interaction capabilities, and has different performance characteristics." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "dbeabe0c", + "metadata": {}, + "outputs": [], + "source": [ + "import hvplot.pandas\n", + "\n", + "penguins = hvplot.sampledata.penguins(\"pandas\").dropna()\n", + "penguins.head(3)" + ] + }, + { + "cell_type": "markdown", + "id": "98a0b527", + "metadata": {}, + "source": [ + "## `groupby`: Interactive Widgets\n", + "\n", + "The `groupby` parameter creates **interactive widgets** that allow users to filter and explore different subsets of your data dynamically.\n", + "\n", + "### What it creates:\n", + "- **HoloViews containers**: [HoloMap](https://holoviews.org/reference_manual/holoviews.html#holoviews.HoloMap) or [DynamicMap](https://holoviews.org/reference_manual/holoviews.html#holoviews.DynamicMap) object\n", + "- **Interactive widgets**: Automatically generated based on data type\n", + "- **Single view at a time**: Only one category visible per interaction\n", + "\n", + "### When to use:\n", + "- When you want to explore different subsets of data interactively\n", + "- When you have many categories that would clutter a single plot\n", + "- When building dashboards or interactive reports\n", + "- When you need to reduce visual complexity" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a2005058", + "metadata": {}, + "outputs": [], + "source": [ + "plot_groupby = penguins.hvplot.scatter(\n", + " x='bill_length_mm',\n", + " y='bill_depth_mm',\n", + " groupby='species',\n", + " title=\"Groupby: Interactive Widget\",\n", + " width=400,\n", + " dynamic=False, # loads all the data on the frontend to enable interactivity on the fly\n", + ")\n", + "plot_groupby" + ] + }, + { + "cell_type": "markdown", + "id": "ae7b6cd5", + "metadata": {}, + "source": [ + "### Indexing and Access\n", + "\n", + "When you use `groupby`, hvPlot creates a **HoloViews container object** (HoloMap or DynamicMap) that acts like a dictionary. This container stores separate plot elements for each category value, which is why you can \"index into\" specific categories.\n", + "\n", + "**Why indexing works**: The container maps category values (like `'Adelie'`, `'Chinstrap'`, `'Gentoo'`) to individual plot elements. Each category becomes a \"key\" that you can use to access its corresponding plot.\n", + "\n", + "**What happens when you index**: You extract a single plot element from the container, giving you just the data for that specific category without the interactive widget.\n", + "\n", + "**Use cases**: \n", + "- Extract specific categories for further analysis\n", + "- Combine individual categories in custom layouts\n", + "- Access the underlying plot element for advanced customization" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "55e5fd82", + "metadata": {}, + "outputs": [], + "source": [ + "# Access specific category: plot['category_value']\n", + "adelie_only = plot_groupby['Adelie'] # Shows only Adelie penguins\n", + "print(f\"Type of groupby plot: {type(plot_groupby)}\")\n", + "print(f\"Type of specific species: {type(adelie_only)}\")\n", + "adelie_only" + ] + }, + { + "cell_type": "markdown", + "id": "30b3be0e", + "metadata": {}, + "source": [ + "## `by`: Multiple Plot Elements\n", + "\n", + "The `by` parameter creates **multiple plot elements** shown simultaneously, either overlaid or in separate subplots.\n", + "\n", + "### What it creates:\n", + "- [NdOverlay](https://holoviews.org/reference_manual/holoviews.html#holoviews.NdOverlay): Multiple elements overlaid (default)\n", + "- [NdLayout](https://holoviews.org/reference_manual/holoviews.html#holoviews.NdLayout): Separate subplots when `subplots=True`\n", + "- **All categories visible**: Simultaneously displayed\n", + "\n", + "### When to use:\n", + "- When you want to compare categories side-by-side\n", + "- When you have a manageable number of categories (typically < 10)\n", + "- When color differentiation is sufficient for your analysis\n", + "- When you need all data visible at once" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "44a01c85", + "metadata": {}, + "outputs": [], + "source": [ + "overlay_plot = penguins.hvplot.scatter(\n", + " x='bill_length_mm',\n", + " y='bill_depth_mm',\n", + " by='species',\n", + " title=\"By: Overlaid Elements\"\n", + ")\n", + "overlay_plot" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2d18719e", + "metadata": {}, + "outputs": [], + "source": [ + "plot_by_subplots = penguins.hvplot.scatter(\n", + " x='bill_length_mm',\n", + " y='bill_depth_mm',\n", + " by='species',\n", + " width=300,\n", + " subplots=True,\n", + ")\n", + "plot_by_subplots.cols(2)" + ] + }, + { + "cell_type": "markdown", + "id": "429174c7", + "metadata": {}, + "source": [ + "### Indexing and Access\n", + "\n", + "Similar to `groupby`, using `by` creates a **HoloViews container object** (NdOverlay or NdLayout) that you can index into. However, the behavior is different because all elements are displayed simultaneously.\n", + "\n", + "**Why indexing works**: The NdOverlay/NdLayout container stores individual plot elements for each category, just like a dictionary mapping category values to plot elements.\n", + "\n", + "**What happens when you index**: You extract a single plot element from the overlay/layout. This gives you just that category's data as a standalone plot element, separate from the others.\n", + "\n", + "**Key difference from groupby**: While `groupby` shows one category at a time with widgets, `by` shows all categories together, but you can still extract individual in the same way as `groupby` objects." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d21ed90c", + "metadata": {}, + "outputs": [], + "source": [ + "# Access specific category: plot['category_value']\n", + "adelie_element = overlay_plot['Adelie'] # Returns just the element for Adelie penguins\n", + "print(f\"Type of 'by' plot: {type(overlay_plot)}\")\n", + "print(f\"Type of specific species element: {type(adelie_element)}\")\n", + "adelie_element" + ] + }, + { + "cell_type": "markdown", + "id": "3fe7048d", + "metadata": {}, + "source": [ + "## `color`/`c`: Vectorized Coloring\n", + "\n", + "The `color` parameter creates **vectorized coloring** within a single plot element, where each data point is colored based on the category value.\n", + "\n", + "### What it creates:\n", + "- **Single plot element**: One unified [Scatter](https://holoviews.org/reference_manual/holoviews.html#holoviews.Scatter), [Curve](https://holoviews.org/reference_manual/holoviews.html#holoviews.Curve), etc.\n", + "- **Vectorized coloring**: Each point colored by category\n", + "- **Cannot be indexed**: Single element, not separable by category\n", + "\n", + "### When to use:\n", + "- When you want the best performance for large datasets\n", + "- When you need smooth, continuous color mapping\n", + "- When you don't need to isolate specific categories" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f54ccbed", + "metadata": {}, + "outputs": [], + "source": [ + "plot_color = penguins.hvplot.scatter(\n", + " x='bill_length_mm',\n", + " y='bill_depth_mm',\n", + " color='species',\n", + " title=\"Color: Vectorized Coloring\"\n", + ")\n", + "plot_color" + ] + }, + { + "cell_type": "markdown", + "id": "60b4c757", + "metadata": {}, + "source": [ + "### Indexing and Access\n", + "\n", + "Unlike `groupby` and `by`, using `color` creates a **single plot element** rather than a container object. This means indexing by category is not possible.\n", + "\n", + "**Why indexing doesn't work**: There's no container structure - just one plot element where the color information is stored as data within the element itself. The categories exist as color mappings, not as separate, accessible plot elements.\n", + "\n", + "**What this means**: All your data points are part of one unified plot object. The categorical information is encoded in the visual properties (colors) rather than the data structure.\n", + "\n", + "**Implications**:\n", + "- You cannot programmatically separate categories\n", + "- Better performance since there's only one plot element to render\n", + "- All data is always visible\n", + "- Ideal when you want aesthetic grouping without interactive separation" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "ab54c88e", + "metadata": {}, + "outputs": [], + "source": [ + "print(f\"Type of 'color' plot: {type(plot_color)}\")\n", + "try:\n", + " adelie_color = plot_color['Adelie'] # This will raise an error.\n", + "except Exception:\n", + " print(\"Error: You cannot index a single element by category!\")" + ] + }, + { + "cell_type": "markdown", + "id": "dc4f9890", + "metadata": {}, + "source": [ + "## Understanding Container Objects vs Single Elements\n", + "\n", + "The key concept underlying these differences is **how HoloViews organizes your data**:\n", + "\n", + "### Container Objects (indexable)\n", + "- **`groupby`** → HoloMap/DynamicMap: `{category: plot_element}`\n", + "- **`by`** → NdOverlay/NdLayout: `{category: plot_element}`\n", + "\n", + "These containers act like dictionaries where each category value maps to a separate plot element. This structure enables indexing with `plot['category_name']`.\n", + "\n", + "### Single Elements (not indexable) \n", + "- **`color`** → Single plot element (Scatter, Curve, etc.)\n", + "\n", + "Here, all data points belong to one plot element. Categories are encoded as visual properties (colors) rather than separate data structures.\n", + "\n", + "This fundamental difference affects not just indexing, but also performance, interactivity, and how you can manipulate the resulting plots.\n", + "\n", + ":::{seealso}\n", + "[Introduction to HoloViews Elements](https://holoviews.org/getting_started/Introduction.html)\n", + ":::" + ] + }, + { + "cell_type": "markdown", + "id": "1626f2c0", + "metadata": {}, + "source": [ + "## Visual Output Comparison\n", + "\n", + "Let's compare all three approaches side by side to see the differences:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a1545149", + "metadata": {}, + "outputs": [], + "source": [ + "import panel as pn\n", + "\n", + "width = 300\n", + "\n", + "groupby_plot = penguins.hvplot.scatter(\n", + " x='bill_length_mm', y='bill_depth_mm',\n", + " groupby='species', title=\"groupby='species'\",\n", + " frame_width=width, widget_location='bottom_right',\n", + " shared_axes=False,\n", + ")\n", + "\n", + "by_plot = penguins.hvplot.scatter(\n", + " x='bill_length_mm', y='bill_depth_mm',\n", + " by='species', title=\"by='species'\",\n", + " frame_width=width,\n", + ")\n", + "\n", + "color_plot = penguins.hvplot.scatter(\n", + " x='bill_length_mm', y='bill_depth_mm',\n", + " color='species', title=\"color='species'\",\n", + " frame_width=width,\n", + ")\n", + "\n", + "pn.Column(pn.Row(groupby_plot, by_plot), color_plot)" + ] + }, + { + "cell_type": "markdown", + "id": "bdcbe3e1", + "metadata": {}, + "source": [ + "### Key Visual Differences:\n", + "\n", + "- **`groupby='species'`** shows only one species at a time with a widget\n", + "- **`by='species'`** shows all species overlaid with different colors and a legend\n", + "- **`color='species'`** looks similar to `by` but is a single plot element\n", + "\n", + "When using `subplots=True` with `by`, you get separate panels:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "3b777d41", + "metadata": {}, + "outputs": [], + "source": [ + "penguins.hvplot.scatter(\n", + " x='bill_length_mm', y='bill_depth_mm',\n", + " by='species', subplots=True,\n", + " width=300, height=250,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "0658c3a1", + "metadata": {}, + "source": [ + "## Advanced: Combining Approaches\n", + "\n", + "You can combine these approaches for more complex visualizations:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "754427cf", + "metadata": {}, + "outputs": [], + "source": [ + "penguins.hvplot.scatter(\n", + " x='bill_length_mm', y='bill_depth_mm',\n", + " groupby='island', color='species',\n", + " width=500, height=400, dynamic=False,\n", + " title=\"Groupby island, colored by species\"\n", + ")\n" + ] + }, + { + "cell_type": "markdown", + "id": "05067653", + "metadata": {}, + "source": [ + "## Summary\n", + "\n", + "| Aspect | `groupby` | `by` | `color`/`c` |\n", + "| ----------------- | ------------------ | ------------------ | ---------------------- |\n", + "| **Holoviews Object** | [HoloMap](https://holoviews.org/reference_manual/holoviews.html#holoviews.HoloMap) / [DynamicMap](https://holoviews.org/reference_manual/holoviews.html#holoviews.DynamicMap) | [NdOverlay](https://holoviews.org/reference_manual/holoviews.html#holoviews.NdOverlay) / [NdLayout](https://holoviews.org/reference_manual/holoviews.html#holoviews.NdLayout) | Single Element |\n", + "| **Interactivity** | Widget-based | Static overlay | Static single plot |\n", + "| **Indexing** | `plot['category']` | `plot['category']` | Not available |\n", + "| **Performance** | Variable | Medium | Best |\n", + "| **Visual** | One at a time | All simultaneous | All simultaneous |\n", + "| **Use case** | Exploration | Comparison | Performance/Aesthetics |\n", + "\n", + "### Choose the approach that best matches your needs:\n", + "\n", + "- **Use `groupby`** for interactive exploration of many categories\n", + "- **Use `by`** for direct comparison of manageable categories \n", + "- **Use `color`** for performance with large datasets or aesthetic coloring\n", + "\n", + ":::{admonition} Further Reading\n", + ":class: seealso\n", + "See the [HoloViews Reference Manual](https://holoviews.org/reference_manual/index.html) for more information on the various objects created by a hvPlot plot.\n", + ":::" + ] + } + ], + "metadata": { + "language_info": { + "name": "python", + "pygments_lexer": "ipython3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/doc/explanation/index.md b/doc/explanation/index.md new file mode 100644 index 000000000..aebb9464f --- /dev/null +++ b/doc/explanation/index.md @@ -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 +``` diff --git a/doc/how_to/explore_with_widgets.ipynb b/doc/how_to/explore_with_widgets.ipynb new file mode 100644 index 000000000..d224ba2c3 --- /dev/null +++ b/doc/how_to/explore_with_widgets.ipynb @@ -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", + "\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 +} diff --git a/doc/how_to/index.md b/doc/how_to/index.md new file mode 100644 index 000000000..2813fb273 --- /dev/null +++ b/doc/how_to/index.md @@ -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 +``` diff --git a/doc/index.md b/doc/index.md index f5607a2fe..0dbd62a80 100644 --- a/doc/index.md +++ b/doc/index.md @@ -434,8 +434,10 @@ align: center Tutorials User Guide +How-To Guides Gallery Reference +Explanation Developer Guide Releases Roadmap diff --git a/doc/ref/api_compatibility/index.md b/doc/ref/api_compatibility/index.md index b4e5636a4..de6992718 100644 --- a/doc/ref/api_compatibility/index.md +++ b/doc/ref/api_compatibility/index.md @@ -7,4 +7,5 @@ This section aims to provide more precise information about the compatibility of :maxdepth: 2 Pandas +Panel Widgets ``` diff --git a/doc/ref/api_compatibility/panel_widgets.ipynb b/doc/ref/api_compatibility/panel_widgets.ipynb new file mode 100644 index 000000000..131125b68 --- /dev/null +++ b/doc/ref/api_compatibility/panel_widgets.ipynb @@ -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 +} diff --git a/doc/ref/plotting_options/data.ipynb b/doc/ref/plotting_options/data.ipynb index 83a2e6272..5e893bf5a 100644 --- a/doc/ref/plotting_options/data.ipynb +++ b/doc/ref/plotting_options/data.ipynb @@ -161,7 +161,7 @@ "(option-groupby)=\n", "## `groupby`\n", "\n", - "The `groupby` option specifies one or more dimensions by which to partition your data into separate groups. This grouping enables the creation of interactive widgets that let users filter or switch between different groups. When `dynamic=True` (the default), each group is rendered interactively as a HoloViews [`DynamicMap`](inv:holoviews#reference/containers/bokeh/DynamicMap), updating on-the-fly; otherwise, with `dynamic=False`, all groups are pre-rendered and returned as a [`HoloMap`](inv:holoviews#reference/containers/bokeh/HoloMap)." + "The `groupby` option specifies one or more dimensions by which to partition your data into separate groups. This grouping enables the creation of interactive widgets that let users filter or switch between different groups. When `dynamic=True` (the default), each group is rendered interactively as a HoloViews [`DynamicMap`](https://holoviews.org/reference_manual/holoviews.html#holoviews.DynamicMap), updating on-the-fly; otherwise, with `dynamic=False`, all groups are pre-rendered and returned as a [`HoloMap`](https://holoviews.org/reference_manual/holoviews.html#holoviews.HoloMap)." ] }, {