Jupyter Blog - Bartosz Telenczuk

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.

Introducing templates for Jupyter widgets layouts

2019-07-04T09:41:00+00:00

Notebooks come alive with Jupyter widgets, which allow users to produce interactive GUIs inline in the Jupyter notebook or JupyterLab.

You can either use them to add a few interactive controls and plots in notebooks or to create fully-fledged applications and interactive dashboards. Both can be built with components from the core built-in widgets such as buttons, sliders, and dropdowns, or with the rich ecosystem of custom widget libraries that built upon the Jupyter widgets framework, such as interactive maps with ipyleaflet or 2-D plots with bqplot. You can also combine several types of widgets together to create even richer applications.

Have you ever tried creating complex widget layouts with multiple widgets placed at specific locations? The preferred approach so far has been to use nested HBox and VBox widgets to compose your layout, which can make creating complex applications a tedious task. We now have a more flexible solution: the layout templates, which just landed with the latest release of the ipywidgets package.

The power of CSS, the simplicity of Python

Layout templates are a set of predefined layouts that allow you to combine multiple widgets on a single screen and arrange them visually. They leverage the powerful CSS Grid Layout specification, which is supported on most current browsers (yes, we are looking at you IE).

While the CSS Grid properties were first introduced in ipywidgets 7.3, they were tricky to use as they were transparently reflecting the CSS Grid Spec API and required the knowledge of the CSS. The new layout templates of ipywidgets wrap the CSS properties with a pythonic interface and sensible defaults, so they never expose the user to the nasty CSS spec. However, they inherit all the advantages of the Grid being fully responsive (they adapt to the screen size) and super easy to use!

Comparing the Python code with the generated CSS layout.

Application-like UIs in Jupyter

AppLayout consists of a header, two side panes, a central pane, and a footer.

If you want to create a simple application-like layout, you can use AppLayout, which consists of a header, a footer, two side panes, and a central pane. You can create the layout and populate it with widgets in a single command:

AppLayout(header=header,
          left_sidebar=prev_button,
          center=image,
          right_sidebar=next_button,
          footer=footer,
          grid_gap='20px',
          justify_items='center',
          align_items='center')

Importantly, if your application does not need all the panes defined by AppLayout, the layout has also some sensible defaults so that it can automatically merge widget locations that were not assigned.

Widgets on a grid

GridspecLayout places widgets on a rectangular grid. A single widget can span several rows or columns (or both).

If you require more flexibility to arrange widgets, you can also try GridLayout. First, you define the dimensions of a rectangular grid. Then you can place widgets on the grid either in a single cell of the grid or spanning several rows or columns (or both). This is easily achieved using the same slice-based API that you already use to select items from a NumPy array (or Python lists). If you already know matplotlib’s GridSpec feature, the syntax may look familiar:

# create a 10x2 grid layout
grid = GridspecLayout(10, 2)

# fill it in with widgets
grid[:, 0] = map
grid[0, 1] = zoom_slider
grid[1, 1] = basemap_selector
grid[2:, 1] = fig

# set the widget properties
grid[:, 0].layout.height = 'auto'

Style me up

The layouts are very configurable and can be easily tuned to the needs of your application. To change the sizes of the layout and the grid intervals, you can use style attributes, such as height , width, and gap-size options:

AppLayout(grid_gap='20px',
          height="200px",
          width="50%")

The size units are directly inherited from the CSS standard. More examples of style attributes can be found in the documentation.

So please go ahead and install the pre-release of ipywidgets that includes this new feature (pip install --upgrade ipywidgets) and take the new layout templates for a spin. We are looking forward to your feedback!

Acknowledgments

The author is a seasoned Python developer and a data scientist. He loves contributing to open source software; among others he is the creator and maintainer of the svgutils library.

The development of the ipywidgets layout templates was kindly supported by QuantStack.