Introduction
Jupyter notebooks are documents that enable the recording and sharing of computational ideas. Often, such ideas are developed and shared by teams of people, distributed throughout the world, collaborating in multiple ways at multiple time scales. Sometimes one person makes changes and proposes them to the project via a version control system such as git, which we can call “long-term collaboration”. At other points during the work, contributors may want to work together on the document at the same time, which we call “real-time collaboration.” Collaboration is a key part of the development and dissemination of computational ideas, so it is important for Jupyter notebooks to be well suited to these tasks.
Scenario
Ash and Fatima are collaborating on a project. They have developed a model, and have some demonstrations to run, illustrating how their model works, and running it through some sample tasks with visualisations. Fatima has some changes to make to the demonstration and would like Ash’s feedback.
For this, Ash needs to:
- See Fatima’s changes in context of the previous version of the document
Ash reviews Fatima’s changes and would like to discuss them further, iterating on the changes to come to a conclusion that both can agree on.
For this second part, Ash and Fatima need to:
- Both be able to execute and edit the document together
Suggestion of solution
- They use a Jupyter notebook for the demonstration of the model, to encapsulate prose, code, and outputs in one place.
- They publish the work as a git repository, enabling review of changes step-by-step as they are made.
- Ash uses nbdime to review Fatima’s changes in the repository.
- They use nbval to validate each change to notebooks via Continuous Integration service such as TravisCI.
- Ash and Fatima use JupyterLab for real-time collaboration to work through rapid feedback and come to a resolution.
Discussion
By using Jupyter notebooks, the illustration of the model can be a single container for prose explanation, implementation in code, and visualisations of results. Further, it can be shared as an interactive document for others to download, execute, and modify, either in their own environments, or online with zero installation via services such as Binder.
Time and expertise required
Assuming the team is familiar with version control and Jupyter (basic lab skills taught at Software Carpentry, and is fluent in using Jupyter notebook, the initial setup of the collaboration could be done in a few minutes. For live collaboration, a notebook server to which both contributors can connect would need to exist. JupyterHub can be used for this, or for short-term collaboration, mybinder.org may be used with zero installation.
What’s new since OpenDreamKit started
- Expansion of the Jupyter technology;
- Introduction of nbdime package for reviewing notebooks in version control;
- Introduction of nbval package for reviewing notebooks in version control;
- Prototype of real-time collaboration in JupyterLab
OpenDreamKit contribution
- Development and contributions to Jupyter interfaces (kernels) for math software (GAP, Pari/GP, SageMath, Singular) and C++; see D4.7.
- Development of nbdime for reviewing notebooks in version control, see D4.6
- Development of nbval for testing notebooks, see D4.8
- Prototype of real-time collaboration in JupyterLab, see D4.15
Jupyter Use Cases Open Science and Reproducibility Best Practice Reproducibility