Looking at notebooks from a new perspective

How to better communicate with Jupyter notebooks

Illustration by Juliette Taka

Jupyter notebooks are a great tool for practitioners of scientific computing from the research phase of their work to the communication of their results. The interleaving of code and rich text makes notebooks an ideal tool to communicate the complex ideas underlying computational concepts. However, depending on the context, we might want to look at the same source material (the notebook document) with different glasses, to present the content as a slideshow, or to audiences who are not comfortable with code.

One may also want to provide statically-rendered content rather than a fully-fledged executable notebook for security reasons. For each context, we should be able to adapt the notebook's aesthetics and behavior to our needs.

Fortunately, the Jupyter ecosystem offers a broad range of tools to give a new face to notebooks and adjust them to one's needs.

Panoramic view of visualization tools on the Jupyter ecosystem

The two main tools in the Jupyter ecosystem for rendering notebooks in a customized fashion are nbconvert and Voilà. In this post, we go over the differences and similarities between these two tools.

nbconvert and Voilà have the same conversion process, the main difference lies in the outcome generated by each tool. While nbconvert outputs static, non-interactive documents, Voilà converts your notebook to a fully interactive application and the way it achieves that is by keeping a Jupyter kernel active at all times.

Simplified scheme of nbconvert and Voilà’s internals

Whichever is the format you chose to generate your notebook, end-users won’t be able to execute arbitrary code, providing a secure way of sharing your results with others.

nbconvert

Nbconvert converts notebooks to various other formats via Jinja templates. It allows you to convert a .ipynb notebook file into various static formats:

• HTML
• LaTeX
• PDF
• Markdown document
• ReStructured Text
• Executable Script

nbconvert is a very versatile tool and can be used not only with the purpose of sharing your code and/or results with peers but also to create tests instances for your Jupyter notebooks and even generate blog posts. You can find more information about its possibilities in the docs.

Voilà

Voilà brings the versatility of nbconvert while allowing you to interact with your code outputs safely both in the Notebook and Lab interface.

As pointed out before, Voilà keeps a Jupyter kernel instance running at all times. It is language-agnostic and it will run any language supported by Jupyter. Furthermore, as it encapsulates nbconvert, Voilà is capable of converting the notebook to any of its output formats as well as make use of all of the templates that come with nbconvert.

Rendering interactive Matplotlib figures in a web application with Voilà. Source.

You will notice that Voilà expands on the default templates: from simple one-page documents to complex grid-based dashboards and slideshows.

Grid template generated by Voilà

Slideshows with Jupyter

A common use case is to share the results as a slideshow. Let's look at the different ways to do so.

The first step to set up your slideshow is to define the mapping between cells and slides. This mapping is saved in the cell metadata of the notebook, and JupyterLab has the appropriate built-in tool to edit this information.

Different kinds of metadata that can be added to a cell on JupyterLab

The classic notebook offers a similar interface to edit the notebook metadata. Then, to visualize the resulting slideshow, several tools are available:

RISE

RISE is a classic notebook extension that provides a toolbar button to turn the notebook into a slideshow in the main notebook UI.

RISE from the notebook to slides. Source.

Unlike the other solutions presented here, RISE slideshows are still executable in the same way as the notebook, which can be a great feature when teaching a class. However, RISE may not be an appropriate tool to share such a slideshow online because it requires giving access to a notebook server.

Unfortunately, despite the effort of the community RISE still doesn’t offer support for JupyterLab.

nbconvert

Another solution is to use the Reveal template of nbconvert, which will use the same cell metadata as RISE to produce a static slideshow.

nbconvert presentation.ipynb --to html --template reveal

Unlike with RISE, for which cells remain executable, the outcome of nbconvert is a static HTML file, and only the already-computed outputs will be displayed.

Voilà

Just like with nbconvert, the Reveal template can be used with Voilà with the --template reveal command-line argument.

Using Voilà instead of nbconvert will spawn a kernel for each connected user, enabling the use of interactive widgets in the resulting slideshow to interact with the backend.

Besides, the default behavior of Voilà is to hide input cells and only display markdown cells and output.

What’s new: Déjàvu!

Déjàvu is a new utility included in nbconvert 6.2, which simply specifies new default values for several options so as to mimick Voilà's behavior with respect to hiding input cells and prompt numbers. However, these defaults can still be overwritten by the end-user. You can do it just like you would if you were using nbconvert.

jupyter dejavu notebook.ipynb

Déjàvu output (on the left) and Voilà output (on the right)

Voilà and Déjàvu's outputs are identical, although, in the case of Déjàvu, interactions with widgets that require a roundtrip to the kernel will not work. In contrast, we can see the result of the calculation on the Voilà side.

To summarize and wrap up:

• Déjàvu supports all of the templates available in Voilà, and even though users don’t have access to interactivity they can still benefit from widgets outputs since they’ll be generated and included on the final file;
• When building a slideshow you can use JupyterLab’s interface to define specific metadata to your cells;
• You can also see your code in Déjàvu’s outputs. Just pass the --show-input option to the command line.

Acknowledgments

Thanks to Juliette Taka for creating the illustrations for this blog post.

About the author

My name is Mariana Meireles, I’m a software engineer working for QuantStack. I care deeply about the impacts that technology has in the world and try my best to be the change I want to see by contributing to open source projects that stand upon libre and diverse standards.
I’m currently focusing on the Jupyter ecosystem and advocating for open science and open knowledge whenever I can.