{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The PyData ecosystem has a number of core Python data containers that allow users to work with a wide array of datatypes, including:\n",
    "\n",
    "* [Pandas](http://pandas.pydata.org): DataFrame, Series (columnar/tabular data)\n",
    "* [XArray](http://xarray.pydata.org): Dataset, DataArray (multidimensional arrays)\n",
    "* [Dask](http://dask.pydata.org): DataFrame, Series, Array (distributed/out of core arrays and columnar data)\n",
    "* [Streamz](http://streamz.readthedocs.io): DataFrame(s), Series(s) (streaming columnar data)\n",
    "* [Intake](http://github.com/ContinuumIO/intake): DataSource (remote data)\n",
    "\n",
    "Many of these libraries have the concept of a high-level plotting API that lets a user generate common plot types very easily. The native plotting APIs are generally built on [Matplotlib](http://matplotlib.org), which provides a solid foundation, but means that users miss out the benefits of modern, interactive plotting libraries for the web like [Bokeh](http://bokeh.pydata.org) and [HoloViews](http://holoviews.org).\n",
    "\n",
    "hvPlot provides a high-level plotting API built on HoloViews and Bokeh that provides a general and consistent API for plotting data in all the abovementioned formats.\n",
    "\n",
    "As a first simple illustration of using hvPlot, let's create a small set of random data in Pandas to explore:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import pandas as pd\n",
    "\n",
    "index = pd.date_range('1/1/2000', periods=1000)\n",
    "df = pd.DataFrame(np.random.randn(1000, 4), index=index, columns=list('ABCD')).cumsum()\n",
    "\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Pandas default .plot()\n",
    "\n",
    "Pandas provides Matplotlib-based plotting by default, using the  `.plot()` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "\n",
    "df.plot();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The result is a PNG image that displays easily, but is otherwise static. \n",
    "\n",
    "## Switching backends\n",
    "\n",
    "To allow using hvPlot directly with Pandas we have to import `hvplot.pandas` and swap the backend with:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "pd.options.plotting.backend = 'holoviews'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**NOTE:** This requires a recent version of pandas (later than 0.25.0), see the [Pandas API](Pandas_API.ipynb) for more details."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## .hvplot()\n",
    "\n",
    "If we instead change `%matplotlib inline` to `import hvplot.pandas` and use the ``df.hvplot`` method, it will now display an interactively explorable [Bokeh](http://bokeh.pydata.org) plot with panning, zooming, hovering, and clickable/selectable legends:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.hvplot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This interactive plot makes it much easier to explore the properties of the data, without having to write code to select ranges, columns, or data values manually. Note that while pandas, dask and xarray all use the ``.hvplot`` method, ``intake`` uses hvPlot as its main plotting API, which means that is available using ``.plot()``.  \n",
    "\n",
    "## hvPlot native API\n",
    "\n",
    "For the plot above, hvPlot dynamically added the Pandas `.hvplot()` method, so that you can use the same syntax as with the Pandas default plotting.  If you prefer to be more explicit, you can instead work directly with hvPlot objects:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from hvplot import hvPlot\n",
    "import holoviews as hv\n",
    "hv.extension('bokeh')\n",
    "\n",
    "plot = hvPlot(df)\n",
    "plot(y=['A', 'B', 'C', 'D'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Getting help\n",
    "\n",
    "When working inside IPython or the Jupyter notebook hvplot methods will automatically complete valid keywords, e.g. pressing tab after declaring the plot type will provide all valid keywords and the docstring:\n",
    "\n",
    "```python\n",
    "df.hvplot.line(<TAB>\n",
    "```\n",
    "\n",
    "Outside an interactive environment ``hvplot.help`` will bring up information providing the ``kind`` of plot, e.g.:\n",
    "\n",
    "```python\n",
    "hvplot.help('line')\n",
    "```\n",
    "\n",
    "For more detail on the available options see the [Customization](Customization.ipynb) user guide."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "## Next steps\n",
    "\n",
    "Now that you can see how hvPlot is used, let's jump straight in and discover some of the more powerful things we can do with it in the [Plotting](Plotting.ipynb) section."
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}