Tutorial 0b: Using Jupyter Notebooks and Jupyter Lab¶

What is Jupyter Lab?¶

Jupyter lab is a browser-focused computational environment allowing you to write and execute Jupyter Notebooks, scripts, and even text files from a centralized interface. While under development for several years, it has now become stable enough for regular use. For those of you used to MATLAB and other GUI focused programming languages, Jupyter Lab will feel just like home!

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 Jupyter Lab¶

As Jupyter Lab is a browser-focused app, it is deployed from a local webserver. A Jupyter 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 ~/cbbtn

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

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 Lab application tab, which is shown boxed in red below:

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

Interacting with Jupyter Lab and launching a Notebook¶

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

You will notice there will be a directory structure on the left-hand side of your window (I navigated to the cbbtn directory we set up in the first tutorial). On the right-hand side, we have a "launcher" interface where we can launch a Jupyter Notebook (highlighted in red), or several other types of files. To start a new notebook, click on the "Python 3" logo beneath the "Notebook" section.

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. To rename your notebook (shown here as Untitled), you can right-click your document and select Rename. In purple 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 red 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 below')

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

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)

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 my 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)

# Don't worry about this syntax for now.
_ = plt.xticks([-np.pi, 0, np.pi], ['$-\pi$', '0', '$\pi$'], fontsize=15)

After typing the above code, your screen should now look something like this:

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 -> Export notebook 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.