This is a brief tutorial introducing you to a new JupyterLab extension for creating and editing Plotly charts through a user-friendly point-and-click interface, based on https://github.com/plotly/react-chart-editor, which is a customizable React-based editor panel for Plotly charts. I will demonstrate how you can construct and save plots using plotly.py and then open and edit them using the new chart editor, all without leaving JupyterLab. We will cover how the chart editor can be used to style traces, legends, axis labels, fonts, annotations, and more!
This extension gives users the ability to customize and display an existing figure without having to write too much code. A basic understanding of plotly's JSON data structure is helpful but not necessary to get started with this awesome extension!
After this guide you'll be able to create and save figures from Python, then open and edit them in the editor. All in JupyterLab. All offline.
Note - if you're new to plotly, check out this beginner guide here, which is a quick primer on generating various types of plots in Plotly.
Assuming you have already spun up Jupyterlab, whether on your local machine or on a server in the cloud, you can install the extension by simply running:
jupyter labextension install jupyterlab-chart-editor`
Note that this is an extension strictly for Jupyterlab, and will not work in the classic notebook environment.
The extension has already been added to our workspaces, but if you use Kyso's docker image from your local machine or on another sever, you can simply create a Dockerfile in your directory with the following command:
This creates a layer from our default docker image, which has the plotly extension pre-installed.
To build and run your image use:
docker build . -t image-name
Then run it with:
docker run --rm -it --user root -v "$(pwd):/home/jovyan" -p 8888:8888 image-name
If you get any permission errors, add the environment variable ENV CHOWN_HOME=yes to the command:
docker run --rm -it --user root -v "$(pwd):/home/jovyan" -p 8888:8888 -e CHOWN_HOME=yes image-name
Ok, let's start with a relatively simple example to demonstrate the basic purpose of the extension. First, let's pull in a all of the imports we'll need for this tutorial:
Because I'm posting on Kyso, I initiate offline plotting so all of the generated plots are viewable on our frontend.
plotly.graph_objs contains the functions that will generate graph objects for us.
plotly.pio will allow us to read and write JSON data to plotly files.
Let's create and display a basic figure:
Perfect, we have a line plot that we will now customize using the editor. We first write the figure to JSON:
This will create a .plotly file, which will appear in Jupyterlab's file browser on left-hand side. Right-click on the scatter.plotly from the file browser and open with "Plotly Editor".
We make some changes to the figure, then use the file menu to save as scatter-styled.plotly.
We import the new scatter-styled.plotly file back into plotly.py and display it inline:
And there you have it! We've just customized a simple scatter figure without having to write any code!
Let's read in some gapminder data and filter for a single year for the purpose of this example:
The gapminder dataset consists of various economic indicators of countries around the world, such as life expectancy and GDP per capita.
Let's first create an empty plotly figure:
Ok, now let's add some data to our plotly figure. After executing the following cell, run
fig.data in the next cell to see what our plot's underlying data structure is like now.
This is a pretty cool graph. We've grouped countries by their respective continents, and plotted their GDP per capita (y-axis) against life expectancy (x-axis), with the data points sized by their respective populations. Clearly, there is a positive correlation between the two indicators, but we won't dive into that just now.
Now we're going to use our chart editor to edit the figure's layout. Let's again write our figure to JSON.
As we did above, we can now customize the layout of our plot, except this time we'll make some more advanced edit operations.
Some of these edits are made directly on the figure itself, such as the title and axis labels.
And then we make some data-related adjustments. We change the scale of the y-axis to a log-scale to get a clearer view of the dispersion between countries. We also make some other configurations to the plot, such as the colorscale, background color, the opacity of the traces, as well as the grid lines.
You can see that the final result is not unlike the popular ggplot style. We have also adjusted the custom dimensions of the plot, as seen above.
We can make some simple annotations of data points for static representation if you are exporting to a png or pdf file. You can download the plot directly to png. And we have saved the file under a new name.
And now we display our newly-styled plot in the notebook:
You can also edit the json data directly in the notebook. For example, to edit the title:
fig_styled.layout.title = 'Wealth & Health of Nations (1982)'
There are a multitude of different ways to share:
You can save as a standalone html file, which you can then open in the browser with a simple drag & drop.
This version of the file is self-contained, so you can just send it by email to friends or colleagues.
As we saw above, when downloading the plot as a png from the editor itself, the editor has static image export support. You can save as a PDF image to insert in an academic paper or to embed in a blog. This is cool because the PDF is saved in a high quality vector format.
Note that this property takes advantage of the orca project. If you don't have this currently installed, you can install it by running the following:
sudo conda install -c plotly plotly-orca
See the orca README (https://github.com/plotly/orca) for more info.
That's it for now! Please note that this blog only looked at a very small sample of the kinds of edits you can make with the chart editor. This new extension is really awesome for styling if, for example, you want to build a high-quality presentation or want to make complicated edits to existing plots you have generated, without having to have a live python kernel involved.
The maintainers over at plotly are continuing to improve upon the existing features of the extension. Some interesting ideas are:
Pretty exciting stuff!! I will be writing another post in the future once some of these new functionalities have been added.
Keep an eye on the component here for issues and updates! Bye for now!