Tutorial 0b: Using Jupyter Notebooks

© 2018 Griffin Chure and Suzy Beeler, modified by Tom Röschinger, 2021. This work is licensed under a Creative Commons Attribution License CC-BY 4.0. All code contained herein is licensed under an MIT license

---

What is a Jupyter notebook?

Jupyter is browser-based system to write code, math, and text in the same document such that you can clearly explain the concepts and practices used in your program. Jupyter is not only for Python, but can be used with R, Juila, MATLAB, and about 35 other languages as of this writing. All files are saved as a JSON formatted text file with the extension .ipynb.

How to launch the notebook

A Jupyter Notebook server can either be launched from the command line or from a GUI program installed along with anaconda called Navigator.

Launching from the command line

To launch a notebook server from the command line, simply open a terminal emulator (Terminal.app on OSX or gitbash on windows) and navigate to the directory you would like to set up a server by typing cd path/to/folder (please see the Python syntax tutorial for more detail on these commands). If you followed the directory structure specified in tutorial 0a, you can navigate to this directory as follows.

cd ~/bootcamp

Once you are in the correct folder, you can launch a notebook server by typing:

jupyter notebook

In this course we will be using Jupyter Lab, which can be launched similarly

jupyter lab

This will open a screen in your default Internet browser with a server containing your notebooks. It's address will be http://localhost:8888 and is only available on your computer. Note that once you start a server, you must keep the terminal window open. This is where the 'guts' of the Python kernel is.

Launching from the Anaconda Navigator

Installing Python 3 from Anaconda should also install a GUI application called Anaconda Navigator. By opening Anaconda-Navigator.app, you will be given the option to launch several applications. Here we are interested in the Jupyter Notebook application tab, which is shown boxed in red below:

By clicking on 'Launch', you will instantiate a Jupyter notebook server which should open in a new window. This window will display the file directory of your home directory. From here you can navigate to your bootcamp folder, provided you set you your file directory as specified in tutorial 0a.

Interacting with the notebook

If everything launched correctly, you should be able to see a screen which looks something like this:

To start a new Python window, click on the right-hand side of the application window and select New. For our purposes, we will be selecting the Python 3 option under notebooks. Note that you may instead see an option for Python [conda root] or Python [root]: these are also fine to select.

Once you start a new notebook, you will be brought to the following screen.

Welcome to the Jupyter notebook! There are many available buttons for you to click. However, the three most important components of the notebook are highlighted in colored boxes. In blue is the name of the notebook. By clicking this, you can rename the notebook. In red is the cell formatting assignment. By default, it is registered as code, but it can also be set to markdown as described later.

Finally, in purple, is the code cell. In this cell, you can type an execute Python code as well as text that will be formatted in a nicely readable format.

Writing code

All code you write in the notebook will be in the code cell. You can write single lines, to entire loops, to complete functions. As an example, we can write and evaluate a print statement in a code cell, as is shown below. To execute the code, we can simply hit shift + enter while our cursor is in the code cell.

# This is a comment and is not read by Python
print('Hello! This is the print function. Python will print this line')

Hello! This is the print function. Python will print this line

The box with the gray background contains the Python code while the output is in the box with the white background. We can also write a for loop as an example of executing multiple lines of code at once.

# Write a basic for loop.
for i in range(5):
    # Multiply the value of i by two and assign it to a variable. 
    temp_variable = 2 * i
    
    # Print the value of the temp variable.
    print(temp_variable)

0
2
4
6
8

As is discussed in the Python syntax tutorial, we often must import modules to get scientific power out of our programs. Import statements work in these cells as well. For example, we can import multiple modules at once that we will use to make a plot.

import numpy as np
import matplotlib.pyplot as plt
import seaborn as sns
sns.set()

In order for plots to render within the notebook, you must tell Python to display these plots inline. To do so, we can simply type the following.

%matplotlib inline

As an example, we can plot one of Griffin's favorite functions.

# Plot one of Griffin's favorite functions.
x = np.linspace(-np.pi, np.pi, 500)
y = np.sin(2 * np.sin(2 * np.sin(2 * x)))

# Generate the plot.
plt.plot(x, y)
plt.xlabel(r'$x$', fontsize=16)
plt.ylabel(r'$y$', fontsize=16)

# Make custom labels for ticks on x-axis
plt.xticks([-np.pi, 0, np.pi], ['$-\pi$', '0', '$\pi$'], fontsize=15);

While you could in principle write an entire script's worth of code in a single code cell, this is not wise for readability. Therefore, keep the length of what you write in code cells to a logical minimum. Write them such that the perform a single step in your analysis, then move on to the next cell. For example, it is wise to write a function in its own code cell and then execute it in another. It is reasonable, however, to have a single notebook contain all code for a single analysis, just not in a single code cell.

A warning

Code cells can be executed in any order. This means that you can overwrite your current variables by running things out of order. When coding in notebooks, be cautious of the order in which you run cells.

Writing Text

Arguably the most useful component of the Jupyter notebook is the ability to interweave code and explanatory text into a single, coherent document.

Each cell in a Jupyter notebook can exist either as a code cell or as text-formatting cell called a markdown cell. Markdown is a markup language that very easily converts to other typesetting formats such as HTML and PDF. You can find a cheat sheet here.

Whenever you make a new cell, it's default assignment will be a code cell. This means when you want to write text, you will need to specifically change it to a markdown cell. You can do this by clicking on the drop-down menu that reads code (highlighted in red in the second figure of this notebook) and selecting Markdown. You can then type in the code cell and all Python syntax highlighting will be removed. The basics of Markdown (nearly all you will need to know can be summarized by typing the following lines into a markdown cell.

**This part of the sentence will be bold**, *this part italic*, [this part a link](http://www.google.com), and 
* This part a 
    + bulleted
        - list

These lines yield the following output:

This part of the sentence will be bold, this part italic, this part a link, and

• This part a
  • bulleted
    • list

Mathematics can be typeset using the LaTeX typesetting language within markdown cells. For example, typing

$$
\int\limits_{-\infty}^{\infty}e^{-\alpha x^2} dx = {\sqrt{\pi}\over{\alpha}}
$$

into a markdown cell is rendered as

$$ \int\limits_{-\infty}^{\infty}e^{-\alpha x^2} dx = {\sqrt{\pi\over{\alpha}}}. $$

Saving, quitting, and going home

Jupyter notebooks are set up to autosave your work every 15 or so minutes. However, you should not rely on the autosave feature! Save your work frequently by clicking on the floppy disk icon located in the upper left-hand corner of the toolbar.

To navigate back to the root of your Jupyter notebook server, you can click on the Jupyter logo at any time.

To quit your Jupyter notebook, you can simply close the browser window and the Jupyter notebook server running in your terminal.

Converting to HTML and PDF

It is useful to know that you can convert these notebooks to highly-portable formats such as HTML and PDF. To convert, you can either do this using the dropdown menu option File -> download as -> ... or via the command line by using the following lines:

jupyter nbconvert notebook_name.ipynb notebook_name.html

assuming you are in the same working directory as your notebooks.