diff --git a/doc/index.md b/doc/index.md index e868f5cec..b7417273d 100644 --- a/doc/index.md +++ b/doc/index.md @@ -415,8 +415,8 @@ The *Explorer* is a [Panel](https://panel.holoviz.org) web application that can ```python import hvplot.pandas -from bokeh.sampledata.penguins import data as df +df = hvplot.sampledata.penguins("pandas").dropna() hvexplorer = df.hvplot.explorer() hvexplorer ``` diff --git a/doc/ref/api/manual/hvplot.hvPlot.explorer.ipynb b/doc/ref/api/manual/hvplot.hvPlot.explorer.ipynb index df1beeaab..b9c840e8d 100644 --- a/doc/ref/api/manual/hvplot.hvPlot.explorer.ipynb +++ b/doc/ref/api/manual/hvplot.hvPlot.explorer.ipynb @@ -25,7 +25,7 @@ "source": [ "import hvplot.pandas # noqa\n", "\n", - "df = hvplot.sampledata.penguins(\"pandas\")\n", + "df = hvplot.sampledata.penguins(\"pandas\").dropna()\n", "\n", "hvexplorer = df.hvplot.explorer()\n", "# Start: only required for building the site\n", @@ -34,6 +34,76 @@ "# End\n", "hvexplorer" ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Explorer with Xarray data\n", + "\n", + "The explorer also works with Xarray datasets:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import hvplot.xarray # noqa\n", + "\n", + "ds = hvplot.sampledata.air_temperature(\"xarray\")\n", + "\n", + "xr_explorer = ds.hvplot.explorer(x='lon', y='lat')\n", + "xr_explorer" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Exporting from the Explorer\n", + "\n", + "The explorer provides several methods to export your plot configuration:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Get the generated code as a string\n", + "print(\"1. Generated code:\\n\", hvexplorer.code, \"\\n\")\n", + "\n", + "# Get the settings as a dictionary\n", + "print(\"2. Settings dictionary:\\n\", hvexplorer.settings(), \"\\n\")\n", + "\n", + "# Generate code with custom variable name\n", + "print(\"3. Code with custom variable name:\\n\", hvexplorer.plot_code('penguins'))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Using the top-level explorer function\n", + "\n", + "You can also use the top-level `hvplot.explorer()` function:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from hvplot import explorer\n", + "\n", + "# Using the top-level function with pre-configured options\n", + "top_level_explorer = explorer(df, x='flipper_length_mm', y='body_mass_g', by=['species'])\n", + "top_level_explorer" + ] } ], "metadata": { diff --git a/doc/tutorials/explorer_getting_started.ipynb b/doc/tutorials/explorer_getting_started.ipynb new file mode 100644 index 000000000..ecf2fbde7 --- /dev/null +++ b/doc/tutorials/explorer_getting_started.ipynb @@ -0,0 +1,273 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "a14bdc3e", + "metadata": {}, + "source": [ + "# Getting Started with the Explorer\n", + "\n", + "The hvPlot Explorer is a graphical user interface that allows you to quickly create customized plots through an interactive interface. Instead of writing code repeatedly to adjust plot parameters, you can use the Explorer to visually configure your plots and then export the code when you're satisfied with the result.\n", + "\n", + ":::{note}\n", + "The Explorer requires a live Python kernel to be fully interactive. The widgets shown in this documentation are not interactive when viewed on the website.\n", + ":::\n", + "\n", + "## What you'll learn\n", + "\n", + "By the end of this tutorial, you'll know how to:\n", + "\n", + "- Launch the Explorer for different data types\n", + "- Navigate the Explorer interface\n", + "- Create basic plots using the interface\n", + "- Export code from your Explorer session\n", + "\n", + "## Setup\n", + "\n", + "First, let's import hvplot and load some sample data:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "261e37cf", + "metadata": {}, + "outputs": [], + "source": [ + "import hvplot.pandas # noqa: this automatically loads the bokeh extension\n", + "import hvplot.xarray # noqa: for xarray support" + ] + }, + { + "cell_type": "markdown", + "id": "367a10d3", + "metadata": {}, + "source": [ + "## Launching the Explorer\n", + "\n", + "The Explorer can be launched in two ways:\n", + "\n", + "1. **Via the top-level function**: `hvplot.explorer(data)`\n", + "2. **Via the data accessor method**: `data.hvplot.explorer()`\n", + "\n", + "Let's start with a simple dataset - the penguins data:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "36f7acff", + "metadata": {}, + "outputs": [], + "source": [ + "df = hvplot.sampledata.penguins(\"pandas\").dropna()\n", + "df.head(3)" + ] + }, + { + "cell_type": "markdown", + "id": "4c864ff0", + "metadata": {}, + "source": [ + "Now let's launch the Explorer using the data accessor method:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "33c476f3", + "metadata": {}, + "outputs": [], + "source": [ + "explorer = df.hvplot.explorer()\n", + "explorer" + ] + }, + { + "cell_type": "markdown", + "id": "9f61c206", + "metadata": {}, + "source": [ + "## Understanding the Interface\n", + "\n", + "The Explorer interface consists of several key areas:\n", + "\n", + "- **Left panel**: Controls and settings for customizing your plot\n", + "- **Right panel**: Live preview of your plot\n", + "- **Top section**: Status bar with options like \"live update\"\n", + "- **Bottom section**: Widgets, error messages and alerts (if any)\n", + "\n", + "### Key Controls\n", + "\n", + "The left panel contains various sections:\n", + "\n", + "- **Fields**: Select different chart types (scatter, line, bar, etc.), choose columns for x, y, color, size, etc., select `By` or `Groupby` options\n", + "- **Axis, Labels, Style**: Customize colors, sizes, and visual appearance\n", + "- **Operations**: Select aggregation options like `rasterize`, `datashade`, `dynspread` etc.\n", + "- **Colormapping**: Control color options, like selecting a colormap, `clim`, `cnorm` and showing a colorbar if available.\n", + "- **Geographic**: Select geographic options for geo-type plots\n", + "- **Advanced**: Add additional plots options via the Holoviews `.opts()` method.\n", + "\n", + "Try changing some of these settings to see how they affect the plot preview.\n", + "\n", + "## Creating Your First Plot\n", + "\n", + "Let's create a simple scatter plot by configuring some basic settings:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b030abca", + "metadata": {}, + "outputs": [], + "source": [ + "scatter_explorer = df.hvplot.explorer(\n", + " x='bill_length_mm',\n", + " y='bill_depth_mm',\n", + " by=['species'],\n", + " title='Penguin Bill Measurements'\n", + ")\n", + "scatter_explorer" + ] + }, + { + "cell_type": "markdown", + "id": "7538aa56-53b2-4e1a-b650-b968855fe344", + "metadata": {}, + "source": [ + "Even after creating your explorer plot with some pre-configured settings, you can still interact with and modify the parameters of the plot!" + ] + }, + { + "cell_type": "markdown", + "id": "a177c259", + "metadata": {}, + "source": [ + "## Exporting Your Work\n", + "\n", + "One of the most powerful features of the Explorer is the ability to export your plot configuration as code. This lets you recreate your plot later or use it in scripts. You can access the generated code in several ways:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0b296aab", + "metadata": {}, + "outputs": [], + "source": [ + "# Get the code as a string\n", + "code = scatter_explorer.code\n", + "print(\"Generated code: \\n\", code)" + ] + }, + { + "cell_type": "markdown", + "id": "efe8b248", + "metadata": {}, + "source": [ + "The generated code can be executed directly to recreate your plot:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "22de5364", + "metadata": {}, + "outputs": [], + "source": [ + "recreated_plot = scatter_explorer.hvplot()\n", + "recreated_plot" + ] + }, + { + "cell_type": "markdown", + "id": "a2aabfc9", + "metadata": {}, + "source": [ + "You can also get the settings as a dictionary to use with the regular hvplot API:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f0e5d221", + "metadata": {}, + "outputs": [], + "source": [ + "settings = scatter_explorer.settings()\n", + "settings" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e160a42c", + "metadata": {}, + "outputs": [], + "source": [ + "# Use the settings with regular hvplot\n", + "df.hvplot(**settings)" + ] + }, + { + "cell_type": "markdown", + "id": "0e871dbf", + "metadata": {}, + "source": [ + "## Working with Different Data Types\n", + "\n", + "The Explorer works with different data types. Let's try it with an xarray Dataset:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "164a4336", + "metadata": {}, + "outputs": [], + "source": [ + "air_temp = hvplot.sampledata.air_temperature(\"xarray\")\n", + "air_temp" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a9421690", + "metadata": {}, + "outputs": [], + "source": [ + "xr_explorer = air_temp.hvplot.explorer(x='lon', y='lat')\n", + "xr_explorer" + ] + }, + { + "cell_type": "markdown", + "id": "24ab7ca3", + "metadata": {}, + "source": [ + "Notice how the Explorer adapts to show options relevant to gridded data, including different plot types like image, quadmesh and contour plots.\n", + "\n", + ":::{admonition} Next Steps\n", + ":class: seealso\n", + "\n", + "Now that you know the basics of the Explorer, you can:\n", + "\n", + "- Experiment with different plot types and settings\n", + "- Try the Explorer with your own datasets\n", + "- Learn about advanced features in the [Exploring Data Interactively](explorer_interactive.ipynb) tutorial\n", + "- Check out the [Explorer API reference](../ref/api/manual/hvplot.hvPlot.explorer.ipynb) for all available options\n", + ":::" + ] + } + ], + "metadata": { + "language_info": { + "name": "python", + "pygments_lexer": "ipython3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/doc/tutorials/explorer_interactive.ipynb b/doc/tutorials/explorer_interactive.ipynb new file mode 100644 index 000000000..82fb2a800 --- /dev/null +++ b/doc/tutorials/explorer_interactive.ipynb @@ -0,0 +1,390 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "f8fa3747", + "metadata": {}, + "source": [ + "# Exploring Data Interactively\n", + "\n", + "The hvPlot Explorer shines when you need to iteratively explore your data to discover patterns and create meaningful visualizations. This tutorial shows you how to use the Explorer for real data exploration workflows.\n", + "\n", + "## What you'll learn\n", + "\n", + "In this tutorial, you'll discover how to:\n", + "\n", + "- Use the Explorer to investigate data relationships\n", + "- Iterate through different visualization approaches\n", + "- Leverage grouping and faceting for deeper insights\n", + "- Work with geographic data\n", + "- Manage and record your exploration sessions\n", + "\n", + ":::{note}\n", + "The Explorer requires a live Python kernel to be fully interactive. The widgets and interactivity described in this documentation are not interactive when viewed on the website.\n", + ":::\n", + "\n", + "## Setup\n", + "\n", + "Let's start by importing the necessary libraries and loading our data:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "76c52f3c", + "metadata": {}, + "outputs": [], + "source": [ + "import hvplot.pandas # noqa\n", + "import hvplot.xarray # noqa" + ] + }, + { + "cell_type": "markdown", + "id": "f5688555", + "metadata": {}, + "source": [ + "## Exploring Tabular Data\n", + "\n", + "Let's begin with the penguins dataset and explore the relationships between different measurements:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0e50bd36", + "metadata": {}, + "outputs": [], + "source": [ + "df = hvplot.sampledata.penguins(\"pandas\").dropna()\n", + "df.info()" + ] + }, + { + "cell_type": "markdown", + "id": "df926d27", + "metadata": {}, + "source": [ + "### Starting Your Exploration\n", + "\n", + "Let's launch the Explorer and begin investigating the data. We'll start with a basic scatter plot to look for patterns:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "60159126", + "metadata": {}, + "outputs": [], + "source": [ + "explorer = df.hvplot.explorer()\n", + "explorer" + ] + }, + { + "cell_type": "markdown", + "id": "6167c340", + "metadata": {}, + "source": [ + "While you would normally use the interface controls, for this tutorial we'll configure the plot programmatically to demonstrate the workflow:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "4b1ede81", + "metadata": {}, + "outputs": [], + "source": [ + "explorer.param.update(\n", + " x='bill_length_mm',\n", + " y_multi=['bill_depth_mm'],\n", + ")\n", + "explorer.labels.title = 'Penguin Bill Measurements: Bill Depth'" + ] + }, + { + "cell_type": "markdown", + "id": "a8c64088", + "metadata": {}, + "source": [ + "Data exploration is iterative. Let's change the y-axis to show the Body Mass:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "676dbd46", + "metadata": {}, + "outputs": [], + "source": [ + "explorer.param.update(y_multi=['body_mass_g'])\n", + "explorer.labels.title = 'Penguin Measurements: Body Mass'" + ] + }, + { + "cell_type": "markdown", + "id": "7d066c83", + "metadata": {}, + "source": [ + "The `by` parameter is powerful for comparing groups. Let's explore how penguin measurements vary by species:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "84aeaf9f", + "metadata": {}, + "outputs": [], + "source": [ + "explorer.param.update( by=['species'])\n", + "explorer.labels.title = 'Bill Measurements by Species'" + ] + }, + { + "cell_type": "markdown", + "id": "70bf1b9f", + "metadata": {}, + "source": [ + "### Recording Your Findings\n", + "\n", + "As you explore, you'll want to save interesting configurations. Here's how to capture and reuse your work:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "941796fe", + "metadata": {}, + "outputs": [], + "source": [ + "plot_code = explorer.code\n", + "print(\"Code to recreate this plot:\\n\", plot_code)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a6f7a341", + "metadata": {}, + "outputs": [], + "source": [ + "# Show plot\n", + "plot_obj = explorer.hvplot()\n", + "plot_obj" + ] + }, + { + "cell_type": "markdown", + "id": "084a41ae", + "metadata": {}, + "source": [ + "## Exploring Gridded Data\n", + "\n", + "The Explorer is also excellent for exploring gridded datasets like climate data. Let's work with air temperature data:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "bc665291", + "metadata": {}, + "outputs": [], + "source": [ + "air_temp = hvplot.sampledata.air_temperature(\"xarray\")\n", + "air_temp" + ] + }, + { + "cell_type": "markdown", + "id": "fe7552f8", + "metadata": {}, + "source": [ + "### Spatial Visualization\n", + "\n", + "Let's explore the spatial patterns in the temperature data:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "613f1b74", + "metadata": {}, + "outputs": [], + "source": [ + "grid_explorer = air_temp.hvplot.explorer(x='lon', y='lat')\n", + "grid_explorer" + ] + }, + { + "cell_type": "markdown", + "id": "cd96b009", + "metadata": {}, + "source": [ + "Notice how the Explorer automatically detects that this is gridded data and offers appropriate plot types like image and contour plots." + ] + }, + { + "cell_type": "markdown", + "id": "d742d11d", + "metadata": {}, + "source": [ + "## Geographic Data Exploration\n", + "\n", + "When working with geographic data, the Explorer can leverage geographic projections and map tiles:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7206c14e", + "metadata": {}, + "outputs": [], + "source": [ + "geo_explorer = air_temp.hvplot.explorer(x='lon', y='lat', geo=True)\n", + "\n", + "geo_explorer.geographic.param.update(\n", + " crs='PlateCarree',\n", + " tiles='CartoDark',\n", + " global_extent=False\n", + ")\n", + "\n", + "geo_explorer" + ] + }, + { + "cell_type": "markdown", + "id": "6a17f20d-483b-4096-b23c-9e5722b0e01b", + "metadata": {}, + "source": [ + "Click on the `Geographic` button to see the 'Tiles' and 'Crs' options updated\n", + "\n", + ":::{warning}\n", + "Using `geo=True` requires the installation of [GeoViews](https://github.com/holoviz/geoviews)\n", + ":::" + ] + }, + { + "cell_type": "markdown", + "id": "dc0cf813", + "metadata": {}, + "source": [ + "## Advanced Exploration Techniques\n", + "\n", + "### Combining Multiple Variables\n", + "\n", + "Let's go back to the penguins data and explore multiple variables simultaneously:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c6b655ea-cf37-4721-9b25-88a31d1de544", + "metadata": {}, + "outputs": [], + "source": [ + "multi_explorer = df.hvplot.explorer()\n", + "multi_explorer" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "89855dbd", + "metadata": {}, + "outputs": [], + "source": [ + "multi_explorer.param.update(\n", + " x='flipper_length_mm',\n", + " y_multi=['body_mass_g'],\n", + " by=['species'],\n", + " groupby=['sex'],\n", + ")\n", + "multi_explorer.labels.title = 'Multi-dimensional Penguin Analysis'" + ] + }, + { + "cell_type": "markdown", + "id": "d442dfbf", + "metadata": {}, + "source": [ + "### Exploring Distributions\n", + "\n", + "The Explorer supports various plot types. Let's explore data distributions:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "37f4eb87", + "metadata": {}, + "outputs": [], + "source": [ + "dist_explorer = df.hvplot.explorer(kind='hist')\n", + "dist_explorer" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "8a195ec7-14d1-42ac-85ad-6b495a8894ba", + "metadata": {}, + "outputs": [], + "source": [ + "dist_explorer.param.update(\n", + " y_multi=['body_mass_g'],\n", + " by=['species'],\n", + ")\n", + "dist_explorer.labels.title = 'Body Mass Distribution by Species'" + ] + }, + { + "cell_type": "markdown", + "id": "d7948ec1-b165-40b9-9544-3b4fbbc3c64b", + "metadata": {}, + "source": [ + "## Best Practices for Data Exploration\n", + "\n", + "1. Start Simple, Add Complexity. Begin with basic plots and gradually add dimensions (color, size, grouping, etc).\n", + "\n", + "2. Record Interesting Findings.\n", + "\n", + "3. Experiment with Different Plot Types. Different plot types reveal different aspects of your data. The Explorer makes it easy to switch between them.\n", + "\n", + "4. Use the Explorer as a Learning Tool. The generated code helps you learn the hvPlot API. Study the code output to understand how to create plots programmatically.\n", + "\n", + "## Workflow Integration\n", + "\n", + "The Explorer fits naturally into data science workflows:\n", + "\n", + "1. **Initial exploration**: Use the Explorer to understand your data\n", + "2. **Hypothesis formation**: Identify patterns that suggest relationships\n", + "3. **Focused analysis**: Export promising configurations for further analysis\n", + "4. **Presentation**: Clean up and refine plots for reports\n", + "\n", + "## Conclusion\n", + "\n", + "The hvPlot Explorer accelerates data exploration by:\n", + "\n", + "- Eliminating the code-run-adjust cycle\n", + "- Making it easy to try different visualizations\n", + "- Capturing your work for reproducible analysis\n", + "- Teaching you the hvPlot API through generated code\n", + "\n", + "Use the Explorer whenever you're starting to work with a new dataset or when you need to quickly investigate patterns and relationships in your data.\n", + "\n", + ":::{seealso}\n", + "[Explorer API reference](../ref/api/manual/hvplot.hvPlot.explorer.ipynb)\n", + ":::" + ] + } + ], + "metadata": { + "language_info": { + "name": "python", + "pygments_lexer": "ipython3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/doc/tutorials/index.md b/doc/tutorials/index.md index 4572f7546..81147c632 100644 --- a/doc/tutorials/index.md +++ b/doc/tutorials/index.md @@ -21,6 +21,20 @@ Get started with hvPlot using this quick tutorial. Get started with hvPlot as a Pandas user. ::: +:::{grid-item-card} {octicon}`telescope;2.5em;sd-mr-1 sd-animate-grow50` Explorer Basics +:link: explorer_getting_started +:link-type: doc + +Learn to use the interactive Explorer interface. +::: + +:::{grid-item-card} {octicon}`graph;2.5em;sd-mr-1 sd-animate-grow50` Interactive Exploration +:link: explorer_interactive +:link-type: doc + +Master data exploration workflows with the Explorer. +::: + :::: ## External tutorials @@ -43,5 +57,7 @@ Explore all the HoloViz tools in this comprehensive tutorial. Getting Started Using hvPlot as a Pandas user +Explorer Basics +Interactive Exploration HoloViz Tutorial ``` diff --git a/hvplot/plotting/core.py b/hvplot/plotting/core.py index 298556d22..c5c2df859 100644 --- a/hvplot/plotting/core.py +++ b/hvplot/plotting/core.py @@ -129,7 +129,7 @@ def explorer(self, x=None, y=None, **kwds): """ The `explorer` plot allows you to interactively explore your data. - Reference: https://hvplot.holoviz.org/user_guide/Explorer.html + Reference: https://hvplot.holoviz.org/tutorials/explorer_getting_started.html Parameters ---------- diff --git a/hvplot/ui.py b/hvplot/ui.py index b1024cf5e..781c3d441 100644 --- a/hvplot/ui.py +++ b/hvplot/ui.py @@ -58,7 +58,7 @@ def explorer(data, **kwargs): This function returns an interactive Panel component that enable you to quickly change the settings of your plot via widgets. - Reference: https://hvplot.holoviz.org/user_guide/Explorer.html + Reference: https://hvplot.holoviz.org/tutorials/explorer_getting_started.html Parameters ----------