Table of Contents
tl;dr
pip install nbinteract
jupyter nbconvert --to interact my_notebook.ipynb
Creates an interactive webpage from a Jupyter notebook.
Explorables
Through my teaching years I’ve come across a bunch of helpful interactive demos for teaching. For example, Explained Visually has a neat demo of PCA that I show students when learning PCA for the first time:
These demos are also known as explorables and they just feel helpful for learning. I observe that as students interact with these types of interactive explanations they implicitly create and test their own hypotheses about the concept. For example, in the example above I asked myself: “How influential can one point be for PCA?”. To me, these explorables encourage active learning by helping students come up with and answer their own questions.
The Issue with Explorables
Many instructors, myself included, wish for an ideal world where almost every lesson can be taught using an explorable demonstration. However, making explorables require two skillsets that are infrequently found together. For example, to recreate the PCA example above you need:
- A strong understanding of PCA to know what to expose to the user.
- Strong web-dev skills to implement the demo.
It just so happens that many instructors have the understanding of the skill
but not the web-dev know-how. As a first step to enable instructors to create
explorables, I created a tool called nbinteract
that takes a Jupyter notebook
with interactivity and allows instructors to publish these notebooks as
interactive web pages.
Interactive Jupyter Notebooks?
Turns out that Jupyter notebooks have an easy way to add interactivity using a
Python library called ipywidgets
. ipywidgets
creates an interactive interface to call a function with different arguments.
For example, the slider in the below animation calls a function to draw points
with different correlations.
For more information about ipywidgets
, see its
Github.
Unfortunately, if you want to show someone else this interactive demo, they have to spin up a notebook server themselves and run your notebook before they can play with your explorable. This is a much higher barrier-to-entry than sharing a URL since the user needs to have Jupyter, Python, and other packages installed on their computer to run the notebook.
Notebook to HTML
Jupyter comes with a package called nbconvert
that can convert a notebook to
an HTML webpage that can then be put online for others to view. With the
built-in converter tool, however, interactive widgets won’t work.
The nbinteract
package provides add-on functionality to nbconvert
. It
performs a notebook-to-HTML conversion that keeps widgets functional. The
resulting webpage, once put online, can be viewed by anyone with a web browser.
For example, the animation below was recorded using a computer without Python
or Jupyter installed by visiting this URL.
Using nbinteract
To use nbinteract
, you need to already have Jupyter and nbconvert
installed. To install nbinteract
:
pip install nbinteract
Then, you can convert a notebook with:
jupyter nbconvert --to interact a_notebook.ipynb
Where a_notebook.ipynb
is the name of your notebook file. This creates an
HTML file called a_notebook.html
. If you put that HTML file online (using
Github pages, for example), anyone can view your notebook and interactive with
widgets that you’ve created.
How it works
Widgets don’t work by default when converting a notebook to HTML because interacting with a widget is supposed to call a Python function and show its output. Webpages aren’t allowed to run Python on your computer without extra setup. Normally, Jupyter notebooks perform this setup for you, but many internet viewers don’t have Jupyter installed.
nbinteract
enables widgets to function by running a Jupyter notebook using
the Binder service in the background. When a user
interacts with a widget on an nbinteract
webpage, the widget sends a request
to a Binder notebook server, gets the output, and shows it in the page.
Future work
Currently we plan to use nbinteract
to add interactivity to pages in
Berkeley’s Data 8 and Prob
140 textbooks. We also plan to conduct some
preliminary user studies in order to see whether this tool is useful for
learning.
In the future, I plan to create new widgets specifically for learning data science. I’m specifically interested in helping students understand sequences of random events (eg. in a bootstrap hypothesis test). I think that students can develop a stronger intuition for statistics not only through interacting with explorables but also through constructing mini-explorables themselves in the process of problem-solving.
Hope nbinteract
is useful to you! Feel free to leave comments and questions
in the nbinteract
issue tracker.