Jupyter Notebook Quick Start

If you're not familiar with the Jupyter Notebook, this page will serve as a quick reference to get started with the code samples in /notebooks. The full docs are available at jupyter-notebook.readthedocs.io.

Jupyter notebook uses the iPython kernel to provide an interactive Python session in a web browser interface. This gives you an development environment to execute "cells" of code that can be executed independently for feedback, yet variables and output persists across cell execution. Additionally, objects can be called directly to display their contents, while visualization libraries like Matplotlib can display/update graphs inline.

To start the Jupyter notebook, open a new terminal window, activate your Python environment, and then type "jupyter notebook".

You'll notice that the startup output includes a URL with security token. This allows you to re-access the notebook if you close out your browser by accident or on purpose (the notebook server will continue to run until you hit Ctrl-C in the terminal window).

Jupyter will also open your default browser and show directory contents from where you launched it:

When you double-click a file with the .ipynb extension, Jupyter opens a new window/tab like this:

You'll notice the code is broken up into groups, with several lines per cell, though some cells have text content instead. In our screenshot above, the first cell is highlighted with a thin blue band to indicate the selection. If you double-click in this cell, it will provide an interface to edit the content using https://www.markdownguide.org, like this:

To "save" or more accurately, to "execute" that set of content styling, simply click the "Run" button in the navigation, or use the keyboard to press "Shift+Enter".

Using Shift+Enter is an easy way to execute each cell, as it will execute the code within it and display any output right below, then advance to the next cell and await for execution. The Shift+Enter keystrokes and the Run button are identical functionality.

To execute the entire program in the Juptyer notebook, simply start at the top cell, and hit Shift+Enter until the program ends. Note that you cannot execute out of order. For example, if the code in a cell depends on a variable assignment or a function declaration in a previous cell, they will need to be executed in order. However, you can go back and rerun a specific cell if needed. For example, in the first code-based cell in the images above, the first three lines are import statements for Python library dependencies. If later in the script I discover I need an additional library such as Matplotlib, I could scroll up to the top, add the necessary import matplotlib and then press Shift+Enter to re-run that cell. After that, I can return to my working area at the bottom and continue writing/testing code that requires Matplotlib.

However, variables are persisted across cell execution, and may be incorrect if you execute code out-of-order or need to return to a previous state. In those instances, you may need to restart the kernel and re-execute code cell-by-cell from the beginning. This is done through the Kernel menu option.

In the image above, you'll see several options, which includes Restart and Clear Output (useful if you want to remove all cell output from the previous execution) and a Restart and Run All, if you want to simply execute the entire notebook like a traditional script (that is, start at the beginning and run each line until the end is reached). If you simply need to reset your Variables, then the plain Restart option is sufficient.

When you re-run a cell, any output for that cell will update accordingly. If you need to clear the output without re-running the cell, you can use the Cell menu to clear output for that cell only, or clear out all cells:

When you create a new cell (by clicking the [+] button underneath the file menu), it defaults to creating a new code cell. If you need to convert it to a Markdown cell (eg, for documentation/instructions/etc), use the dropdown menu to select it.

Finally, if you want to save the code as a Python .py file, use the File -> Download As -> Python menu options. This will save it to your browser's default download location with a .py.html file extension. The code itself will be as expected, with any markdown text commented out.

However, not all output functions in Jupyter work in plain Python code (eg, calling an object directly in Jupyter notebook will display the object's contents or information, while displaying the output in a terminal window requires wrapping the object in a print() statement.