Jupyter Blog - Voilà

Voilà 0.5.0 : Homecoming

2023-09-25T14:54:00+00:00

Voilà 0.5.0: Homecoming

Voilà turns Jupyter notebooks into standalone web applications and dashboards. It provides a simple way for Jupyter users to share their work. For a detailed introduction to Jupyter’s Voilà subproject, you can check out this earlier blog post.

Up until the previous version, Voilà relied on custom JavaScript code to load extension assets and handle kernel connection. However, this approach had drawbacks since it only supported the now outdated Jupyter Notebook 6 extensions.

Following the launch of Jupyter Notebook 7, it is now Voilà’s turn to join the JupyterLab family. In Version 0.5.0, the front-end of Voilà has been rebuilt from scratch using JupyterLab 4.0 components, just like in the case of Notebook 7. A JupyterLab plugin-based application replaces the current custom extension loader approach. This transition enables Voilà to leverage all the latest features and enhancements available upstream.

New features in Voilà 0.5.0

Extension loading system

As of Version 0.5.0, Voilà uses the same prebuilt extension system as JupyterLab. The extension assets are loaded from local paths rather than relying on a CDN, resulting in a significant enhancement to Voilà’s extension compatibility with the rest of the JupyterLab ecosystem. This change also avoids making requests for external services. Additionally, users can now develop extensions for Voilà using the same approach as for JupyterLab extensions.

A Voila dashboard with top bar extension and custom JupyterLab theme.

Mimetype rendering mechanism

In 0.5.0, the logic for rendering cell outputs containing mimetypes has been revised, moving away from relying on nbconvert and instead depending on JupyterLab mimetype renderers. This change adds support for a wide range of custom JupyterLab renderers such as jupyterlab-fasta, vega, jupyterlab-geojson, etc.

Rendering mimetypes data in Voila

New tree page

The default tree page in Voilà has transitioned into a JupyterLab-based application incorporating the file browser widget. While the Jinja-based tree page remains available, users must opt for it using either the --classic-tree CLI option or by appending ?classic-tree=Trueto the query string.

The new tree page in Voilà supports JupyterLab custom themes, whereas the classic tree page is limited to light and dark themes.

New tree page with a custom theme.

Token-based authentication system

Depending on the identity provider of jupyter-server 2, Voilà now supports token authentication but is disabled by default.

To start Voilà with auto-generated token:

voila --token ...

To start Voilà with a personalized token:

voila --token=my-secret-token ...

Installing Voilà

Voila is available on both PyPI and conda-forge:

# Install with pip
pip install voila

# Install with mamba
mamba install -c conda-forge voila

You can try Voilà online using this link.

Acknowledgments

The contributions to Voilà by QuantStack are supported by Bloomberg.

About the Contributors

Voilà is an official Jupyter subproject, it has resulted from the collective efforts of numerous contributors. Below, we highlight the primary contributors for this release:

Jeremy Tuloup is a Technical Director at QuantStack and a Jupyter Distinguished Contributor. Maintainer and contributor of JupyterLab, Jupyter Notebook, JupyterLite, Voilà, and projects within the Jupyter ecosystem.

Martin Renou is a Project Director at QuantStack and a Jupyter Distinguished Contributor. Martin works on a variety of projects, from xtensor and xeus-python in C++ to ipywidgets, ipyleaflet and bqplot in Python and TypeScript.

Le Duc Trung is a Scientific Software Developer at QuantStack. He works on several projects within the Jupyter ecosystem, from the main projects like JupyterLab, Voilà, and ipywidgets to various JupyterLab extensions and widgets.

Need for Speed: Voilà edition

2021-12-10T14:52:00+00:00

Voilà turns Jupyter notebooks into standalone applications without requiring any modification to the content. You want to share your content with non-technical readers? Just call Voilà with the notebook to turn it into a deployable web application. The simplicity of Voilà comes at a cost: the page load time.

We set ourselves to fix this Achilles’ heel while preserving the ease-of-use of Voilà. Today we are pleased to announce the release of Voilà 0.3.0, with a focus on performance.

Motivation

Page load time has a critical impact on user experience of a website.

According to Kissmetrics, nearly half of web users expect a site to load in 2 seconds or less, and they tend to abandon a site that is not loaded within 3 seconds.

In the case of Voilà, a simple dashboard takes around one second to render and more complicated dashboards (involving libraries import, data fetching, and widgets) can easily push users out of their comfort zone. Several efforts have been made to improve the situation, from adding an execution progress indicator to enhancing the rendering technique. The load time of a medium-to-high complexity notebook has not been cut down to a desirable range yet. That is why in the 0.3.0 version, we aimed at addressing the main bottleneck of Voilà: the execution of notebook.

Preheated kernels

Based upon an excellent idea of the hotpot_km project about the pooling hot-loaded Jupyter kernels, we implemented a new solution called “preheated kernels” to diminish the waiting time for starting a new python kernel and for executing the requested notebook.

Preheated kernels can be activated just by setting thepreheat_kernel option to Truein the Voilà command line or configuration file. For example, this command will activate preheated kernels feature for the voila.ipynb notebook with a pool of five kernels:

voila voila.ipynb --preheat_kernel=True --pool_size=5

Speed comparison between Voilà 0.3.0 with preheated kernel and 0.2.16

Behind the scene, the two following actions are performed:

For each notebook, a queue of kernels is created and the notebook is executed in every kernel. When a new client requests a kernel, the oldest preheated kernel of the pool is used and another kernel is started asynchronously to refill the pool.
The rendered HTML for the notebook is produced in advance for each preheated kernel and directly served to the client upon connection.
If the kernel pool is empty, Voilà will fall back to starting a new kernel and render the notebook as usual. The advanced configurations of preheated kernels are detailed in Voilà’s official documentation.

Partially pre-render notebook

To benefit from the acceleration of preheated kernels mode, the notebooks need to be pre-rendered before users connect to Voilà. But in many real-world applications, the notebook requires user-specific data, which makes pre-rendering impossible. To overcome this limit, Voilà offers a feature to handle the most used method for providing user data: the URL query string.

In preheated kernels mode, Voilà executed the first 4 cells before waiting for the query string from the user.

In normal mode, Voilà users can get the query string at run time through the QUERY_STRING environment variable:

import os
query_string = os.getenv('QUERY_STRING')

In preheated kernels mode, users can simply replace the os.getenv call with the helper get_query_string from voila.utils

from voila.utils import get_query_string
query_string = get_query_string()

get_query_string will pause the execution of the notebook by the preheated kernel at this cell and wait for an actual user to connect to Voilà, then get_query_string will return the URL query string and continue the execution of the remaining cells.

To maximize the benefits of preheated kernels, the user-independent cells should be placed before the get_query_stringcall.

What’s next?

There is more in the works to improve Voilà’s performances. Beyond kernel hot pooling, we will improve the performance of rendering Jupyter widgets in the front-end. Several of these improvements will be enabled with the upcoming 8.0 release of ipywidgets, and more optimizations are in the works.

Acknowledgments

We would like to thank Vidar Tonaas Fauske and Maarten Breddels for the prior art on the hotpot_km project, which was an inspiration for this work in core Voilà.

About the author

Duc Trung Le is a Scientific Software Developer at QuantStack. He works on several projects within the Jupyter ecosystem, from the main projects like JupyterLab, Voilà, ipywidgets to Jupyter extensions and widgets.

Looking at notebooks from a new perspective

2021-10-05T08:33:00+00:00

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.

Voilà is now a Jupyter subproject

2019-12-29T12:11:00+00:00

It is a great pleasure to announce that the Voilà project has been incorporated as a Jupyter subproject. Voilà will now be subject to the Jupyter governance and code of conduct.

For reference, the Jupyter Enhancement Proposal (JEP) for the Voilà incorporation is available here.

What is Voilà?

Voilà helps you communicate insights, by transforming a Jupyter Notebook into a stand-alone web application you can share. It gives you control over what your readers experience in a secure and customizable interactive dashboard.

The easiest way to get started with Voilà is to install it via pip or conda and type voila some_notebook.ipynb to turn the said notebook into a dashboard.

Besides, Voilà includes a templating system that allows to overload the behavior of the front-end. Using this templating system, Voilà can be used to create

slideshows (with voila-reveal)

A Voilà slideshow created with the voila-reveal template.

dashboards (with voila-gridstack)

A Voilà Dashboard based on the voila-gridstack template.

Why moving Voilà under the Jupyter governance?

While the project was initially started by QuantStack, the team now comprises developers from Bloomberg, UC Berkeley, JP Morgan, and Cal Poly San Luis Obispo. OVH has been supportive of the project by kindly providing the free hosting of the gallery on their infrastructure.

We believe that the multi-stakeholder nature of the Voilà project is well-suited for the Jupyter organization.

The Voilà project is largely built upon Jupyter subprojects and standards.

The standard notebook file format is the main entry point to Voilà.
nbconvert is used for the conversion to progressively-rendered HTML.
naturally, we use jupyter_client for handling the execution of notebook cells
jupyter_server is the default back-end.
JupyterHub is at the foundation of the voila-gallery project.
JupyterLab components (mime renderers, input and output areas) are used in the front-end implementation. Voilà also includes a preview JupyterLab extension.
ipywidgets and custom jupyter widget libraries such as bqplot, ipyvolume, ipyleaflets provide the bulk of the interactivity of Voilà applications.

Voilà is more a remix of existing Jupyter components (with changes to enable that use case) than a completely new application.

Resources

Should you be interested in Voilà, feel free to try it on Binder or locally! You can also engage with the developer community during our public team meetings and the various GitHub repositories of the project:

the Voilà GitHub repository is available here: https://github.com/voila-dashboards/voila.
the Documentation is hosted on Read the Docs: https://voila.readthedocs.io.
the Team Compass holds the calendar for the public developer meetings, as well as the meeting minutes: https://voila-dashboards.github.io.
the Announcement of the first Voilà release was published on this blog: https://blog.jupyter.org/and-voilà-f6a2c08a4a93

Acknowledgements

Voilà was started by the team of open-source developers at QuantStack as a separate project, but with the full intent to incorporate it into Jupyter. The initial project development at QuantStack was funded by Bloomberg.
Now, Voilà contributors work in many institutions, including UC Berkeley, Cal Poly San Luis Obispo, JP Morgan, and Faculty (formerly ASI Data Science).
The Voilà Gallery is kindly hosted by OVH.

Configure your dashboards with Voilà gridstack template

2019-11-11T14:03:00+00:00

Voilà is a new dashboarding solution from Jupyter ecosystem. It provides an easy-to-use tool to convert your Jupyter notebooks into standalone web applications. If you have not used it before, you can learn more about Voilà from this blog post.

And voilà… the dashboard templates

To create interactive and engaging dashboards, you can add graphs, interactive widgets, maps etc. to your notebook. Voilà will turn them into interactive applications by stripping any code and displaying the outputs in the order they appear in the notebook. If you need more flexibility over the position of the cell outputs, you can use one of the widget layout templates defined in the ipywidgets library. If this is not enough, with Voilà you can even turn your notebooks into interactive presentations. Would you also like to re-configure your dashboards the drag-and-drop way? Et voilà, the gridstack template.

Creating ad-hoc dashboards with gridstack

If you have never used layout templates and just want to use Voilà with your existing notebooks, you can consider the new gridstack template for Voilà dashboards. Simply run the following command with the path to your notebook:

voila --template=gridstack my_notebook.ipynb --VoilaConfiguration.resources='{“gridstack”: {“show_handles”: True}}'

This will open a dashboard created from your notebook in a brower. By default the output cells of the notebook are laid out vertically. But you can move and resize them freely by dragging one of the handles in the corners of the cells.

An example notebook rendered with Voilà gridstack template. The layout was configured by dragging and resizing the cells of the notebook. The notebook was downloaded from LIGO project: https://github.com/losc-tutorial/Data_Guide

Positioning widgets with metadata

When you are done with configuring your dashboard, Voilà enables you to persist it and a create static layout of the widgets. To achieve that you will need to edit manually the notebook metadata, but we are also planning to release a tool that will simplify the process.

For example, you can add the following attributes to one of the cells (to edit the cell metadata, you need to activate the “Edit metadata” button from the View -> Cell toolbar menu of your notebook):

{
  "extensions": {
    "jupyter_dashboards": {
      "version": 1,
      "views": {
        "grid_default": {
          "col": 0,
          "height": 15,
          "hidden": false,
          "row": 9,
          "width": 4
        },
        "report_default": {}
      }
    }
  },
  "trusted": false
}

Example metadata

In Jupyter lab ≥ 1.0 you can edit the metadata using “Advanced Tools” section of “Notebook tools” sidebar (wrench icon).

Then you can start Voilà with the following command:

voila --template=gridstack my_notebook.ipynb

This should open your dashboard with cells in the specified positions and of specified sizes.

Final layout of the dashboard configured with cell metadata. The cells are not movable in this dashboard.

Supporting legacy notebooks

The metadata follow the specification of the legacy jupyter-dashboards project, which was an earlier solution for creating interactive dashboards. Unfortunately, the project is not maintained any more and it won’t work with the recent installations of Jupyter. However, you can open your notebooks created with jupyter-dashboards without changes with Voilà gridstack template to achieve identical rendering and give a second life to your Jupyter dashboards.

(To compare the outputs, you can open the notebook with binder that provisions the jupyter-dashboards ecosystem installed in an old version of Anaconda (2017). You can also use its design tool to lay out your widgets visually and save the cell metadata usable with Voilà gridstack template).

Design tool implemented in legacy jupyter-dashboards project.

How to install

If you want to try out the template yourself, please install it now with:

pip install voila-gridstack (for pip users) or

conda install voila-gridstack (for conda/anaconda users).

You can also try out the interactive examples with our gridstack binder.

And if you have any questions or want to share your experience please reach out on our Gitter chat.

Credits

The development Voilà and gridstack template was initiated by the amazing team at QuantStack that also provided financial and brain-power support.

About the author

Bartosz Telenczuk is a seasoned Python developer and a data scientist. He is an ardent user of Jupyter ecosystem and frequent contributor to open source software; among his projects is the svgutils library for composing SVG files in Python.

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.

A Gallery of Voilà Examples

2019-07-09T10:53:00+00:00

Voilà is one of the latest addition to the Jupyter ecosystem and can be used to turn notebooks into standalone applications and dashboards.

Today we are pleased to introduce the Voilà Gallery, a collection of examples built with Voilà.

The Voilà Gallery

The Voilà Gallery is a collection of live dashboards built with Voilà and Jupyter widgets.

The goal of the gallery is to provide inspiration to Jupyter users who want to convert their notebooks into web applications. Most of the examples rely on widget libraries such as ipywidgets, ipyleaflet, ipyvolume, bqplot and ipympl, and showcase how to build complex web applications entirely based on notebooks.

The landing page of the gallery lists all the available examples. Each entry contains can be used to launch the example and includes a button to view the source.

The Voilà Gallery landing page

Launch Example will bring you to the interactive application. Under the hood, a notebook server running voila and a live kernel are started.

GPX Viewer is an application built with Voilà

View Source will let you have a look at the source notebook used to create the example. This is useful to learn more about the inner workings of each dashboard.

Adding your own example

The source for the public gallery is available on GitHub: https://github.com/voila-gallery/voila-gallery.github.io

All the examples shown in the gallery come from the gallery.yaml file, which is automatically rendered on the landing page at voila-gallery.org.

You can contribute a new example to the gallery by following these steps, which consist in adding a new entry to the gallery.yaml file and opening a new pull request. The gallery will pick up the new example shortly after it has been added.

The voila-gallery organization on GitHub already contains a few examples that you can use as a starting point.

Deploying your own gallery

The gallery can also be deployed as a plugin for The Littlest JupyterHub (TLJH), which is a JupyterHub distribution meant to be used on a single server.

The plugin makes use of the JupyterHub REST API to create a new JupyterHub service and to launch the examples.

You can actually deploy your own gallery by following the instructions in the README. Within a few minutes, you will have a Voilà gallery running on your own server. You could even run it on a private instance.

What’s next?

We are still iterating on the content of the gallery to add some variety to the types of application that can be created using widgets, Jupyter notebooks and Voilà.

If you have authored an interesting dashboard and would like to share it with the rest of the world, feel free to open a pull request to add it to the list of examples!

Acknowledgments

We are very grateful to OVH for hosting the Voilà Gallery on their servers.

Thanks to Yuvi Panda and Pascal Bugnion for initially starting the Voilà Gallery project, and QuantStack for kindly sponsoring the development.

The development of Voilà at QuantStack is funded by Bloomberg.

And voilà!

2019-06-11T17:42:00+00:00

… from Jupyter notebooks to standalone applications and dashboards

The goal of Project Jupyter is to improve the workflows of researchers, educators, scientists, and other practitioners of scientific computing, from the exploratory phase of their work to the communication of the results.

But interactive notebooks are not the best communication tool for all audiences. While they have proven invaluable to provide a narrative alongside the source, they are not ideal to address non-technical readers, who may be put off by the presence of code cells, or the need to run the notebook to see the results. Finally, following the order as the code often results in the most interesting content to be at the end of the document.

Another challenge with sharing notebooks is the security model. How can we offer the interactivity of a notebook making use of e.g. Jupyter widgets without allowing arbitrary code execution by the end user?

We set ourselves to solve these challenges, and we are happy to announce the first release of Voilà.

Voilà turns Jupyter notebooks into standalone web applications.

Voilà supports Jupyter interactive widgets, including the roundtrips to the kernel.
Voilà does not permit arbitrary code execution by consumers of dashboards.
Built upon Jupyter standard protocols and file formats, Voilà works with any Jupyter kernel (C++, Python, Julia), making it a language-agnostic dashboarding system.
Voilà is extensible. It includes a flexible template system to produce rich application layouts.

Installation and first-time use

Voilà can be installed from pypi:

pip install voila

or conda-forge:

conda install voila -c conda-forge

Upon installation, several components are installed, one of which is the voila command-line utility. You can try it by typing voila notebook.ipynb. It results in the browser opening to a new tornado application showing markdown cells, rich outputs, and interactive widgets.

From a notebook to a standalone web application

As you can see in the screencast, Jupyter interactive widgets remain fully functional even when they require computation by the kernel.

You can immediately try out some of the command-line options to Voilà

with --strip_sources=False, input cells will be included in the resulting web application (as read-only pygment snippets).
with --theme=dark, Voilà will make use of the dark JupyterLab theme, which will apply to code cells, widgets and all other visible components.

Making use of the dark theme and including input cells

Note that code is only shown, voilà does not allow users to edit or execute arbitrary code.

Voilà’s execution model

The execution model of Voilà is the following: upon connection to a notebook URL, Voilà launches the kernel for that notebook, and runs all the cells as it populates the notebook model with the outputs.

The execution model of Voilà

After the execution, the associated kernel is not shut down. The notebook is converted to HTML and served to the user. The rendered HTML includes JavaScript that establishes a connection to the kernel. Jupyter interactive widgets referred in cell outputs are rendered and connected to their counterpart in the kernel. The kernel is only shut down when the user closes their browser tab.

The current version of Voilà only responds to the initial GET request when all the cells have finished running, which may take a long time, but there is ongoing work on enabling progressive rendering, which should make it into a release soon.

An important aspect of this execution model is that the front-end does not determine what code is run by the backend. In fact, unless specified otherwise (with option --strip-sources=False), the source of the rendered notebook does not even make it to the front-end. The instance of the jupyter_server instantiated by Voilà actually disallows execute requests by default.

Support for custom interactive widgets

Voilà can render custom Jupyter widget libraries, including (but not limited to) bqplot, ipyleafet, ipyvolume, ipympl, ipysheet, plotly, ipywebrtc, etc.

Including bqplot figures with Voilà

Together with ipympl, Voilà is actually a simple means to render interactive matplotlib figures in a standalone web application:

Rendering interactive matplotlib figures in a web application with voilà

Voilà is language-agnostic

Voilà can be used to produce applications with any Jupyter kernel. The following screencast shows how Voilà can be used to produce a simple dashboard in C++ making use of leaflet.js maps, with the xeus-cling C++ kernel and the xleaflet package.

A standalone Voilà page making use of the C++ Jupyter kernel, xeus-cling (input cells display enabled).

We hope that Voilà will be a stimulant to other languages (R, Julia, JVM/Java) to provide stronger widgets support.

Richer layouts with Voilà templates

The main extension point to Voilà is the custom template system. The HTML served to the end-user is produced from the notebook model by applying a Jinja template, which can be defined by the user.

An example template for voilà is the voila-gridstack template, which can be installed from pypi with

pip install voila-gridstack

You can try it by typing voila notebook.ipynb --template=gridstack.

Making use of the Gridstack template to produce a dashboard with bqplot charts

The gridstack Voilà template makes use of the cell metadata to lay out the application.

A roadmap item for the gridstack Voilà template is to support the entire spec for the deprecated jupyter dashboards and to create a WYSIWYG editor for these templates in the form of a JupyterLab extension.

Note that voila-gridstack template is still at an early stage of development.

How to make custom Voilà templates?

A Voilà template is actually a folder placed in the standard directoryPREFIX/share/jupyter/voila/templates and which may include

nbconvert templates (the jinja templates used to transform the notebook into HTML)
static resources
custom tornado templates such as 404.html etc.

All of these are optional. It may also contain a conf.json file to set up which template to use as a base. The directory structure for a Voilà template is the following:

PREFIX/share/jupyter/voila/templates/template_name/
|
├── conf.json                # Template configuration file
├── nbconvert_templates/     # Custom nbconvert templates
├── static/                  # Static directory
└── templates/               # Custom tornado templates

The Voilà template system can be used to completely override the behavior of the front-end. One can make use of modern JavaScript frameworks such as React or Vue.js to produce modern UI including Jupyter widgets and outputs.

Another example template for Voilà is voila-vuetify, which is built upon vue.js:

The voila-vuetify template makes use of Vue.js

The voila-gridstack and voila-vuetify templates are still at an early stage of development, but will be iterated upon quickly in the next weeks as we are exploring templates.

A Jupyter server extension

Beyond the voila command-line utility, the Voilà package also include a Jupyter server extension, so that Voilà dashboards can be served alongside the Jupyter notebook application.

When Voilà is installed, a running Jupyter server will serve the Voilà web application under BASE_URL/voila.

The Jupyter Community Workshop on Dashboarding

From June 3rd to June 6th 2019, a community workshop on dashboarding with Project Jupyter took place in Paris. Over thirty Jupyter contributors and community members gathered to discuss dashboarding technologies and hack together.

The participants to the Paris Jupyter community workshop on dashboarding

Several dashboarding solutions such as Dash and Panel were presented during the workshop and featured at the PyData Paris Meetup which was organized on the same week.

The workshop was also the occasion for several contributors to start working on Voilà. Custom templates, a dashboard gallery, logos and UX mockups for JupyterLab extensions have been developed.

We will soon publish a more detailed post on the workshop, detailing the many tracks of development that have been explored!

What is coming?

There is a lot of planned work around Voilà in the next weeks and months. Current work streams include better integration with JupyterHub for publicly sharing dashboard between users, as well as JupyterLab extensions (a Voilà “preview” extension for notebooks, and a WYSIWYG editor for dashboard layouts). There are also ongoing discussions with the OVH cloud provider (which already supports binder by handling some of its traffic) on hosting a binder-like service dedicated to Voilà dashboards. So stay tuned for more exciting developments!

Last but not least, we are especially excited about what you will be building upon Voilà!

Acknowledgments

The development of Voilà and related packages at QuantStack is sponsored by Bloomberg.

We are also grateful to the attendees of the Jupyter Community Workshop on Dashboarding for their numerous contributions to Voilà!

We would like to thank Chris Holdgraf for his work on improving documentation, and integration with JupyterHub.

We should mention Yuvi Panda and Pascal Bugnion for getting the voila-galleryproject off the ground during the workshop. We are grateful to Zach Sailer for his continued work on improvingjupyter_server. We should finally not forget to mention the prior art by Pascal Bugnion with the Jupyter widgets server which was also an inspiration for Voilà.

About the Authors

Sylvain Corlay is the founder and CEO of QuantStack and a core team member for Project Jupyter.

Maarten Breddels is an independent scientific software developer partnering with QuantStack on numerous projects, and a core developer of Project Jupyter.