{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "hvPlot is written to work well inside a Jupyter notebook, from the interactive Python command prompt, or inside a Python batch script. In this user guide we will discover how to use hvPlot to view plots in each of these cases and how to save the plots to a separate file.\n",
    "\n",
    "## Notebook\n",
    "\n",
    "In a Jupyter notebook, hvPlot will return HoloViews objects that display themselves using Bokeh, as long as the extension has been loaded. The easiest way of loading the extension is to import one of the plotting extensions such as `hvplot.pandas`:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\" role=\"alert\">\n",
    "  If you are using JupyterLab, run <code>jupyter labextension install @pyviz/jupyterlab_pyviz</code> before starting jupyter lab.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot\n",
    "import hvplot.pandas  # noqa"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we will load some of the sample data and then compose the HoloViews objects into a layout:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from hvplot.sample_data import airline_flights, us_crime\n",
    "\n",
    "violent_crime = us_crime.hvplot(x='Year', y='Violent Crime rate', width=400)\n",
    "burglaries    = us_crime.hvplot(x='Year', y='Burglary rate', width=400)\n",
    "\n",
    "violent_crime + burglaries"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using Panel\n",
    "\n",
    "To display the object from inside a function it's recommended that you use [Panel](https://panel.pyviz.org). Panel can also be used to create more complicated layouts, to add additional interactivity, and to deploy servers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import panel as pn\n",
    "\n",
    "pane = pn.panel(violent_crime)\n",
    "pane"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This ``pane`` can be updated with another HoloViews object replacing the plot:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pane.object = burglaries"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or the object can be updated inplace:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pane.object *= violent_crime "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Converting to bokeh\n",
    "\n",
    "In some cases it can be convenient to construct a plot with ``hvPlot`` and then convert it to a bokeh model to embed in a more complex plot. This can be achieved using HoloViews' ``render`` function, e.g. we can convert the `violent_crime` plot from above into a bokeh `Figure`, which can be composed into a more complex figure as needed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import holoviews as hv\n",
    "\n",
    "hv.render(violent_crime)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Python Command Prompt & Scripts\n",
    "\n",
    "When working outside the notebook we can instead use the ``hvplot.show`` function, which will open the plot in a new browser window:\n",
    "\n",
    "<img src=\"../assets/console.png\" style=\"display: table; margin: 0 auto;\"></img>\n",
    "\n",
    "For static plots this will simply save a temporary file and open it, however for dynamic and [datashaded](http://datashader.org) plots it will automatically launch a Bokeh server, enabling all the dynamic features.\n",
    "\n",
    "<img src=\"../assets/console_server.gif\" style=\"display: table; margin: 0 auto;\"></img>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Saving plots\n",
    "\n",
    "When looking at any Bokeh plot in a web browser, you can use the toolbar's \"Save\" tool to export the plot as a PNG (try it on one of the plots above!).\n",
    "\n",
    "hvPlot also provides a convenient ``save`` function to export HoloViews objects to a file. By default it will save the plot as HTML:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot = airline_flights.hvplot.hexbin(x='airtime', y='arrdelay', colorbar=True, width=600, height=500, logz=True)\n",
    "\n",
    "hvplot.save(plot, 'test.html')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default, the HTML file generated will depend on loading JavaScript code for BokehJS from the online CDN repository, to reduce the file size.  If you need to work in an airgapped or no-network environment, you can declare that `INLINE` resources should be used instead of `CDN`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from bokeh.resources import INLINE\n",
    "hvplot.save(plot, 'test.html', resources=INLINE)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, if a 'png' file extension is specified, the exported plot will be rendered as a PNG, which currently requires Selenium and PhantomJS to be installed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hvplot.save(plot, 'test.png')"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}