Introduction
Jupyter Notebooks are a web based application that enables users to create and share documents containing code, data visualisations and text in different programming languages. The structure of the notebook makes them useful for describing and record keeping of code execution and figures, helping maintain the reproducibility of the software. This format also suits the production of documentation and teaching, combining text and code within one document.
This workshop presents an introduction to Jupyter Notebooks and three packages which extend their functionality:
These packages were chosen for their relevance to scientific computing: for the sharing of outputs, allowing version control and validation of documentation produced using the notebook. nbconvert allows the user to convert a Jupyter Notebook into different formats, such as PDF, LaTeX and many more. nbdime is a tool used to see the differences between two notebooks (diffing) or to merge two notebooks. Lastly, nbval is a plugin for pytest which validates the execution of the notebook by checking the output.
nbconvert and nbdime are the main tools for the conversion of notebooks into different formats, and diffing and merging. nbval is one of a number of tools which give the ability to test notebooks. pytest-ipynb allows cells to be defined as tests, which can then be executed using the standard pytest procedure. ipython_nose is a similar extension which allows the execution of Nose tests using the notebook. nbval will be presented here as it fits into the use of notebooks for documentation.
For this workshop, Python3 will be used. No previous knowledge of Jupyter Notebooks is required, however coding skills are a plus.
Tutorial
Learning Material and Exercises
All of the material created for this session is contained in Jupyter Notebooks. There is a main notebook which contains all of the learning material and exercises. This will guide you through using Jupyter Notebooks and the three packages listed above, ending with the exercises to practise what you have learnt. You can view that material here or see the download section below.
Supporting Material
A number of notebooks have been created to demonstrate the functionality of the three packages covered and will be referenced in the learning material.
Download
You can download all of this material from here and starting working through it.
Pre-Requisites
Installation on own machine
For working on your own machine, you will need:
- Python
- Jupyter Notebook
- nbconvert
- nbdime
- nbval (version >= 0.5.0)
Python
We would recommend installing Python using Anaconda. This gives you access to Python, a range of standard packages and pip (for installing further Python packages). If you do not want to install the full Anaconda distribution then you can use Miniconda which will install only a few basic packages to get you started.
Jupyter Notebook
- Anaconda - Jupyter Notebook comes as part of the Anaconda distribution
- pip - there is a metapackage called Jupyter which will install all of the necessary Jupyter packages
pip install jupyter
See here for further information on installing Jupyter.
nbconvert
-
In command line run:
pip install nbconvert
nbdime
nbval
- pip - nbval can be installed through pip:
pip install nbval
Virtual Machine
We have also created a virtual machine which contains all of the necessary software and material for the workshop. If you prefer you can use VirtualBox and download the virtual machine labelled feeg6003_jupyternotebook from here to complete the workshop.
Checking you're ready
The following steps allow you to check that you have Jupyter Notebook installed correctly and have the additional packages we are going to show you.
Opening Jupyter Notebook
In a terminal window:
This should open an instance of Jupyter Notebook which usually open automatically in your browser. The Jupyter Notebook instance has the default address http://localhost:8888/ so by typing this into your browser you should also be able to access a running Jupyter Notebook.
nbconvert
If you installed nbconvert using command line, run the following lines to download and run the official tests.
pip install nbconvert[test]
py.test --pyargs nbconvert
Most of the tests shoud pass, with some few skipped and several warnings. It can be read by the warning messages that the tests are deprecated, and will be eliminated in the next version.
nbdime
If you installed nbdime using command line, run the following lines to download and run the official tests.
pip install nbdime[test]
py.test --pyargs nbdime
Most of the tests should pass, with some failing due to some libraries not being installed properly. Ignore this for now, as they do not affect the functionality.
nbval
For the functionality included in this workshop we need version 0.5.0 or greater. You can check your current version using:
If you have version 0.5.0 or greater then you have what you need.