From 1917a58f5577897ca2d7ee185ec4433280309335 Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Mon, 4 Aug 2025 17:14:39 +0100 Subject: [PATCH 1/7] Add how-to section --- doc/how_to/index.md | 10 ++++++++++ doc/index.md | 1 + 2 files changed, 11 insertions(+) create mode 100644 doc/how_to/index.md diff --git a/doc/how_to/index.md b/doc/how_to/index.md new file mode 100644 index 000000000..f1c886fff --- /dev/null +++ b/doc/how_to/index.md @@ -0,0 +1,10 @@ +# 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 + +``` diff --git a/doc/index.md b/doc/index.md index e868f5cec..c1fbf0941 100644 --- a/doc/index.md +++ b/doc/index.md @@ -434,6 +434,7 @@ align: center Tutorials User Guide +How-To Guides Gallery Reference Developer Guide From 16f84fc99dbb6ebc6e675181ca9e659636f6691b Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Thu, 7 Aug 2025 18:00:05 +0100 Subject: [PATCH 2/7] add how to guides for plotting extensions --- doc/how_to/index.md | 2 + .../load_switch_plotting_extensions.ipynb | 138 +++++++++++++++++ doc/how_to/style_plots_by_backend.ipynb | 146 ++++++++++++++++++ 3 files changed, 286 insertions(+) create mode 100644 doc/how_to/load_switch_plotting_extensions.ipynb create mode 100644 doc/how_to/style_plots_by_backend.ipynb diff --git a/doc/how_to/index.md b/doc/how_to/index.md index f1c886fff..7c5739988 100644 --- a/doc/how_to/index.md +++ b/doc/how_to/index.md @@ -7,4 +7,6 @@ How-to guides are practical, problem-oriented instructions that help you accompl :hidden: :maxdepth: 2 +load_switch_plotting_extensions +style_plots_by_backend ``` diff --git a/doc/how_to/load_switch_plotting_extensions.ipynb b/doc/how_to/load_switch_plotting_extensions.ipynb new file mode 100644 index 000000000..408f21fe6 --- /dev/null +++ b/doc/how_to/load_switch_plotting_extensions.ipynb @@ -0,0 +1,138 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "98c86d5c", + "metadata": {}, + "source": [ + "# How to Load and Switch Plotting Extensions in hvPlot\n", + "\n", + "This guide shows how to load different plotting extensions in hvPlot and switch between them. hvPlot supports [Bokeh](https://docs.bokeh.org/) and [Matplotlib](https://matplotlib.org/) as backends for rendering plots." + ] + }, + { + "cell_type": "markdown", + "id": "108ed881", + "metadata": {}, + "source": [ + "## Load hvPlot and a Sample Dataset\n", + "\n", + "We'll use the `penguins` dataset from the `hvsampledata` module for all examples." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "563a019f", + "metadata": {}, + "outputs": [], + "source": [ + "import hvplot.pandas\n", + "penguins = hvplot.sampledata.penguins('pandas').dropna()" + ] + }, + { + "cell_type": "markdown", + "id": "3bc21afb", + "metadata": {}, + "source": [ + "## Load Matplotlib Extension\n", + "\n", + "By default, importing an accessor like `hvplot.pandas` loads the Bokeh extension. To use Matplotlib, call `hvplot.extension('matplotlib')`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "6b0d85de", + "metadata": {}, + "outputs": [], + "source": [ + "hvplot.extension('matplotlib') # Loads Matplotlib (active) extension." + ] + }, + { + "cell_type": "markdown", + "id": "8ac4fdc9", + "metadata": {}, + "source": [ + "## Plot with the Active Extension\n", + "\n", + "The following plot uses the currently active extension (Matplotlib):" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "713ebc6f", + "metadata": {}, + "outputs": [], + "source": [ + "penguins.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', c='species', title='Penguins Bill Dimensions')" + ] + }, + { + "cell_type": "markdown", + "id": "8aaf2d90", + "metadata": {}, + "source": [ + "## Switch Plotting Extension with `output()`\n", + "\n", + "You can switch the active backend using `hvplot.output(backend=...)`. Below, we switch between Matplotlib and Bokeh.\n", + "\n", + ":::{tip}\n", + "The `extension` function could also be used to switch the plotting extension. You should however prefer `output` as any call to `extension` actually internally loads code in the output of the cell where it is executed, which can significantly increase the notebook size if `extension` is called in multiple cells.\n", + ":::" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c30e2d57", + "metadata": {}, + "outputs": [], + "source": [ + "penguins.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', c='species', title='Penguins Bill Dimensions (Matplotlib)')" + ] + }, + { + "cell_type": "markdown", + "id": "06625de1", + "metadata": {}, + "source": [ + "Switching to Bokeh is as simple as calling `hvplot.output(backend='bokeh')`:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "6873b401", + "metadata": {}, + "outputs": [], + "source": [ + "hvplot.output(backend='bokeh')\n", + "penguins.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', c='species', title='Penguins Bill Dimensions (Bokeh)')" + ] + }, + { + "cell_type": "markdown", + "id": "80d0ad0b", + "metadata": {}, + "source": [ + "You can load multiple plotting extensions in hvPlot and switch between them using `hvplot.output()`. This allows you to choose the best backend for your visualization needs.\n", + "\n", + ":::{seealso}\n", + "[Styling plots with backend specific option](./style_plots_by_backend.ipynb)\n", + ":::" + ] + } + ], + "metadata": { + "language_info": { + "name": "python", + "pygments_lexer": "ipython3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/doc/how_to/style_plots_by_backend.ipynb b/doc/how_to/style_plots_by_backend.ipynb new file mode 100644 index 000000000..e7fe9ec8d --- /dev/null +++ b/doc/how_to/style_plots_by_backend.ipynb @@ -0,0 +1,146 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "c08e6804", + "metadata": {}, + "source": [ + "# How to Style Plots by Backend in hvPlot\n", + "\n", + "This guide shows how to apply styling options to hvPlot visualizations, depending on the active backend (Bokeh or Matplotlib)." + ] + }, + { + "cell_type": "markdown", + "id": "88d73acc", + "metadata": {}, + "source": [ + "## Load hvPlot and the Penguins Dataset\n", + "\n", + "We'll use the `stocks` dataset from the `hvsampledata` module for all examples." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "eb44e804", + "metadata": {}, + "outputs": [], + "source": [ + "import hvplot.pandas\n", + "stocks = hvplot.sampledata.stocks('pandas')\n", + "\n", + "stocks.head(2)" + ] + }, + { + "cell_type": "markdown", + "id": "36aaaa37-f9c1-49b5-aa19-fdfe8b6bbd3c", + "metadata": {}, + "source": [ + "## Backend-specific styling options\n", + "\n", + "```{eval-rst}\n", + ".. backend-styling-options:: bar\n", + "```" + ] + }, + { + "cell_type": "markdown", + "id": "5a340106", + "metadata": {}, + "source": [ + "## Style Plots with Bokeh Options\n", + "\n", + "By default, hvPlot uses Bokeh as the backend. You can use Bokeh-specific styling options, such as `line_dash`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "ce95554c", + "metadata": {}, + "outputs": [], + "source": [ + "stocks.hvplot.line(x='date', line_dash='dashed')" + ] + }, + { + "cell_type": "markdown", + "id": "2746150c", + "metadata": {}, + "source": [ + "## Style Plots with Matplotlib Options\n", + "\n", + "When using Matplotlib as the backend, use Matplotlib-specific options, such as `linestyle`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a5b92dcd", + "metadata": {}, + "outputs": [], + "source": [ + "hvplot.output(backend='matplotlib')\n", + "stocks.hvplot.line(x='date', linestyle='dashed')" + ] + }, + { + "cell_type": "markdown", + "id": "b2c8c515", + "metadata": {}, + "source": [ + "## Use Bokeh Compatibility Mode with Matplotlib\n", + "\n", + "You can use Bokeh-style options with Matplotlib by enabling compatibility mode. This is useful for reusing code or notebooks originally written for Bokeh." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a2b619a3", + "metadata": {}, + "outputs": [], + "source": [ + "hvplot.extension('matplotlib', compatibility='bokeh')\n", + "stocks_line = stocks.hvplot.line(x='date', line_dash='dashed', title='Matplotlib (Bokeh compatibility): Dashed Line')\n", + "stocks_line" + ] + }, + { + "cell_type": "markdown", + "id": "45656359", + "metadata": {}, + "source": [ + "You can inspect the options applied to the plot object to see how Bokeh options are mapped to Matplotlib options:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "23261e95", + "metadata": {}, + "outputs": [], + "source": [ + "stocks_line.opts.info()" + ] + }, + { + "cell_type": "markdown", + "id": "5f6b8b46", + "metadata": {}, + "source": [ + "Use backend-specific styling options for hvPlot visualizations, or enable compatibility mode to reuse Bokeh options with Matplotlib." + ] + } + ], + "metadata": { + "language_info": { + "name": "python", + "pygments_lexer": "ipython3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} From e8580c9627fd9a7083e48f84711c4079b23f898e Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Thu, 7 Aug 2025 18:17:01 +0100 Subject: [PATCH 3/7] hide warning cell --- doc/how_to/style_plots_by_backend.ipynb | 28 ++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/doc/how_to/style_plots_by_backend.ipynb b/doc/how_to/style_plots_by_backend.ipynb index e7fe9ec8d..215d51e80 100644 --- a/doc/how_to/style_plots_by_backend.ipynb +++ b/doc/how_to/style_plots_by_backend.ipynb @@ -20,6 +20,21 @@ "We'll use the `stocks` dataset from the `hvsampledata` module for all examples." ] }, + { + "cell_type": "code", + "execution_count": null, + "id": "67ad8f16-a89f-481e-902e-da69cc29c59c", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "import warnings\n", + "warnings.filterwarnings(\"ignore\", message=\"linestyle is redundantly defined\")" + ] + }, { "cell_type": "code", "execution_count": null, @@ -28,8 +43,9 @@ "outputs": [], "source": [ "import hvplot.pandas\n", + "hvplot.extension('matplotlib'\n", + " )\n", "stocks = hvplot.sampledata.stocks('pandas')\n", - "\n", "stocks.head(2)" ] }, @@ -62,6 +78,7 @@ "metadata": {}, "outputs": [], "source": [ + "hvplot.output(backend='bokeh')\n", "stocks.hvplot.line(x='date', line_dash='dashed')" ] }, @@ -83,7 +100,7 @@ "outputs": [], "source": [ "hvplot.output(backend='matplotlib')\n", - "stocks.hvplot.line(x='date', linestyle='dashed')" + "stocks.hvplot.line(x='date', linestyle='dashed', rot=45)" ] }, { @@ -104,7 +121,12 @@ "outputs": [], "source": [ "hvplot.extension('matplotlib', compatibility='bokeh')\n", - "stocks_line = stocks.hvplot.line(x='date', line_dash='dashed', title='Matplotlib (Bokeh compatibility): Dashed Line')\n", + "stocks_line = stocks.hvplot.line(\n", + " x='date',\n", + " line_dash='dashed',\n", + " title='Dashed Line - Matplotlib (Bokeh compatibility)',\n", + " rot=45\n", + ")\n", "stocks_line" ] }, From 93a09c93f274231f24928e265599feb45439fc2a Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Thu, 7 Aug 2025 18:44:42 +0100 Subject: [PATCH 4/7] add explanation section --- doc/explanation/hvplot_backend_support.ipynb | 73 ++++++++++++++++++++ doc/explanation/index.md | 11 +++ 2 files changed, 84 insertions(+) create mode 100644 doc/explanation/hvplot_backend_support.ipynb create mode 100644 doc/explanation/index.md diff --git a/doc/explanation/hvplot_backend_support.ipynb b/doc/explanation/hvplot_backend_support.ipynb new file mode 100644 index 000000000..4256f2141 --- /dev/null +++ b/doc/explanation/hvplot_backend_support.ipynb @@ -0,0 +1,73 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "360bd599", + "metadata": {}, + "source": [ + "# How hvPlot Supports Multiple Plotting Backends\n", + "\n", + "hvPlot provides a unified API for creating interactive visualizations using different plotting libraries, including [Bokeh](https://docs.bokeh.org), [Matplotlib](https://matplotlib.org/), and [Plotly](https://plotly.com/). This flexibility is made possible by its integration with [HoloViews](https://holoviews.org/), which acts as an abstraction layer for rendering plots." + ] + }, + { + "cell_type": "markdown", + "id": "f27d8593", + "metadata": {}, + "source": [ + "## hvPlot Architecture\n", + "\n", + "When you use hvPlot (e.g. `df.hvplot.line()`), hvPlot creates a HoloViews object that can be rendered by any supported backend. The choice of backend is controlled by the `extension()` and `output()` functions. See the [How-to guide on loading and switching plotting extensions](../how_to/load_switch_plotting_extensions.ipynb) for practical usage." + ] + }, + { + "cell_type": "markdown", + "id": "fcbd6dcc", + "metadata": {}, + "source": [ + "## Switching Backends\n", + "\n", + "You can switch between backends (e.g., Bokeh and Matplotlib) at any point in your notebook using `hvplot.output(backend=...)`. This allows you to reuse the same plotting code with different visual styles and interactive capabilities. For step-by-step instructions, see the [How-to guide on styling plots by backend](../how_to/style_plots_by_backend.ipynb)." + ] + }, + { + "cell_type": "markdown", + "id": "75356549", + "metadata": {}, + "source": [ + "## Styling and Compatibility Mode\n", + "\n", + "Each backend supports its own set of styling options. For example, Bokeh uses `line_dash`, while Matplotlib uses `linestyle`. hvPlot offers a compatibility mode that lets you use Bokeh-style options with Matplotlib, making it easier to reuse code across backends. Learn more in the [How-to guide on styling plots by backend](../how_to/style_plots_by_backend.ipynb)." + ] + }, + { + "cell_type": "markdown", + "id": "f3d4b164-7bcc-4fd2-ac83-f3a47274bf67", + "metadata": {}, + "source": [ + "## Limitations and Best Practices\n", + "\n", + "Not all options are supported across all backends, and some advanced features may only be available in specific libraries. For best results, use the backend-specific options for advanced customization, and refer to the [reference documentation](../ref/plotting_options/index.md) for details on available options.\n", + "\n", + "hvPlot's backend flexibility allows you to choose the best visualization library for your needs, while keeping your plotting code consistent and reusable.\n", + "\n", + ":::{admonition} Suggested Readings\n", + ":class: seealso\n", + "[Loading and switching plotting extensions](../how_to/load_switch_plotting_extensions.ipynb)\n", + "\n", + "[Styling plots by backend](../how_to/style_plots_by_backend.ipynb)\n", + "\n", + "[Plotting Options](../ref/plotting_options/index.md)\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..e9ca5f9cb --- /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 + +hvplot_backend_support +``` From 3e6e0677a6effdf66e3bfc30fc8d9ba04794ad33 Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Thu, 7 Aug 2025 18:45:15 +0100 Subject: [PATCH 5/7] meh --- doc/how_to/style_plots_by_backend.ipynb | 2 +- doc/index.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/how_to/style_plots_by_backend.ipynb b/doc/how_to/style_plots_by_backend.ipynb index 215d51e80..a395da799 100644 --- a/doc/how_to/style_plots_by_backend.ipynb +++ b/doc/how_to/style_plots_by_backend.ipynb @@ -57,7 +57,7 @@ "## Backend-specific styling options\n", "\n", "```{eval-rst}\n", - ".. backend-styling-options:: bar\n", + ".. backend-styling-options:: line\n", "```" ] }, diff --git a/doc/index.md b/doc/index.md index c1fbf0941..5340961fd 100644 --- a/doc/index.md +++ b/doc/index.md @@ -437,6 +437,7 @@ User Guide How-To Guides Gallery Reference +Explanation Developer Guide Releases Roadmap From 7698c7ef418b307b13fd2897a01a9f69f261033e Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Thu, 7 Aug 2025 18:50:48 +0100 Subject: [PATCH 6/7] small update --- doc/explanation/hvplot_backend_support.ipynb | 2 +- doc/how_to/style_plots_by_backend.ipynb | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/explanation/hvplot_backend_support.ipynb b/doc/explanation/hvplot_backend_support.ipynb index 4256f2141..185d12050 100644 --- a/doc/explanation/hvplot_backend_support.ipynb +++ b/doc/explanation/hvplot_backend_support.ipynb @@ -17,7 +17,7 @@ "source": [ "## hvPlot Architecture\n", "\n", - "When you use hvPlot (e.g. `df.hvplot.line()`), hvPlot creates a HoloViews object that can be rendered by any supported backend. The choice of backend is controlled by the `extension()` and `output()` functions. See the [How-to guide on loading and switching plotting extensions](../how_to/load_switch_plotting_extensions.ipynb) for practical usage." + "When you use hvPlot (e.g. `df.hvplot.line()`), hvPlot creates a HoloViews object that can be rendered by any supported backend. The choice of backend is controlled by the `extension()` and `output()` functions." ] }, { diff --git a/doc/how_to/style_plots_by_backend.ipynb b/doc/how_to/style_plots_by_backend.ipynb index a395da799..153402950 100644 --- a/doc/how_to/style_plots_by_backend.ipynb +++ b/doc/how_to/style_plots_by_backend.ipynb @@ -54,7 +54,7 @@ "id": "36aaaa37-f9c1-49b5-aa19-fdfe8b6bbd3c", "metadata": {}, "source": [ - "## Backend-specific styling options\n", + "## Backend-specific styling options for `line` Plots\n", "\n", "```{eval-rst}\n", ".. backend-styling-options:: line\n", From d1ccaa62f3dac5b54097c9f0ccf9f5bbbe2dc735 Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Thu, 7 Aug 2025 18:54:22 +0100 Subject: [PATCH 7/7] small update2 --- doc/explanation/hvplot_backend_support.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/explanation/hvplot_backend_support.ipynb b/doc/explanation/hvplot_backend_support.ipynb index 185d12050..ebc301362 100644 --- a/doc/explanation/hvplot_backend_support.ipynb +++ b/doc/explanation/hvplot_backend_support.ipynb @@ -27,7 +27,7 @@ "source": [ "## Switching Backends\n", "\n", - "You can switch between backends (e.g., Bokeh and Matplotlib) at any point in your notebook using `hvplot.output(backend=...)`. This allows you to reuse the same plotting code with different visual styles and interactive capabilities. For step-by-step instructions, see the [How-to guide on styling plots by backend](../how_to/style_plots_by_backend.ipynb)." + "You can switch between backends (e.g., Bokeh and Matplotlib) at any point in your notebook using `hvplot.output(backend=...)`. This allows you to reuse the same plotting code with different visual styles and interactive capabilities. For step-by-step instructions, see the [How-to guide on Loading and switching plotting extensions](../how_to/load_switch_plotting_extensions.ipynb)." ] }, {