Sharing notebooks

Objectives

• Know about good practices for notebooks to make them reusable

• Have a recipe to share a dynamic and reproducible visualization pipeline

Instructor note

• 20 min presentation and discussion

[this lesson is adapted from https://coderefinery.github.io/jupyter/sharing/]

Document dependencies

If you import libraries into your notebook, note down their versions.

It is customary to do this either in a requirements.txt file (example):

pandas==2.2.2
altair==5.3.0

… or in an environment.yml file (example):

name: example-environment
channels:
  - conda-forge
dependencies:
  - pandas=2.2.2
  - altair=5.3.0

Place either requirements.txt or environment.yml in the same folder as the notebook(s).

This is not only useful for people who will try to rerun this in future, it is also understood by some tools (e.g. Binder) which we will see later.

Different ways to share a notebook

We need to learn how to share notebooks. At the minimum we need to share them with our future selves (backup and reproducibility).

• You can enter a URL, GitHub repo or username, or GIST ID in nbviewer and view a rendered Jupyter notebook

• Read the Docs can render Jupyter Notebooks via the nbsphinx package

• Binder creates live notebooks based on a GitHub repository

• EGI Notebooks (see also https://egi-notebooks.readthedocs.io)

• JupyterLab supports sharing and collaborative editing of notebooks via Google Drive. Recently it also added support for Shared editing with collaborative notebook model.

• JupyterLite creates a Jupyterlab environment in the browser and can be hosted as a GitHub page.

• Notedown, Jupinx and DocOnce can take Markdown or Sphinx files and generate Jupyter Notebooks

• Voilà allows you to convert a Jupyter Notebook into an interactive dashboard

• The jupyter nbconvert tool can convert a (.ipynb) notebook file to:

  • python code (.py file)

  • an HTML file

  • a LaTeX file

  • a PDF file

  • a slide-show in the browser

These platforms can be used free of charge but have paid subscriptions for faster access to cloud resources:

• CoCalc (formerly SageMathCloud) allows collaborative editing of notebooks in the cloud

• Google’s Colaboratory lets you work on notebooks in the cloud, and you can read and write to notebook files on Drive

• Microsoft Azure Notebooks also offers free notebooks in the cloud

• Deepnote allows real-time collaboration

Sharing dynamic notebooks using Binder

Exercise/demo: Making your notebooks reproducible by anyone (15 min)

Instructor demonstrates this:

• Instructor creates a GitHub repository.

• Uploads a notebook file that we created in earlier episodes.

• Then we look at the statically rendered version of the notebook on GitHub and also nbviewer.

• Add a file requirements.txt which contains:

  pandas==2.2.2
  altair==5.3.0
  

• Visit https://mybinder.org:

  

• Check that your notebook repository now has a “launch binder” badge in your README.md file on GitHub.

• Try clicking the button and see how your repository is launched on Binder (can take a minute or two). Your notebooks can now be explored and executed in the cloud.

• Enjoy being fully reproducible!

Also please see how we share the notebooks from this lesson in the repository README.

How to get a digital object identifier (DOI)

• Zenodo is a great service to get a DOI for a notebook (but first practice with the Zenodo sandbox).

• Binder can also run notebooks from Zenodo.

• In the supporting information of your paper you can refer to its DOI.