A slideshow template for Voilà apps

2019-10-29T10:32:00+00:00

Last June, QuantStack announced the first release of Voilà, a solution to turn Jupyter notebooks into standalone web applications. Voilà enforces security (preventing arbitrary code execution) while preserving interactivity (supporting interactive widgets for Jupyter notebooks, including roundtrips to the kernel). A recent addition to the ever-teeming Jupyter ecosystem, Voilà is flexible, extensible, and language-agnostic (running any Jupyter kernel, such as Python, R, Julia, C++).

A dashboarding solution based on Jupyter.

Getting started with Voilà

Voilà is available as a Python package on conda-forge and PyPI. After installing Voilà in their environment, Jupyter notebook users will see a new button in the toolbar, a button reading “Voila” with a display icon. Clicking this button will take you to a Voilà web app served with the notebook server.

Voilà use case as a Jupyter server extension.

Alternatively, you can use Voilà to create a standalone Tornado application. From the terminal, run $ voila index.ipynb to turn notebook index.ipynb into a web app. Note that you don’t launch nor run the Jupyter notebook yourself. At this point, Voilà serves the app locally.

Jupyter notebook turned Voilà app (source).

Of course, the full value of sharing these apps (typically analytics web apps, data dashboards) comes from deploying them. Voilà apps can come into play at different steps of a data science workflow, from the initial step of exploring data all the way to the final step of communicating results.

Styling Voilà apps with layout templates

Now, you may want to customize the layout of your app, especially if it is somewhat complex. For example, you can make results more readable by splitting them and using different tab panes or boxes. This you can already achieve with the voila-gridstack template, also available from either conda-forge or PyPI (still in beta).

Templates are written in Jinja and use the metadata field of the notebook cells. Practically, a Voilà template is a folder which lives under PREFIX/share/jupyter/voila/templates/. The system of custom templates is actually where the extensibility of Voilà shines most. Here, we introduce voila-reveal, a slideshow template for Voilà. It builds off of RISE, which itself builds off of reveal.js. The credit goes to Maarten Breddels for initiating development a few months ago.

Rendering Voilà apps as slideshows

With RISE, you can instantly turn your Jupyter notebook into a slideshow. Besides, if you share it within a binder, collaborators can readily view it in their web browser, with no need for a local setup. They can enjoy the interactive controls, if any. They are expected to run code though (example), which may not be suitable if they are non-technical. And, even if they are, you may want to prevent arbitrary code execution.

With Voilà and its new reveal template, you can achieve this by sharing your RISE slideshow as a standalone web application. How so? Ever since Jupyter notebook slides, it has been possible to author or edit a Jupyter notebook with slideshow-related information on each cell. In principle, we could also add (or edit) these cell metadata manually (or automatically) by post-processing the JSON.

Our custom slideshow template voila-reveal leverages these very cell metadata (namely, subfield slideshow of field metadata). It handles them the exact same way nbconvert does when generating slideshow HTML from a notebook. It also passes default values to specific resources required by reveal. These reveal-required resources are: scroll, theme, and transition.

To use the slideshow template with Voilà, install the voila-reveal package: $ conda install voila-reveal or $ pip install voila-reveal. This will create and populate the PREFIX/share/jupyter/voila/templates/reveal/ folder. At the command line, serve the index.ipynb notebook as a standalone app with the following command:

$ voila index.ipynb --template=reveal

… and voilà!

Voilà app rendered as a slideshow with slide transitions configured to zoom in and out (source).

Configuring templates at the command line

You can overwrite the above-mentioned resource defaults by passing additional options. For instance, the default value of transition is "fade". To get the "zoom" behaviour, we could use the following command:

$ voila index.ipynb --template=reveal --VoilaConfiguration.resources="{'reveal': {'transition': 'zoom'}}"

Admittedly, it is verbose and cumbersome. Another possibility is to specify (here, reveal-specific) resources in a configuration file.

Configuring templates with a JSON file

Write your configuration file, named conf.json, with the following structure:

{
  "traitlet_configuration": {
    "resources": {
      "reveal": {
        "scroll": false,
        "theme": "simple",
        "transition": "zoom"
      }
    }
  }
}

Then, it is enough to run $ voila index.ipynb --template=reveal to get slide transitions zoomed in and out; Voilà picks up the config file, as long as it lives under PREFIX/share/jupyter/voila/templates/reveal/.

In the above demo screencast, we showcase a scatter plot and a scatter matrix of the “iris” dataset made with Plotly Express and customizable with ipywidgets dropdowns. To display the Python code for these plots, run

$ voila index.ipynb --template=reveal --strip_sources=False

To turn on scrollbars, so you can view the plots entirely, run

$ voila index.ipynb --template=reveal --strip_sources=False --VoilaConfiguration.resources="{'reveal': {'scroll': True}}"

or edit the scroll value in the configuration file!

Coming next

At the moment, you must specify the template upon launching Voilà. We would like to be able to toggle between different templates on the fly (without restarting the app). To this end, we shall support template specification as a URL parameter. We shall make template selection available from the Jupyter interface as well.

Acknowledgments

The development of voila-reveal is entirely supported by QuantStack. The author would like to thank Jeremy Tuloup, Johan Mabille, and Sylvain Corlay for their valuable feedback on this piece.

About the author

Marianne Corvellec is an independent scientific software developer. She is also an independent researcher affiliated with IGDORE. She holds a PhD in statistical physics from Ecole Normale Supérieure de Lyon, France.

Jupyter Blog - Marianne Corvellec