Sharing notebooks

Objectives

• Know about good practices for notebooks to make them reusable

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

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

Document dependencies

• If you import libraries into your notebook, note down their versions. Document the dependencies as discussed in section Reproducible environments and dependencies.

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

• If you publish the notebook as part of a publication, it is probably a good idea to pin the versions of the libraries you use.

• 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

The following 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 Colab 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 on Binder

Exercise (20 min): Making your notebooks reproducible by anyone via Binder

• Create a new GitHub repository and click on “Add a README file”: https://github.com/new

• This exercise can be done entirely through the GitHub web interface (but using the terminal is of course also OK). You can use the “Add file” button to upload files.

Jupyter NotebooksR Markdown/R Studio project

• Download this notebook (right-click, “Save as …”) and upload it to this repository. You can also try this with a different notebook.

• Add also a requirements.txt file which contains (adapt this if your notebook has other dependencies):

  numpy==1.26.4
  matplotlib==3.4.1
  

• Visit https://mybinder.org:

  

  Screenshot of Binder web interface.

• Copy-paste the markdown text for the mybinder badge into a README.md file in your notebook repository.

• 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 expored and executed in the cloud.

• Enjoy being fully reproducible!

More examples with Binder:

• Binder documentation

• Collection of example repositories

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.