{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "**A high-level plotting API for the PyData ecosystem built on HoloViews.**\n", "\n", "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 (labelled multidimensional arrays)\n", "* [Dask](http://dask.pydata.org): DataFrame, Series (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 (data catalogues)\n", "* [GeoPandas](http://geopandas.org): GeoDataFrame (geometry data)\n", "* [NetworkX](https://networkx.github.io/documentation/stable/): Graph (network graphs)\n", "\n", "Several 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 it means that users miss out on 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 that provides a general and consistent API for plotting data in all the abovementioned formats. hvPlot can integrate neatly with the individual libraries if an extension mechanism for the native plot APIs is offered, or it can be used as a standalone component. To get started jump straight into the [Getting Started Guide](getting_started/index.html) and check out the current functionality in the [User Guide.](user_guide/index.html)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Usage\n", "\n", "hvPlot provides an alternative for the static plotting API provided by [Pandas](http://pandas.pydata.org) and other libraries, with an interactive [Bokeh](http://bokeh.pydata.org)-based plotting API that supports panning, zooming, hovering, and clickable/selectable legends:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import pandas as pd, numpy as np\n", "idx = pd.date_range('1/1/2000', periods=1000)\n", "df = pd.DataFrame(np.random.randn(1000, 4), index=idx, columns=list('ABCD')).cumsum()\n", "\n", "import hvplot.pandas # noqa\n", "df.hvplot()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "hvPlot works with multiple data sources and ships with some inbuilt sample data, which is loaded using the [Intake](http://github.com/ContinuumIO/intake) data catalog." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from hvplot.sample_data import us_crime\n", "\n", "columns = ['Burglary rate', 'Larceny-theft rate', 'Robbery rate', 'Violent Crime rate']\n", "us_crime.plot.violin(y=columns, group_label='Type of crime', value_label='Rate per 100k', invert=True)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Unlike the default plotting, hvPlot output can easily be composed using `*` to overlay plots (or `+` to lay them out side by side):" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "us_crime.plot.bivariate('Burglary rate', 'Property crime rate', legend=False, width=500, height=400) * \\\n", "us_crime.plot.scatter( 'Burglary rate', 'Property crime rate', color='black', size=15, legend=False) +\\\n", "us_crime.plot.table(['Burglary rate', 'Property crime rate'], width=350, height=350)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "When used with [streamz](http://streamz.readthedocs.io) DataFrames, hvPlot can very easily plot streaming data to get a [live updating plot](user_guide/Streaming.html):" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import hvplot.streamz # noqa\n", "from streamz.dataframe import Random\n", "\n", "streaming_df = Random(freq='5ms') \n", "\n", "streaming_df.hvplot(backlog=100, height=400, width=500) +\\\n", "streaming_df.hvplot.hexbin(x='x', y='z', backlog=2000, height=400, width=500);" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "For multidimensional data not supported well by Pandas, you can use an XArray Dataset like this gridded data of North American air temperatures over time, which also demonstrates support for [geographic projections](user_guide/Geographic_Plots.html):" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import xarray as xr, cartopy.crs as crs\n", "import hvplot.xarray # noqa\n", "\n", "air_ds = xr.tutorial.open_dataset('air_temperature').load()\n", "proj = crs.Orthographic(-90, 30)\n", "\n", "air_ds.air.isel(time=slice(0, 9, 3)).hvplot.quadmesh(\n", " 'lon', 'lat', projection=proj, project=True, global_extent=True, \n", " cmap='viridis', rasterize=True, dynamic=False, coastline=True, \n", " frame_width=500)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Lastly, hvPlot also provides drop-in replacements for the NetworkX plotting functions, making it trivial to generate interactive plots of [network graphs](user_guide/NetworkX.html):" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import networkx as nx\n", "import hvplot.networkx as hvnx\n", "\n", "G = nx.karate_club_graph()\n", "\n", "hvnx.draw_spring(G, labels='club', font_size='10pt', node_color='club', cmap='Category10', width=500, height=500)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "hvPlots will show widgets like the \"Time\" slider here whenever your data is indexed by dimensions that are not mapped onto the plot axes, allowing you to explore complex datasets much more easily than with the default plotting support.\n", "\n", "hvPlot is designed to work well in and outside the Jupyter notebook, and thanks to built-in [Datashader](http://datashader.org) support scales easily to millions or even billions of datapoints:\n", "\n", "\n", "\n", "The [User Guide.](user_guide/index.html) shows more of what's available and how to use it.\n", "\n", "## Installation\n", "\n", "hvPlot supports Python 2.7, 3.5, 3.6 and 3.7 on Linux, Windows, or Mac and can be installed with conda:\n", "\n", "```\n", "conda install -c pyviz hvplot\n", "```\n", "\n", "or with pip:\n", "\n", "```\n", "pip install hvplot\n", "```\n", "\n", "For JupyterLab support, the ``jupyterlab_pyviz`` extension is also required:\n", "\n", "```\n", "jupyter labextension install @pyviz/jupyterlab_pyviz\n", "```\n", "\n", "The [Getting Started Guide](getting_started/index.html) has more details if you need them." ] } ], "metadata": { "language_info": { "name": "python", "pygments_lexer": "ipython3" } }, "nbformat": 4, "nbformat_minor": 2 }