Introduction to Jupyter Notebook

Last edited: March 6th, 2018

A short introduction to the use of Jupyter Notebook

In this tutorial we introduce the web-based application Jupyter Notebook. It is ment as a quick and easy introduction to the use of the application. For a full guide on every function, check out the Jupyter Notebook homepage. It is assumed that the reader is already familiar with Python. See e.g. the notebooks on Basic Plotting or Introduction to Matplotlib for a general discussion on plotting. For an alternate introduction by Erik André Jakobsen in norwegian, click here.

What is Jupyter Notebook?

Much more than only Python! Jupyter Notebook is an web-based application suitible for the process of solving a computational problem and presenting the results along with code, explanatory text and background. Jupyter Notebook combines two components:

The web application: a browser-based tool for interactive authoring of documents which combine explanatory text, mathematics, computations and their rich media output.

Notebook documents: a representation of all content visible in the web application, including inputs and outputs of the computations, explanatory text, mathematics, images, and rich media representations of objects.

Why Jupyter Notebook?

Installation

Do you have Python installed?

You need Python to run the IPython Notebook on your system. To see if you have it installed, type the following into the command line:

python.

If you get a response similar to this

Python 3.6.3 |Anaconda custom (x86_64)| (default, Oct  6 2017, 12:04:38)
[GCC 4.2.1 Compatible Clang 4.0.1 (tags/RELEASE_401/final)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>

you're good. If not, see below. You might have to type python3 to get Python 3 if you launch Python 2 by default.

Installing the Notebook

Jupyter's own installation guide is a good place to start. They explain how to install the notebook using either Anaconda or pip.

Starting a Notebook

When you have the application installed, creating a notebook is easy. The fastest way is by using terminal/CMD. Executing the command jupyter notebook from the command line will start the notebook server and open a web browser to the web application dashboard. The command will also print some information about the notebook server in your console. When you connect for the first time you may have to copy and paste the URL presented in the console into your browser to open the application dashboard.

If you have Anaconda installed, you may open Jupyter Notebook by launching it from Anaconda-Navigator, which is an default application from Anaconda.

From the Jupyter Notebook browser dashboard you can navigate through your own directories and open existing notebooks or create new ones by clicking the New-button and selecting Notebook: Python 3. This will open a new tab in your browser and you are good to go! You can also drag and drop .ipynb notebooks and standard .py Python source code files into the notebook list area.

Gif credit: Jupyter Notebook

Alternatively, you can open a particular notebook directly from the command line with the command jupyter notebook my_notebook.ipynb. Be sure to be in the same directory as the notebook file.

Notebook user interface and structure

Structure of a Notebook

Before desscribing the interface you should now a bit about the structure of a Jupyter Notebook. The notebook basically consists of a sequence of cells aranged unnderneath eachother. Usually a mixture of Markdown cells and code cells. As default, one code cell is presented. Here you can write python code with automatic syntax highlighting, indention, and tab completion/introspection. The code can be executed by using Shift-Enter and the eventual computation result will be display under the cell. Also a new code cell will be added. This new cell can then be changed to e.g. a markdown cell if you want to comment the result in rich text. Next, you can create a new code cell and do more computation without having to run the previous code cells.

Interface

The interface of a new notebook presents a notebook name, a menu bar, a toolbar and an empty default code cell.

From the menu bar you can open, copy and create new notebooks, print and download a preview, insert, delete manipulate and run cells (wich is the core of the notebook structure), and more.

The toolbar is a quick and easy accsess way of navigating through and working with cells. As well as changing cell types.

The notebook name can be altered directly by clicking on the title.

Cells

A cell is a multiline text input field, and its contents can be executed by using Shift-Enter. Jupyter Notebook has three types of cells: code cells, markdown cells and raw cells.

Code cells Allows you to write and edit code in Python. Other languages such as R or Julia can be handled using cell magic commands. The only magic command we will present in this tutorial is the command %matplotlib inline, demostrated under Plotting.

Markdown cells. If you want to document your computation, let's say you are writing a report and need an introduction, theory section with mathematical equation and a coclusion to accompony your code, then you want to use a markdown cell.

Using the Markdown language, this cell makes an easy way of writing and performing text markup (italic and bold text, lists, headings, etc.). A great thing about Markdown is that you can include mathematics and equations in a straightforward way, using standard LaTeX notation.

Additionally, Markdown allows arbitrary HTML code for formatting. Wich makes it possible to customize images and e.g make HTML lists.

As an example of the Markdown language:

**This** is an *example* of how:

* Markdown works
* ~~Python works.~~
* $E = mc^2$

\begin{equation}
T = \frac{1}{2}mv^{2}
\end{equation}

Executing the code above will yield:

For a full cheatsheat of all Markdown language funcionalities, click here.

Raw cells provide a place in wich you can write output directly. Raw cells are not evaluated by the notebook. This means that you can write LaTeX code in a raw cell, but it will not be rendered until you convert and view the notebook through a preview application, such as nbviewer.

However, this enables the possibility of defining your own style and font of the notebook using CSS or HTML in a raw cell. More on this later

Edit mode and command mode

While navigating through cells in the notebook you are woking in either command or edit mode, indentfied by the color of the frame around the cell. Blue or green left marrow and frame colour respectively corresponds to command or edit mode.

In command mode you can easy navigate through the cells using the arrow keys. You can also change the cell type of the selected sell with keyboard shortcuts. Typing M will change it to a markdown cell and Y will change it to a code cell. Pressing Hwill show all available keyboard shortcuts, both in command and edit mode.

While in command mode, you can enter edit mode by hitting Enter. This will allow you to edit the content of the current cell. To return to command mode, press esc.

Commanding Shift+Enter will run the selected cell in both command and edit mode. As well as moving to the next cell, or create a new code cell if necesarry. To run without leaving the cell, press Ctrl+Enter.

Plotting

To embed plots within the notebook (this is often default behaviour), one needs to use the inline backend by typing 

%matplotlib inline  # embed plots

To change backend, one can use

%matplotlib qt  # use qt backend

This enables amongst other plotting in a seperate window.

Extensions

More advanced users can note that there exists some extensions to Jupyter Notebook, such as Jupyter Nbextensions Configurator and Jupyter notebook extensions. The jupyter_nbextensions_configurator jupyter server extension provides graphical user interfaces for configuring which nbextensions are enabled. The jupyter_contrib_nbextensions repository contains a collection of extensions that add functionality to the Jupyter notebook. This includes equation labels (this is now also included at NBviewer and when downloading the notebook as HTML), codefolding, spell checking and much more.

Sharing your Notebook

There are a number of ways to view and share your finished notebook. A Jupyter Notebook is by default a .ipynb file. This filetype can be shared and opened by anyone having Jupyter Notebook installed. To open an .ipynb, proceed as instructed above.

From File in the menu bar you can print a preview or download the notebook in a variaty of filetypes. If you wish to download it as a .pdf, LaTeX and pandoc is required.

However, a better way of displaying your notebook is by using nbviewer.

  1. Upload your .ipynb notebook to a webpage, e.g your own homepage at NTNU (folk.ntnu.no).
  2. Enter the location of your Jupyter Notebook (URL) to the nbviewer homepage and click Go!. This will redirect you to the rendered nbviewer web page for your notebook.

Now you can copy the URL of the notebook-page and share it as you like. This link will be functional as long as your notebook .ipynb-file is located at your chosen web page.

For an instruction on how to create and upload files to your homepage folk.ntnu.no/brukernavn, click here.