diff --git a/doc/explanation/hvplot_backend_support.ipynb b/doc/explanation/hvplot_backend_support.ipynb new file mode 100644 index 000000000..ebc301362 --- /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." + ] + }, + { + "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 Loading and switching plotting extensions](../how_to/load_switch_plotting_extensions.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 +``` diff --git a/doc/how_to/index.md b/doc/how_to/index.md new file mode 100644 index 000000000..7c5739988 --- /dev/null +++ b/doc/how_to/index.md @@ -0,0 +1,12 @@ +# 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 + +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..153402950 --- /dev/null +++ b/doc/how_to/style_plots_by_backend.ipynb @@ -0,0 +1,168 @@ +{ + "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": "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, + "id": "eb44e804", + "metadata": {}, + "outputs": [], + "source": [ + "import hvplot.pandas\n", + "hvplot.extension('matplotlib'\n", + " )\n", + "stocks = hvplot.sampledata.stocks('pandas')\n", + "stocks.head(2)" + ] + }, + { + "cell_type": "markdown", + "id": "36aaaa37-f9c1-49b5-aa19-fdfe8b6bbd3c", + "metadata": {}, + "source": [ + "## Backend-specific styling options for `line` Plots\n", + "\n", + "```{eval-rst}\n", + ".. backend-styling-options:: line\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": [ + "hvplot.output(backend='bokeh')\n", + "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', rot=45)" + ] + }, + { + "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(\n", + " x='date',\n", + " line_dash='dashed',\n", + " title='Dashed Line - Matplotlib (Bokeh compatibility)',\n", + " rot=45\n", + ")\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 +} diff --git a/doc/index.md b/doc/index.md index e868f5cec..5340961fd 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