Interactive Dashboard from Jupyter Notebook with Mercury framework

Photo by Louis Hansel on Unsplash

You have just prepared your Jupyter notebook with the analysis. Congratulations!🎉 You would like to share your results and findings with others. The bad news is that you can’t share the Jupyter Notebook code directly with your friends because they don’t speak Python 🐍. They can’t install required packages, pull the code from the GitHub repository, and run the notebook locally. The good news is that you can easily convert your notebook into a standalone web application with minimal effort.

In this post, you will learn how to:

• create a dashboard in the Jupyter Notebook,
• convert notebook to a standalone web application,
• deploy a notebook-based app to Heroku.

This article is inspired by the previous article “Creating an Interactive Dashboard from Jupyter Notebook with Voila” by Ruben Winastwan.

Ruben, in his article, created the dashboard of San Francisco crimes. His code is available at GitHub https://github.com/marcellusruben/sf-crime-voila

The dashboard in the notebook

The code to create a dashboard can be divided into three parts:

1. Load a dataset from a CSV file.
2. Set parameters that will filter the data.
3. Plot data as map and histograms.

The code is presented in the Gist below.

The code that creates the dashboard.

You will need the following packages in the requirements.txt file to run the notebook:

mljar-mercury                             
pandas                             
numpy                             
matplotlib                             
folium

The dashboard is presented in the screenshot below:

The Dashboard view in the Jupyter Notebook

The code to create a dashboard is just Python code. Please note that the parameters used in the dashboard are just simple variables. There are no widgets used. If you want to change something in the dashboard, you need to change the variable and re-execute the notebook.

The exciting things will happen in the next step 🪄

Convert Notebook to Web App

Now we will need some magic. Ruben, in his article, used ipywidgets and Voila to turn a notebook into a web application. Here I will use a Mercury framework. It allows you to define the widgets for the notebook by adding a YAML header at the beginning of the notebook. The YAML is below:

The YAML header added to the notebook as a first RAW cell.

The YAML header should be added at the beginning of the notebook as a RAW cell.

The full notebook with code and YAML header.

The YAML configuration is used to create widgets for the notebook.

Widgets are defined based on YAML configuration.

The following widgets panel is created based on the YAML:

The widgets panel generated from YAML header.

It is important to note that variables in the YAML should have the same names as variables in the code. Later, widgets values will be assigned to the variables in the code after Run button clicked.

YAML params should be the same as variables names.

The YAML is ready. It’s time to check how it looks like in the Mercury.

You can observe how the web application will look like during the notebook development. There is a command mercury watch — for watching the code updates on the notebook. Please just run the command:

mercury watch SF_crime.ipynb

You will get the application running at http://127.0.0.1:8000/

The application running in the watch mode.

Every time you will update the notebook it will be automatically updated in the Mercury (no need to press F5 😊)

Deploy to Heroku

The dashboard is ready, so let’s deploy it to the Heroku.

I assume that you have a Heroku account and Heroku Command Line (CLI) tool installed (check the docs if needed).

Let’s create a Heroku app by running:

heroku create dashboard-mercury

in the project directory. (You should use different name in the create command)

We will need to add a Procfile to our project:

web: mercury runserver 0.0.0.0:$PORT --runworker

Let’s set necessary environment variables in the dyno:

heroku config:set ALLOWED_HOSTS=dashboard-mercury.herokuapp.com
heroku config:set SERVE_STATIC=True
heroku config:set NOTEBOOKS=*.ipynb

You are ready to deploy the app by running:

git push heroku main

That’s all. You should be able to check the app running at https://dashboard-mercury.herokuapp.com. Below are presented views of the notebook dashboard in mobile and desktop.

The mobile view of the dashboard application.

The desktop view of the dashboard application.

Conclusion

The Jupyter Notebook is a fantastic tool to analyze the data and visualize the results. The dashboard created in Python can be easily shared as a standalone web application thanks to the Mercury framework 🧰. The interactive widgets are defined by YAML header. The widgets values are assigned to variables in the code, so there is no need to rewrite or change the notebook’s code. The application can be easily published on free Heroku dyno.

The dashboard code & data are available on the GitHub repository.

I’m the author of the Mercury framework.