Overview

This page describes the installation and use of Jupyter notebooks. This page assumes you have some familiarity with the command line.

Jupyter notebooks give you a more structured way to run python that allows you to view plots inline with text and the code that produced them. This allows you to do sophisticated analyses in a single file with the ability to share the results easily with others. A nifty example is this Lorentz System demonstration. If you have ever used Mathematica, you will be familiar with the idea of Jupyter Notebooks. Once you have Jupyter installed, you can download this notebook and run it yourself!

Installing Jupyter

If you are using the machines in Rm 17, everything should already be set up and running. These instructions are for those that also want to be able to work on their own machines.

You can install and configure python and Jupyter on your own machine following instructions on jupyter.org. This uses the Anaconda distribution which is cross-platform and generally very trouble free. This is also how python is installed in Rm 17, so the environment should be identical.

Running Jupyter

First, make sure Anaconda-Navigator is running. From the Navigator panel, select either Jupyter Notebook or Jupyter Lab and hit the Launch button. Jupyter Lab is newer and has some nice features, but I had some problems with some of these features on my old laptop. The instructions below are for Jupyter Notebook.

Once you launch Jupyter Notebook, you will be presented with a directory listing in a web browser. This allows you to open existing Jupyter notebooks or create new ones.

Create a Jupyter Notebook

In the Jupyter browser, you can now open a directory where you want to store your files and create a new Python 3 notebook using the New menu in the upper right. This will bring up a new window with an empty Jupyter notebook. Note that the New menu also allows you to open a terminal window where you can directly run python. Before you do anything else, give a name to your notebook by clicking on Untitled at the top of the page. If you go back to the browser window you can see the notebook has appeared!

Using Jupyter

Jupyter allows you to run code, annotate your code, and see plots all in one file. In fact, this is a really useful way to document your work (including lab write-ups!) which is popular in a lot of data science fields. If you have ever used Mathematica, the idea should be familiar.

By default, you are presented with a code cell. Type your favorite python command into the window and see what happens. If you don't have a favorite, try print("hello there"). Note, nothing happens until you run this code cell. This can be done with the Run button (either at the top or in the code cell itself), or a handy shortcut is Shift-Return. Normal Return doesn't work as you can enter multiple lines of python code in a single cell.

If you want to just enter some text, you can change a cell from Code to Markdown with the drop-down menu at the top of the page. Again, Shift-Return will advance you to the next cell (Code by default). To go back and edit a markdown cell, just double click on it. To get some nice formatting, you can create headers in a markdown cell by starting a line with a pound sign:

	# Main Heading
	## Sub Heading

There are other markdown commands to easily make text *italic* or **bold**, or even make formatted lists and tables. Markdown is not specific to Jupyter, so you may have used some of this syntax in other applications. Jupyter extends basic markdown with some other nifty features, most notably a basic LaTeX math mode (try $e^{i\phi} = \cos{\phi}+i\sin{\phi}$! For more details on markdown commands, look at this Markdown Cheatsheet or just read the manual.

Plots!

One of the nicest features of Jupyter is being able to create and view plots within the notebook. If you have properly installed everything, you will have access to the widely used matplotlib package, which is a python library inspired by the Matlab plotting commands. To test this, put the following into a code cell and run it (you can just copy/paste...).

# Import needed packages
import matplotlib.pyplot as plt
import numpy as np

# Create array of 100 evenly spaced values
theta = np.linspace(0., 2*np.pi, 100)

# Define a few plots with optional labels
plt.plot(theta, np.sin(theta), label='In phase')
plt.plot(theta, 0.5*np.cos(theta), label='Out of phase')

# Always label your axes, with units!
plt.xlabel('time (s)')
plt.ylabel('Voltage (mV)')

# Titles are optional 
plt.title('Voltage Waveform')

# Draw the plot
plt.show()

Note that one important feature of Jupyter is that if you screw up, you can edit your code cells and try again. The backend which is running python remembers all of the previous commands you have run in earlier code cells in a notebook (as indicated by the In []: label next to each code cell. Once you get a cell to work, you should probably start a new code cell. Any variables defined in a previous cell will also be available in a later cell. As a result, many notebooks will start with some standard initialization commands such as the following to import some useful packages which aren't built-in to python:

import matplotlib
import numpy as np
import matplotlib.pyplot as plt

Learning More

• To get more practice with the Jupyter notebook itself and what it can do, follow the Jupyter Notebook for Beginners tutorial. This actually covers a lot of the skills you will need for your first lab assignment! If you have never used Jupyter Notebooks, I would strongly encourage you to work through at least the first part of this tutorial!
• To learn a bit more about making plots, go to mathplotlib.org and click on the tutorials link. The Pyplot Tutorial is a great place to start, and should cover everything you need for this course.
• To learn some of the neat things that numpy can do, go to numpy.org and click on the NumPy Tutorial.
• To get more information about Jupyter Notebooks, go to the Jupyter Notebook documentation and follow the link The Jupyter Notebook.

Quitting

Jupyter notebooks should auto-save every 2 minutes, but it is good practice to save with Ctrl+S before closing a Jupyter window. Even though you have shut the window, the python engine behind this window will remain running, however, so if you re-open this page, it will remember where you left off. You can see this in the main Jupyter browser window where it will show the notebook as running. It is often better to shutdown the notebook so that it is in a well-defined state when you reopen it. This is most easily done with the Close and Halt command in the File menu. Note, your Jupyter browser still works, and the backend will still be running in your terminal window. When you re-open a notebook, it will show the output from the last time you had the notebook open, but it won't remember any of the actual values or computations. To get back to where you were, simply use the Run All command in the Cells menu. In fact, it is good to test this on any notebook you are turning in, as this is how I will check your work.

If you hit the Logout button in the upper right, this shuts down your web browser, but still leaves the backend running in the terminal. You can reconnect by navigating back to the original address you used in the first place (http://localhost:8888/?token=blah). You can find this address in the terminal window that popped up when you originally launched Jupyter Notebook. If you re-launch Notebook from Anaconda, you will start a new instance of the Jupyter back-end. This is fine, but if you do this a lot, you will end up with lots of orphaned processes running in the terminal. To completely shut down everything, use the Quit button in the main Jupyter browser window. Unless you have a long job that needs to run in the background, using Quit is a better option than Logout.

Copyright © MMXX, Eric Torrence, All Rights Reserved