{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "**A high-level plotting API for the PyData ecosystem built on HoloViews.**\n", "\n", "\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](https://pandas.pydata.org): DataFrame, Series (columnar/tabular data)\n", "* [Rapids cuDF](https://docs.rapids.ai/api/cudf/stable/): GPU DataFrame, Series (columnar/tabular data)\n", "* [Dask](https://dask.pydata.org): DataFrame, Series (distributed/out of core arrays and columnar data)\n", "* [XArray](https://xarray.pydata.org): Dataset, DataArray (labelled multidimensional arrays)\n", "* [Streamz](https://streamz.readthedocs.io): DataFrame(s), Series(s) (streaming columnar data)\n", "* [Intake](https://github.com/ContinuumIO/intake): DataSource (data catalogues)\n", "* [GeoPandas](https://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 built 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 [installation instructions](#installation) 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 by default 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": [ "With recent versions of Pandas (>=0.25.0) we can also swap the default plotting backend:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "pd.options.plotting.backend = 'holoviews'\n", "\n", "df.A.hist()" ] }, { "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, color='Type of crime')" ] }, { "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": [ "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.\n", "\n", "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": [ "hvPlot offers the possibility to create [Matplotlib](https://matplotlib.org/) and [Plotly](https://plotly.com/) plots. Load the chosen plotting library with the `extension` function." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "hvplot.extension('matplotlib')" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "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", " xaxis=None, yaxis=None, width=500\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "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", "" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "For information on using hvPlot take a look at the [User Guide](user_guide/index.html) or the [announcement blog](http://blog.pyviz.org/hvplot_announcement.html).\n", "\n", "## Installation\n", "\n", "| | |\n", "| --- | --- |\n", "| Latest release | [![Github release](https://img.shields.io/github/release/holoviz/hvplot.svg?label=tag&colorB=11ccbb)](https://github.com/holoviz/hvplot/releases) [![PyPI version](https://img.shields.io/pypi/v/hvplot.svg?colorB=cc77dd)](https://pypi.python.org/pypi/hvplot) [![hvplot version](https://img.shields.io/conda/v/pyviz/hvplot.svg?colorB=4488ff&style=flat)](https://anaconda.org/pyviz/hvplot) [![conda-forge version](https://img.shields.io/conda/v/conda-forge/hvplot.svg?label=conda%7Cconda-forge&colorB=4488ff)](https://anaconda.org/conda-forge/hvplot) [![defaults version](https://img.shields.io/conda/v/anaconda/hvplot.svg?label=conda%7Cdefaults&style=flat&colorB=4488ff)](https://anaconda.org/anaconda/hvplot) |\n", "| Python | [![Python support](https://img.shields.io/pypi/pyversions/hvplot.svg)](https://pypi.org/project/hvplot/) |\n", "\n", "hvPlot supports Python 3.6, 3.7, 3.8, 3.9 and 3.10 on Linux, Windows, or Mac. The recommended way to install hvPlot is using the [conda](https://conda.io/en/latest/) command provided by [Anaconda](https://docs.anaconda.com/anaconda/install/index.html) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html):\n", "\n", " conda install -c pyviz hvplot\n", "\n", "or using PyPI:\n", "\n", " pip install hvplot\n", "\n", "For versions of `jupyterlab>=3.0` the necessary extension is automatically bundled in the `pyviz_comms` package, which must be >=2.0. However note that for version of `jupyterlab<3.0` you must also manually install the JupyterLab extension with:\n", "\n", " conda install jupyterlab\n", " jupyter labextension install @pyviz/jupyterlab_pyviz" ] } ], "metadata": { "language_info": { "name": "python", "pygments_lexer": "ipython3" } }, "nbformat": 4, "nbformat_minor": 4 }