Create Explorer Tutorial

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
 ```

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": {

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
+}