Introduction to Jupyter Notebooks#

Today we are going to learn about Jupyter Notebooks! The advantage of notebooks is that they can include explanatory text, code, and plots in the same document. This makes notebooks an ideal playground for explaining and learning new things without having to jump between several documents. You will use notebooks a LOT during your studies, and this is why I decided to teach you how they work very early in your programming journey.

This document itself is a notebook. It is a simple text file with a .ipynb file path ending. Notebooks are best opened in “JupyterLab”, the development environment that you learned about last week.

Note: learning about notebooks is less urgent than learning how to write correct code. If you are feeling overwhelmed by coding, you should focus on the coding exercises for now and learn about notebooks a bit later. They will only become mandatory in about 2 to 3 weeks.

Let’s start with a short video introduction, which will invite you to download this notebook to try it yourself:

First steps#

Have you downloaded and opened the notebook as explained in the video? If not, do that first and continue this lesson on your own latpop.

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'

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'
s = s + ' Python!'
# Lines which start with # are not executed. These are for comments.
'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! Type 'se' in the next row and press [TAB].

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 therefore 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 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 variables between each other). In certain situations (for example, if you got confused about the order of your cells and variables 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
NameError                                 Traceback (most recent call last)
/tmp/ipykernel_123666/ in <cell line: 3>()
      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. If you want to recover from the error, adress the problem (here a capsize issue) and re-run the cell.

Formatting your notebook with text, titles and formulas#

The default role of a cell is to run code, but you can tell the notebook to format a cell as “text” by clicking in the menu bar on “Cell”, choose “Cell Type” \(\rightarrow\) “Markdown”. The current cell will now be transformed to a normal text. Again, there is a keyboard shortcut for this: press [Ctrl+m] to enter in command mode and then [m] to convert the active cell to text. The opposite (converting a text cell to code) can be done with [Ctrl+m] to enter in command mode and then [y].

As we have seen, the notebook editor has two simple modes: the “command mode” to navigate between cells and activate them, and the “edit mode” to edit their content. To edit a cell you have two choices:

  • press [enter] on a selected (highlighted) cell

  • double click on a cell (any cell)

Now, try to edit the cell below!

A text cell is formatted with the Markdown format, e.g. it is possible to write lists:

  • item 1

  • item 2

Numbered lists:

  1. part a

  2. part b

Titles with the # syntax (the number of # indicating the level of the title:

This is a level 3 title (with 3 # symbols)#

Mathematical formulas can be written down with the familiar Latex notation:

\[ E = m c^2\]

You can also write text in bold or cursive.

Download a notebook#

Jupyter notebooks can be downloaded in various formats:

  • Standard notebook (*.ipynb): a text file only useful within the Jupyter framework

  • Python (*.py): a python script that can be executed separately.

  • HTML (*.html): an html text file that can be opened in any web browser (doens’t require python or jupyter!)

  • … and a number of other formats that may or may not work depending on your installation

To download a jupyter notebook in the notebook format (.ipynb), select the file on the left-hand side bar, right-click and select “Download”. Try it now!

For all other formats, go to the “File” menu, then “Export notebook as…”

Take home points#

  • jupyter notebooks consist of cells, which can be either code or text (not both)

  • one can navigate between cells in “control mode” ([ctrl+m]) and edit them in “edit mode” ([enter] or double click)

  • to exectute a cell, do: [shift+enter]

  • the order of execution of cells does matter

  • a text cell is written in markdown format, which allows lots of fancy formatting

These were the most important features of jupyter-notebook. In the notebook’s menu bar the tab “Help” provides links to the documentation. Keyboard shortcuts are listed in the “Palette” icon on the left-hand side toolbar. Furthermore, there are more tutorials on the Jupyter website.

But with the few commands you learned today, you are already well prepared for the rest of the class!