Creating a Jupyter notebook widget

This post will provide a step-by-step tutorial for creating and running a Jupyter widget.

The Jupyter widget we’ll create in this example will allow us to add Britecharts to our Jupyter notebook.

Jupyter notebook is increasingly becoming one of my main tools and I wanted to be able to extend the basic Jupyter notebook and create additional widgets / use external javascript libraries inside Jupyter notebook.

All of these are great tutorials, but I was looking for a tutorial teaching how to build a simple widget, from scratch, that uses an external javascript library as part of the Jupyter notebook. That will be covered in this tutorial.

As you can see from the folder tree, the widget has two parts which are the python code and the javascript code.
When we run the widget, we will run python code in our notebook and that code will sync with the javascript code, which will render the output in our notebook.

Running the example widget

The cookiecutter jupyter widget has an integrated “hello world” example. Just as a sanity check, let’s try to run this example.
In order to run it, we need to install the package in our virtual env and enable it for our jupyter notebook.

Add required npm packages to our project

Since pull request 1047, Jupyter notebook is using Webpack for javascript bundling.
This change allows the notebook to use NPM packages such as d3 and in our case (for this tutorial), it will allow us to add the Britecharts package to our Jupyter widget module.

Create the python file for interacting with the widget

The python side of the widget will basically be a class that is synced with a javascript model.

When you call the widget in the notebook, the python module will call the javascript model which will eventually be rendered in the browser.
You can find more details about this process here.

In our example, we will write a simple Python class.
In order to use this class we will have to pass it a list of values.
This list of values will be used by the class to create a bar chart in the notebook.

Create a new python file with the name “britecharts_jupyter_widget.py” in the <package_name>\<package_name> folder, “jupyter_britecharts_widget_tutorial\jupyter_britecharts_widget_tutorial” in our example (this is same folder that has the “example.py” file).

Create a new class for the bar chart that we want to display.
Because we want our widget to be displayed in the Jupyter notebook, our class must inherit from ipwidgets.DOMWidget.
Once we inherit from DOMWidget, we will need to associate it with the front-end using the following members:

_view_name

_view_module

_model_name

_model_module

Each attribute will be a traitlets object that will have the sync=True option for handling the synchonization of the value with the browser.

We also want to add an attribute that will save our _model_data for the bar chart.
The traitlets package will help us to declare the types of each of these attributes which is required for the widget.

The widget view will handle rendering the bar chart in the browser.
this.elm is the HTML container our widget will use to hold the bar chart.
After we are done setting up the bar chart object, we’ll combine it with our data in the bar chart container.

The settings for the bar chart can be changed according to your preferences. In this example, we added a color scheme for the bar chart that we’ve imported earlier on. For now, to make things simple, we will hard code all these settings in the javascript file.

Run the code in the cell and you’ll see the barchart in the output cell of the notebook:

Debugging

Debugging the jupyter widget can be a little tricky as there are many components and you need to know where to look in order to find the error.

I use the following tools to debug my Jupyter widgets:

If the issue is with the Python code, you will be able to see the error in the Jupyter notebook console output.

If the issue is with the Javascript code, you will either find the error during the “setup.py build” step or in the browser using the browser’s developer tools -> javascript console, firebug, etc.

Summary

This was a very basic example of creating a Juyper notebook widget that uses external javascript libraries.
Britecharts was used for this example as the external javascript library, but the same method can be used with other external javascript libraries.