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.
Another tutorial shows how to embed mapbox plots as part of the notebook.
Source code can be found on github.
Create a dev environment for the new widget
For this tutorial we will need to install the jupyter package, ipywidgets for our jupyter notebook and widgets, and cookiecutter for the Jupyter notebook widget template.
We will start by creating a virtual / conda environment with the following packages:
Creating the template for our widget
In my opinion, the best place to start our work would be to use a pre-defined template for our widget. This template will already have most of what we will need.
We will use the Widget Cookiecutter template for our project.
Run the following command in order to create the base project:
After running the cookiecutter command you will need to add some basic information about your custom Jupyter widget:
Once you’re done you’ll have the following folders structure under your new directory (jupyter_britecharts_widget_tutorial):
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.
Build and install the package with the following commands:
Enable the widget for Jupyter notebook:
Start the Jupyter notebook:
In the browser, open a new notebook and insert the following code:
The code will create the text “Hello World!” in the output cell:
Add required npm packages to our project
The package dependencies are set in the js/package.json file. The package.json file is being used by setup.py, and during the build step it will install the dependencies specified in package.json using npm.
Open the js/package.json file and add the britecharts and d3 pacakges to the “dependencies” section. The “dependencies” section should look like this:
The “devDependencies” section should look like this:
Create the python file for interacting with the widget
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).
For this model we will need the following packages:
- ipywidgets - our class will inherit from “ipywidgets.DOMWidget”
Add the following imports at the beginning of the 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
Once we inherit from
DOMWidget, we will need to associate it with the front-end using the following members:
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.
We’ll add two methods:
_default_layout- controls the layout of the output cell and make enough space for the bar chart
set_data- allows the user to set their own data for the bar chart
The full code in the file should be:
Lastly, we will create the front-end side of our widget. We need to create two objects:
- widget model - the widget model defines some default values that can be overriden by the python class
- widget view - the widget view will be responsible for the rendering and creation of the bar chart itself
Create a new file called
britecharts_jupyter_widget.js in the
Start by importing jupyter-js-widgets, d3, britecharts bar chart, css, etc.:
The widget model will extend the DOMWidgetModel from
jupyter-js-widgets and set the default values:
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 full code in the file should look like this:
The export modules at the end of the file will allow our BarChartModel and BarChartView to be imported by other files.
Replace the places where
example.js was being imported in
Running the full example
Now we’re ready to run the full example.
First, uninstall the widget from our jupyter notebook so we can clean the environment before re-building and re-installing it:
Next, delete the static folder that gets generated in the
setup.py build step:
Re-run the build step and install the python package again:
Re-install the widget and enable it for our jupyter notebook:
Start the jupyter notebook again by running:
Now we need some code to populate our bar chart. We’ll use coding languages and random numbers as an example.
In the browser, open a new notebook and run the following code in the notebook cells:
Run the code in the cell and you’ll see the barchart in the output cell of the notebook:
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.
Source code can be found on github.