hvplot_docs/Explorer.md

import hvplot.pandas  # noqa
import xarray as xr

hvPlot API provides a simple and intuitive way to create plots. However when you are exploring data you don't always know in advance the best way to display it, or even what kind of plot would be best to visualize the data. You will very likely embark in an iterative process that implies choosing a kind of plot, setting various options, running some code, and repeat until you're satisfied with the output and the insights you get. The Explorer is a Graphical User Interface that allows you to easily generate customized plots, which in practice gives you the possibility to explore both your data and hvPlot's extensive API.

:::{note} The Explorer has been added to hvPlot in version 0.8.0 and improve over the next versions, in particular version 0.9.0 added support to Xarray input types. We plan to keep on improving the explorer, making it a powerful exploration app, in the meantime please report any issue or feature request on GitHub. :::

Set up

For an explorer to be displayed in a notebook you need to load the hvPlot extension, which happens automatically when you execute an import like import hvplot.pandas. You could also just run hvplot.extension('bokeh'). If instead of building Bokeh plots you would rather build Matplotlib or Plotly plots, simply execute once hvplot.extension('matplotlib') or hvplot.extension('matplotlib') before displaying the explorer.

Instantiate

An explorer can be instantiated in two different ways:

• via the top-level explorer() function: from hvplot import explorer; explorer(data)
• via the .explorer() method available on the .hvplot namespace: data.hvplot.explorer() (added in version 0.9.0)

The explorer callable accept options to pre-customize the plot, for example data.hvplot.explorer(title='Penguins', width=200).

Interface

The object returned by explorer() is a Panel layout that can be displayed in a notebook or served in a web application. This small application includes:

• right-hand side: a preview of the hvPlot plot and code you are building
• left-hand side: the various options that you can set to customize the plot
• top part: an Alert section that displays error messages
• bottom part: a status bar which includes a live update checkbox to disable live updating the preview

Let's create our first explorer instance.

from bokeh.sampledata.penguins import data as df

df.head(2)

hvexplorer = df.hvplot.explorer()
hvexplorer

Spend some time browsing the options made available to you. Note however that to be fully interactive the explorer needs to be executed with a live Python kernel, updating the options on the website won't update the plot.

Before diving more into the explorer's capabilities, we will update the explorer we just created as the default configuration doesn't lead to a very interesting preview for this dataset. We will do so programmatically for the purpose of building this website but you would usually not have to do that, so just assume you've changed a few options directly in the explorer using your mouse and keyboard.

hvexplorer.param.update(x='bill_length_mm', y_multi=['bill_depth_mm'], by=['species'])
hvexplorer.labels.title = 'Penguins Scatter'

Record the plot state

Quite often you will want to record the state of a plot you have obtained from the explorer. We even encourage the pattern of creating short-lived explorer instances that allow for quickly building the plots you want, record their state and then remove the instances from your notebook, possibly replacing them by simpler .hvplot() plot expressions.

You can record the state of an explorer instance in multiple ways:

• Code tab: displays a code snippet you can copy/paste in your notebook and that will generate exactly the same plot as previewed in the explorer
• code parameter: holds the code snippet string
• .plot_code(var_name) method: similar to the code parameter except you can configure the variable name
• .settings() method: to obtain a dictionary of your customized settings
• .save(filename, **kwargs) method: to save the plot to file
• .hvplot() method: to get a handle on the displayed HoloViews plot

We will explore a few of these approaches. Let's start with printng code and validating that is produces a snippet that can be copy/pasted into another cell and executed (using eval to simulate that).

print(hvexplorer.code)

eval(hvexplorer.code)

The dictionary obtained from calling .settings() can be directly passed as kwargs to the .hvplot() data accessor to re-create the customized plot using the plotting API.

settings = hvexplorer.settings()
settings

Note that for the next line to display a plot hvplot.pandas has to be imported, which we did at the beginning of this notebook.

df.hvplot(**settings)

Supported data inputs

The explorer was added in version 0.8.0 with support for Pandas DataFrames. Support for Xarray objects was added in version 0.9.0.

ds = xr.tutorial.open_dataset('air_temperature')

hvplot.explorer(ds, x='lon', y='lat')

Geographic options

When geoviews is installed, it's also possible to geographically reference the data.

hvexplorer = hvplot.explorer(ds, x='lon', y='lat', geo=True)
hvexplorer.geographic.param.update(crs='PlateCarree', tiles='CartoDark', global_extent=False)
hvexplorer

Conclusion

The Explorer makes it very easy to quickly spin up a small application in a notebook with which you can explore your data, generate the visualization that you want, record it in a simple way, and keep going with your analysis!