Sharing notebooks

Objectives

  • Learn how to share notebooks with colleagues and the community?

Instructor note

  • 10 min teaching

  • 20 min exercises


Sharing dynamic notebooks on Binder

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

  • Create a new GitHub repository.

  • Commit and push the notebook which we have created earlier to this repository. If you got stuck earlier, you can download this notebook (right-click, “Save as …”). You can also try Binder with a different notebook.

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

    matplotlib==3.4.1
    
  • Commit and push also this file to your notebook repository.

  • Visit https://mybinder.org:

    Screenshot of Binder web interface

    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!

  • Even better would be to get a DOI to your notebook and point Binder to the DOI.


Optional exercises

Importance of requirements file

(Optional) Exercise: what happens without requirements.txt?

Let’s look at the same activity inequality repository. We can start this repository in Binder by using this link.

  • Start the repository in Binder

  • fig3/fig3bc.ipynb is a Python notebook, so works in Binder. Most others are in R, which also works in Binder. But how? Try to run the notebook - can you make it work?

  • Install the missing requirements with pip. Does it work now? Why or why not?

  • How could this be better?

Sharing an interactive notebook on Binder

(Optional) Exercise: share an interactive (ipywidgets) notebook via Binder

  • Take the solution from the exercise “Widgets for interactive data fitting” in the Examples of Jupyter features episode and paste it into a notebook.

  • Push the notebook to a GitHub/GitLab repository.

  • Create a requirements.txt file in your notebook repository, e.g.:

    ipywidgets==7.4.2
    numpy==1.16.4
    matplotlib==3.1.0
    
  • Try to deploy this example via Binder in the same way as the above exercise.

Sharing R Markdown/Studio projects

(Optional) Exercise: share R Markdown/R Studio project via Binder

This exercise is for those who use Rmd files instead of Jupyter notebooks.

  • Put your Rmd file into a GitHub repository.

  • To this repository add a file runtime.txt which specifies the R version you want to use:

    r-3.6-2020-10-13
    
  • To this repository add a file install.R which lists the dependencies, for instance:

    install.packages(c("readr", "ggplot2"))
    
  • After you have done that, visit https://mybinder.org/v2/gh/myuser/myrepo/mybranch?urlpath=rstudio (adapt “myuser”, “myrepo”, and “mybranch”).

  • For more information, see this guide.


Different ways to share a notebook

  • 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.

  • 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

Commercial offers with free plans

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