Jupyter notebook

This material is adapted from the OGGM-Edu’s educational notebooks.

Welcome to this introduction to Jupyter Notebooks! The advantage of notebooks is that they can include explanatory text, code, and plots in the same document.

This makes of notebooks an ideal playground for explaining and learning new things without having to jump between several documents. Thanks to binder, you can run them in your web browser without requiring to install anything!

This document itself is a notebook. It is a simple text file with a .ipynb file path ending. If you opened this notebook via an Binder link, it is opened in a platform which is called JupyterLab. “JupyterLab” is the development environment allowing you to navigate between notebooks (navigation bar on the left), (re-)start them, and much more. Here, we will focus on the notebooks themselves.

First steps

At first sight the notebook looks like a text editor. Below this line, you can see a cell. The default purpose of a cell is to write code:

# Click on this cell, so that its frame gets highlighted
m = 'Hello'
print(m)
Hello

You can write one or more lines of code in a cell. You can run this code by clicking on the “Run” button from the toolbar above when the cell’s frame is highlighted. Try it now!

Clicking “play” through a notebook is possible, but it is much faster to use the keybord shortcut instead: [Shift+Enter]. Once you have executed a cell, the next cell is selected. You can insert cells in a notebook with the + button in the toolbar. Again, it is much faster to learn the keybord shortcut for this: [Ctrl+m] or [ESC] to enter in command mode (blue frame) then press [a] to insert a cell “above” the active cell or [b] for “below”.

Create a few empty cells above and below the current one and try to create some variables. Instead of clicking on a cell to enter in edit mode press [Enter].

You can delete a cell by clicking “Delete” in the “Edit” menu, or you can use the shortcut: [Ctrl+m] to enter in command mode then press [d] two times!

More cell editing

When you have a look into the “Edit” menu, you will see that there are more possibilities to edit cells, like:

  • copy / cut and paste

  • splitting and merging cells

and more.

a = 'This cell needs to be splitted.'

b = 'Put the cursor in the row between the variables a and b, then choose [split cell] in the "Edit" menu!'

Another helpful command is “Undo delete cell’, which is sometimes needed when the key [d] was pressed too fast.

Writing and executing code

The variables created in one cell can be used (or overwritten) in subsequent cells:

s = 'Hello'
print(s)
Hello
s = s + ' Python!'
# Lines which start with # are not executed. These are for comments.
s
'Hello Python!'

Note that we ommited the print commmand above (this is OK if you want to print something at the end of the cell only).

In jupyter notebooks, code autocompletion is supported. This is very useful when writing code. Variable names, functions and methods can be completed by pressing [TAB].

# Let's define a random sentence as string.
sentence = 'How Are You?'
# Now try autocompletion! Put the cursor behind the 'se' in the next row and press [TAB].
se
# Call methods of the string by typing "sentence." and pressing [TAB].
sentence.
# Choose for example the method lower() and see what happens when you execute the cell!
sentence.lower()
'how are you?'

An advantage of notebooks is that each single cell can be executed separately. That provides an easy way to execute code step by step, one cell after another. It is important to notice that the order in which you execute the cells is the order with which the jupyter notebook calculates and saves variables - the execution order therfore depends on you, not on the order of the cells in the document. That means that it makes a difference, whether you execute the cells top down one after another, or whether you mix them (cell 1, then cell 5, then cell 2 etc.).

The numbers on the left of each cell show you your order of execution. When a calculation is running longer, you will see an asterisk in the place of the number. That leads us to the next topic:

Restart or interrupt the kernel

Sometimes calculations last too long and you want to interrupt them. You can do this by clicking the “Stop button” in the toolbar.

The “kernel” of a notebook is the actual python interpreter which runs your code. There is one kernel per opened notebook (i.e. the notebooks cannot share data or variable between each other). In certain situations (for example, if you got confused about the order of your cells and variable and want a fresh state), you might want to retart the kernel. You can do so (as well as other options such as clearing the output of a notebook) in the “Kernel” menu in the top jupyterlab bar.

Errors in a cell

Sometimes, a piece of code in a cell won’t run properly. This happens to everyone! Here is an example:

# This will produce a "NameError"
test = 1 + 3
print(tesT)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-9-9d2bf95108c6> in <module>
      1 # This will produce a "NameError"
      2 test = 1 + 3
----> 3 print(tesT)

NameError: name 'tesT' is not defined

When a cell ends with an error, don’t panic! Nothing we cannot recover from. First of all, the other cells will still run (unless they depend on the output of the failing cell): i.e., your kernel is still active. I you want to recover from the error, adress the problem (here a capsize issue) and re-run the cell.

Displaying plots with matplotlib

The most widely used plotting tool for Python is Matplotlib. Its syntax is inspired from Matlab and might be familiar to a few:

# First we need the next line to tell the notebook: display plots in the notebook.
%matplotlib inline

# Now, we import matplotlib:
import matplotlib.pyplot as plt

# We import also the package called numpy (that helps us to play with numbers).
import numpy as np
# Let's plot something nice:

# Define a square function of x
x = np.linspace(-1, 1)
y = np.sqrt(1-x**2)
# Plot it.
plt.plot(x, y)
plt.title('My first plot in a notebook');
../_images/jupyter_31_0.png

Interactive plots with Bokeh

Bokeh is a plottling library made for the web. It uses another syntax than matplotlib and can be used to display interactive plots. In OGGM-Edu, we sometimes prefer to use interactive plots as they allow to explore the data after plotting it. Here is an example:

# hvplot is a plotting library relying on bokeh
# you'll need to install it alongside with pandas for this cell to work
import hvplot.pandas

# pandas is a very useful data analysis library
import pandas as pd

# This makes the plot
ts = pd.Series(index=x, data=y)
ts.hvplot().opts(title='An interactive plot', width=500)