Share interactive Jupyter dashboards on a USB stick
How to deliver interactive notebooks to clients or colleagues when you never wanted to build a web app anyway…
A lot of data science visualizations are really throwaway web apps that aren’t intended to be public, or even cloud-based for private users. It’s not worth the infrastructure (and security risk) of locking down a hosting service to serve these given their short shelf-life. In fact, the web technologies employed are really only ‘borrowed’ from different scenarios where cloud or internet is important. It is only by accident that our visualizations were built with web-style technologies in the first place… so can we shift our thinking to take our head out of the clouds completely?
The culmination of your proof-of-concept data science project is a beautiful visualization in a Jupyter notebook. You’ve even included some slider widgets so you can change some parameters and instantly see how this affects the plot in the middle of your notebook, and how your model’s predictions change.
If you can just let your client slide the sliders around for a bit in their own time, you know they’ll completely understand what you’re trying to convey — and give the green light to move forward with the rest of the project.
But what’s the best way to give them access to your visualization on their own machine?
There are some great ways to publish notebooks as web-based cloud apps, including mybinder.org if you’re happy for everything to be public. But what if the data used by your notebook is confidential, and you don’t have permission to host it on arbitrary cloud-based services?
It would test the patience of even the most technologically-enthusiastic client to ask them to install conda on their machine and run a series of terminal commands to replicate your package environment. And the commands might need to vary depending on their operating system and existing installations.
A simple single file
You already have a system for sharing plain files with the client — maybe SharePoint or Dropbox has been set up for collaboration already, so perhaps there is a way to utilise that.
ContainDS Desktop is software for Windows or Mac that allows you to run isolated Jupyter environments on your local machine. It now lets you export your Jupyter workspace and package environment as one single self-contained file, such that it can be imported straight back into ContainDS Desktop running on someone else’s computer — and present them with the exact environment and notebook files that were already running just as you wanted them on your own machine.
This article shows how you might create an interactive Jupyter visualization and then export it and share it with your client as a simple file so they can easily run it just as intended.
To install ContainDS Desktop and start a simple ‘container’ ready for us to install some packages and write some new notebooks, first follow the ContainDS Desktop Getting Started tutorial. This will also guide you through installing Docker, which is used by ContainDS Desktop under the hood.
New Container
If you stepped through the Getting Started tutorial closely, you should already have ended up with a new JupyterLab environment which should be open in a browser window. You can just use that existing container if you prefer or keep following to start a new one.
A container in ContainDS Desktop is just a Jupyter package environment (e.g. where numpy and pandas can be installed) combined with a workspace where your notebooks and other data reside.
In ContainDS Desktop, click on the ‘+ NEW’ button to see some starting points you can use for your new container. Click ‘SELECT’ next to ‘minimal-notebook’.
On the next screen, you will be asked how you want the workspace to be stored. To ensure your notebook files are easily accessible from your local hard drive, choose a new folder — perhaps named ‘dsworkspace’ within your home folder, but really this can be anywhere you like.
Click ‘CREATE’, then the new container will be started and listed along the left-hand side of ContainDS Desktop. It might take a bit of time if the ‘minimal-notebook’ starting point image needs to be downloaded first.
Once it’s ready, click the ‘WEB’ button to launch into JupyterLab.
Installing Packages
In JupyterLab, click on the Terminal icon to open a new command shell tab.
To install the packages we need, enter the following commands:
conda install -c anaconda numpy --yes
conda install -c anaconda ipywidgets --yes
conda install -c anaconda matplotlib --yes
jupyter labextension install @jupyter-widgets/jupyterlab-manager
Once everything is installed, reload the Jupyter Lab browser window to ensure the newly-installed Javascript is running.
Writing our Notebook
Click the ‘+’ button, and this time click on the ‘Python 3’ icon to open a new notebook tab.
Copy and paste the cells from our sample notebook on GitHub here. Remember it’s shift+enter to run each cell after you’ve pasted the code.
The notebook provides a slider so the user can choose different values of the parameter ‘t’. As you change the values, the sin(t*x) and cos(t*x) plots shift based on the coefficient ‘t’. Wow, this could really teach someone some new mathematics! If you haven’t come across them, interactive widgets are a very powerful visualization feature of Jupyter notebooks that can really immerse the user in the numbers.
Save the ipynb notebook as a file named Presentation.ipynb or whatever suits you.
Exporting as a plain old file
OK, we’ve installed the packages that we need and created our interactive notebook. Now we come to the whole point of this article. How can we share it directly with a client so they can interact with it to their heart’s content on their own machine?
You can close the JupyterLab browser window if you wish.
Back in the ContainDS Desktop application, our container should still be highlighted in the left-hand panel. Click on the ‘Share’ tab. The ‘Export’ sub-tab should be visible, asking for a folder location where the ‘.containds’ file should be written.
The default of your Downloads folder should be fine, so just click ‘EXPORT’.
You should see some output while the container is committed and exported. Finally, the full filename of the saved ‘.containds’ file will be displayed.
Share with your friends!
The file saved in the last step will be large (maybe 5GB) so it can’t be sent over email. Hopefully, you will have a collaboration service already set up that you can use to share the ‘.containds’ file. SharePoint, Dropbox, Google Drive etc should all be suitable if approved by your organisation. Or a USB stick might be most suitable if you are trying to avoid cloud services.
Your recipient will also need to install ContainDS Desktop. Once running, they should click on the ‘File’ tab in the ‘+ NEW’ screen. Locate the ‘.containds’ file you shared with them, then click ‘START’. Some logs will be displayed while the file is processed.
Once complete, the container will start and ContainDS Desktop will show you the new container’s log screen. Click ‘WEB’ to open the notebook in JupyterLab just as it was when you left it.
Your colleague or client can interact with the slider just as you intended!
Conclusion
As discussed at the start of this article, many data visualizations aren’t really suited to web technologies in the first place — it’s only by accident and familiarity that we are employing them for our throwaway apps anyway.
The focus in the tutorial above was on reproducibility — faithfully transmitting the exact computing environment, files, and data that we experienced on our own computers. But there are certainly drawbacks that need to be overcome in this process.
Most obviously, the end user needs to install some software on their own machine: ContainDS Desktop which also requires Docker to be running in the background.
And then we brushed over the fact that the ‘.containds’ file itself was 5GB.
There are potential solutions to these problems. To reduce the installation requirements, it is noteworthy that Docker is based on open source software that could be streamlined and bundled into ContainDS itself — so maybe only the one installer would be required, and the user wouldn’t need to worry about ensuring Docker is running in the background.
ContainDS Desktop itself is a relatively simple UI for a technical user such as a typical data scientist, but there is more power there than is needed by the non-technical end user of your Jupyter ‘web app’. It would be possible to build a cut-down ‘ContainDS Viewer’ version of the software that simplifies things for the end user. It could also use a more friendly front-end such as Voilà so that the end user doesn’t need to worry about code cells and pressing shift+enter through the notebook.
The field of data science has popularised these types of throwaway web apps, and there have been many exciting developments in data visualization tools as the subject grows in scope. I look forward to hearing your thoughts as to how the approaches introduced in this article might work for you. What obstacles prevent you from sharing your visualizations easily with your colleagues and clients?
For any questions or feedback about ContainDS Desktop please get in touch through our website.
