Jupyter notebooks

Download the files 03_unit/Our_first_notebook.ipynb and 03_unit/JupyterNB_md_cheatsheet.png and place them in the directory $SCIPRO/03_unit/. Open the notebook file with the ending .ipynb with JupyterLab.

Using Jupyter Notebooks in JupyterLab

The content of this notebook is informed by Fabien Maussion’s lecture matrial on Jupyter Notebooks.

Jupyter Notebooks are self-contained dynamic documents that combine code, explanatory text, and visualizations in an interactive format. They are powerful tools to support data analysis in an interactive way. In the course of your Master’s program, sharing dynamic documents with your colleagues and teachers allows you to provide them with both the code of your data analysis and the discussion of your findings at the same time. Furthermore, notebooks are ideal playgrounds for explaining and learning new things without having to jump between several documents.

Jupyter Notebooks are files with the ending .ipynb. In contrast to .py files that we dealt with so far, .ipynb files cannot meaningfully be viewed in simple text editors (although they are simple text files—you should open an .ipynb file with your text editor once..). Luckily, JupyterLab is designed to excel in working with these types of files. If you want to share a notebook with somebody who cannot view .ipynb files, just convert it to PDF or HTML. It’s as easy as clicking a button at File – Save and Export Notebook As….

Elements of a notebook

Jupyter Notebooks consist of a series of cells. Each cell can be devoted to narrative text or programm code but not both. The text you are reading right now, for example, is part of the first cell of this notebook, and I devoted it to text. Any cell can be filled with as much content as you like.

Narrative text

To format text, Jupyter Notebooks use Markdown, a lightweight plain-text markup language. You might think: “Uff, yet another language I have to learn..”, but don’t worry, it was designed to be easy to read and write, and you will quickly get the gist of it! If you want to understand how it works, I invite you to double-click on the text you’re reading right now to move into text editing mode. This will stop rendering the text “nicely” with headings, italic and bold fonts, etc, but will display the raw markdown. And as you see, it doesn’t look overly complicated.

Let me give you an example: This sentence is rendered with italic font, while this one will be bold. As you see, you will have to learn just a tiny bit of markdown syntax to be able to structure and format your narrative text cells.

Intermezzo: Cell navigation

We will dive a bit deeper into markdown syntax later, but before we move on to Code cells, I should tell you how you can run the cell you’re currently editing. Either you click the “Play” button in the top notebook bar or you use the keyboard shortcut [Ctrl+Enter] to run the current cell. If you are editing a markdown cell, this will render the text. If you are editing a code cell, it will execute the code. Upon running the cell, you will find yourself in command mode, where you can either choose to step back into editing mode of the current cell by double-clicking on the cell or pressing [Enter]. In command mode, you can also choose to insert a new cell above the currently selected cell ([a]), or below ([b]), or you can navigate between cells with the [Arrow-up] and [Arrow-down] keys. (Note, if you want to enter command mode without actualy running the cell, you can press [ESC] or [Ctrl+m]).

Any new created cell will be a code cell to start with. To change that, use the dropdown menu at the top of the notebook. If you’re in command mode, you can also use the keyboard shortcuts [m] for changing a cell to a markdown cell, or [y] for changing it back to code.

To delete a cell, go into command mode and press [d] twice, or click Cut this cell in the top notebook bar.

Code

After the coding experience we’ve gained so far, writing code in a notebook will be super easy! Just create a code cell and rest assured that you’re talking to the ipython interpreter! You will even see the ipython prompt. Actually, I think it’s time that we do create a code cell:

your_name = "Florian"
print("Hello " + your_name)

Hello Florian

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

your_name = "Babette"
print("Hello " + your_name)

Hello Babette

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 indicate 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 interrup 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 notebook 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: 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.

A brief motivating example with a figure

import numpy as np
import matplotlib.pyplot as plt

# Create x-y values for a sine wave:
x = np.linspace(0, 2*np.pi, 100)
y = np.sin(x)

# Plot the graph
plt.figure()
plt.plot(x, y)
plt.title(your_name + "'s sine wave")
plt.show()

More on Markdown

The above figure is a visualization of the equation \[ y = sin(x)\].

There are several other math notations we can use in these markdown cells, like inline math $x^2$. If you’re interested in fancy math formatting, have a look here.

More importantly though, you should familiarize yourself with the basic structuring and formatting of markdown text. Have a look at the following cheat sheet, and keep it handy for your first attempts of writing markdown yourself.

Note: To correctly display the above image, make sure you downloaded the file 03_unit/JupyterNB_md_cheatsheet.png and placed it in the same directory as 03_unit/Our_first_notebook.ipynb.

Learning checklist

I understand that Jupyter notebooks are .ipynb files that consist of cells, where each cell either represents python code or markdown text.
I can navigate between cells in command mode ([ESC]) and edit them in edit mode ([Enter]).
I can execute cells with [Ctrl+Enter].
I am aware that the objects defined/imported in one cell, can also be used in another cell. However, the order of execution matters.
I know where to find guidance when formatting my own markdown text.