Fork me on GitHub

Jupyter and JupyterLab: Sharing notebooks

Overview

Teaching: 10 min
Exercises: 0 min
Questions
  • How can I share notebooks with colleagues and the community?
Objectives
  • See what platforms and services exist to share Jupyter notebooks
  • Have a final discussion on notebooks in research.

Sharing notebooks

Note: the Google, Microsoft and CoCalc platforms are free but have paid subscriptions for faster access to cloud resources

Exercise: Making your notebooks reproducible by anyone via Binder

  • Create a requirements.txt file in your notebook repository, e.g.:
    ipywidgets==7.4.2
    numpy==1.16.4
    matplotlib==3.1.0
    
  • Commit and push.
  • Visit https://mybinder.org, and paste in the URL of your notebook repository.
  • Click on the arrow next to the “Copy the text below …” to expand it.
  • Copy the markdown line which begins with [![Binder](https://mybinder.org/badge_logo.svg)], and paste it into a README.md file for your notebook repository. Commit and push it.
  • Check that your notebook repository now has a “launch binder” button in your README file on GitHub
  • Try clicking the button and see how your repository in launched on Binder. Your notebooks can now be expored and executed in the cloud.
  • Enjoy being fully reproducible!
  • As a side note you can also run RStudio directly on Binder (example).

(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 would this be better?

Recommendations for longer notebooks

Create a table of contents on top

You can do that using Markdown. This produces a nice overview for longer notebooks. Example: https://stackoverflow.com/a/39817243

How to make it possible to toggle showing code

It is possible to hide all the code and only show the output. This can be nice for notebook readers who don’t need/want to see the code:

from IPython.display import HTML

HTML('''<script>
code_show=true;
function code_toggle() {
 if (code_show){
 $('div.input').hide();
 } else {
 $('div.input').show();
 }
 code_show = !code_show
}
$( document ).ready(code_toggle);
</script>
<form action="javascript:code_toggle()"><input type="submit" value="Click here to toggle on/off the raw code."></form>''')

Final discussion

  • If you are already using Jupyter, what tasks do you use it for?
  • If you are new to Jupyter, do you see any possible use cases?
  • Do you think Jupyter Notebooks can help tackle the problem of irreproducible results?

But Notebooks have some pitfalls:

  • They don’t promote modularity, and once you get started in a notebook it can be hard to migrate to modules.
  • They are difficult to test. There are things to run notebooks as unit tests like nbval, but it’s not perfect.
  • Notebooks can be version controlled (nbdime helps with that), but there are still limitations.
  • You can change code after you run it and run code out of order. This can make debugging hard and results irreproducible if you aren’t careful.
  • Notebooks aren’t named by default and tend to acquire a bunch of unrelated stuff. Be careful with organization!
  • Once lots of code is in notebooks, it can be hard to change to proper programs that can be scripted.