Welcome to Jupyter Notebook!
This tutorial contains basics of the Jupyter Notebook application. If you have opened this tutorial in Jupyter you can test different features, modify the content and create comments. If you don't have Jupyter yet, see section Installing Jupyter Notebook.
For more detailed instructions, the official documentation of the Jupyter project can be found at http://jupyter.readthedocs.io/en/latest/index.html. The Jupyter Notebook documentation is available at http://jupyter-notebook.readthedocs.io/en/latest/.
This document contains:
(unfortunately the heading links work only in Jupyter, not in GitHub)
Jupyter Notebook is a web application which makes it possible to create documents that combine programming code, regular text, images, visualizations and mathematical equations. These documents are called notebooks.
Jupyter is an open-source application. It supports over 40 different programming languages, including for example Python, C++, JavaScript and Ruby.
There are couple of different ways to install the Jupyter Notebook. The easiest and recommended option is to perform the installation with Anaconda. Anaconda installs Jupyter Notebooks, Python and some useful Python packages all at once. The installation is easy:
Other options for installing Jupyter can be found from http://jupyter.readthedocs.io/en/latest/install.html.
You can also open a free test version at https://try.jupyter.org/ or you can create a free account on the CoCalc service at https://cocalc.com/. CoCalc makes it possible to use Jupyter in cloud without installing it to your computer.
Jupyter Notebook can be started either with the Anaconda Navigator or with the command line as explained below. After starting, the Jupyter dashboard will open in the browser showing your files and folders.
A new notebook can be created with the New button in the top-right of the dashboard. Pressing the button will open a menu where under the text Notebooks the kernel of the notebook can be selected. The kernel determines which programming language (e.g. Python 2, Python 3, C++...) the notebook will use. The number of kernels available depends on how much kernels the user have installed.
In this tutorial we are using the Python 3 language. After selecting the kernel the new notebook will open in a new tab.
Jupyter uses a browser based user interface. The most important parts of the interface are the menu and the toolbar on the top of the interface (see picture below) and the notebook area.
Edit mode can be activated by pressing Enter or by double-clicking the cell that is wanted to be edited. One can get back to the command mode by pressing Esc or by double-clicking again. From the right of the menu it is possible to check in which mode Jupyter is. If the pencil is shown like in the image below
The key commands in edit mode and in command mode differ. Depending on which mode Jupyter is, same button can have different actions. For example in command mode the button s will save the notebook but in edit mode the button s writes the letter "s" in the cell that is edited.
All content of the notebook is written in cells. In below there is for example a cell that is determined to be a code cell. Also this text that you are reading is written in the own cell, text cell. Cells can be run. Running the cell will make the cell do different actions depending on the type of the cell.
# This is a code cell that includes just this comment line and no code at all actually.
There are four different cell types in Jupyter: code (programming code), Markdown (normal text), heading and raw (code that will be left off from the content of the notebook). The most important ones are Code and Markdown cells.
There are some useful shortkeys listed in the table below. You can also check out how to create a table and set different alignments for colums. More precise information concerning cells is found in the following subsections.
Shortkey (Cell not active *) |
Function | Shortkey (Cell active **) |
Function |
---|---|---|---|
a/b | new cell above/below | Ctrl + Enter | run cell |
dd | delete cell | Shift + Enter | run cell and activate next cell |
m/y | text/code cell | Alt + Enter | run cell and create new cell below |
up/down | previous/next cell | Ctrl + Shift + - | divide cell |
s | save | Ctrl + S | save |
(centered) | (left aligned) | (left aligned) | (right aligned) |
* Cell not active refers to command mode when the cursor is outside of the cell and the side of the cell is blue.
** Cell active refers to edit mode when the cursor is active inside the cell and the side of the cell is green.
You can find and edit all the shortcuts by pressing *H* while in command mode.
A new cell can be created below the selected one by
If you are reading this tutorial in Jupyter you can now try to add a new cell below this text cell. You can also add cell above the selected one by pressing a in command mode.
After creating the cell, the type of the cell can be selected. Selection can be done either with the toolbar selection
The cell can be edited by moving to edit mode by pressing Enter or by double-clicking the cell. The type of the cell can be changed even if there is content in the cell.
Deleting the cell is done the easiest way by double-pressing the button d when the cell is selected (blue).
Deleting can be also done by selecting Edit $\rightarrow$ Delete Cells from the menu.
The most important feature of Jupyter Notebook is the running of cells. After running, the cell will do actions that it is meant to do. Content of the Markdown cell will turn into regular text and the code cell will do what is written in it in the selected programming language.
You maybe noticed earlier that after editing a Markdown cell and exiting it, the cell didn't return into normal text automatically. That happens because the cell needs to be run after editing it.
The only cell type that won't be run straight in Jupyter is the raw cell. The code written in the raw cell is meant for example for the output of the nbconvert tool (https://github.com/jupyter/nbconvert). With the nbconvert notebooks can be imported in other file formats.
Running the cell can be done in three different ways.
<img src="../Images/cellrun.png", align="left">
# This is a code cell. After running the cell the text "Hello world!" should be printed.
print('Hello world!')
Hello world!
Now let's view the Markdown, heading and code cells more closely.
Markdown cells use the Markdown markup language (https://daringfireball.net/projects/markdown/). Markdown makes it possible to easily format plain text. The text can be for example bolded, italicized or sriked out.
For example this kind of blockquote can be added in the text.
Also lists are easy to create with Markdown.
Shopping list:
In this tutorial the Markdown formatting commands are not handled more accaurately but a good list of different commands can be found for example from the web page https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet. You can also enter the edit mode in this Markdown cell and see how the different formats have been made.
Heading cells are in fact not even own cell types but more likely shortcuts for creating headings. That is because heading cells also use Markdown, so basically they are Markdown cells.
Differently leveled headings are determined in Markdown with # characters. Below there are the heading levels that are in use in Jupyter starting from # tagged, continuing to ## tagged and ending in ###### tagged heading.
Even though Heading cells and Markdown cells are basically same, it is recommended to keep headings in their own cells separated from text. That makes the compiling of the text easier for the program.
Programming code in selected programming language (kernel determines the language) can be written in code cells. For example if the notebook uses Python 3 kernel, Python 3 commands can be run in code cells. If in this case some other programming language would be written in code cells the code would not be compiled because it would be interpreted as Python 3 code.
The code written in code cells behave similarly than in other programming environments. This is possible because of the IPython kernel. Running the code is in summary based on the connection between the notebook and the kernel. The code is actually run in the kernel. The kernel will communicate with the notebook and give the results of the run. The results of running the code will be seen in the output part below the code cell.
For example in the code cell below the result of the calculation 3 + 4 is saved in the variable result. After that the value of the result is asked to be shown. When the code is run, the creation of the variable and the calculation are done in the kernel. After that the kernel will return the results to the notebook and the number 7 is appeared in the output part.
result = 3 + 4
result
7
The output of the code cell isn't restricted to numbers or text only. Output can also be for example a graph. In the code cell below different number pairs are plotted with the matlpotlib module and the output will be a graph.
import matplotlib.pyplot as plt
% matplotlib inline
numbers = [1,2,3,6,7,8,12,16]
plt.plot(numbers, 'ro')
plt.show()
There are different ways for adding images and videos to notebooks. Here adding images and videos with HTML is showed.
Because Jupyter uses Markdown language, some HTML tags will work straight in Markdown cells. For example adding the test-image.png named image could be done by writing the following HTML tag straight in the Markdown cell:
<img src="test-image.png">
In the example above the image has to be in the same directory than the notebook. It has to be told in the HTML tag if the image added to the notebook will be in some other directory than the notebook. A good example of referring to directories in different cases can be found from https://stackoverflow.com/questions/14489016/how-to-properly-reference-local-resources-in-html.
Let's take for example a situation where the image is not in the same directory/folder with the notebook. There is a folder Images in the parent directory of the notebook and we want to add the image test-image.png to our notebook.
Adding the image to the notebook can be done with the following tag:
<img src="../Images/test-image.png">
where $../$ tells the program to go to the parent directory and then Images/ to a folder named Images where the image named test-image.png is located.
If you are reading the tutorial in Jupyter you can also check how the images in this tutorial are written in the Markdown cells by entering in edit mode.
Information for example about the position and the size of the image can be added to the HTML tag. For example an image can be aligned to left with the following tag:
<img src="../Images/test-image.png" align="left">
.
Note that setting alignment can make the text appear on the side of the image. You can "push" the text lower by adding linebreaks <br>
.
Selecting the size is possible by telling the wanted size in pixels, for example
<img src="../Images/test-image.png" align="left" width="80" height="50">
.
More information about the HTML image tags can be found for example from https://www.w3schools.com/tags/tag_img.asp.
Adding a video in notebook can also be done with HTML tags. Determining the directory of the video is done similarly than with the image (see section 6.1 Adding an image above). For example the test-video.mp4 which is in the same directory than the notebook can be added to the notebook with the following tag:
<video src="test-video.mp4" type="video/mp4" controls>
In the tag the type determines the file format of the video which is in this example .mp4. Command controls creates the buttons that are needed to play the video. More information about the HTML video tags can be found from https://www.w3schools.com/tags/tag_video.asp.
The video added in the notebook can for example look like this (note that the video might not be viewable straight in GitHub):
Jupyter Notebook also supports $\LaTeX$ formatting. With $\LaTeX$ for example mathematical equations can be easily created. In Jupyter $\LaTeX$ can be written in Markdown cells by separating it from the other text with $ characters. Command $...$ produces material inline with the text (inline mode) and command $$...$$ produces material separated from the text (displayed mode). The $\LaTeX$ code would be written in the ... section.
Inline mode looks like this: $\sin(x) = \frac{3}{4}$ and displayed mode like this:
$$\int_2^3{cos(x)} = \frac{23}{45}$$More information about the $\LaTeX$ can be found from https://www.latex-project.org/.
Saving the notebook can be done easiest by pressing s button in the command mode. Notebook can also be saved by selecting File $\rightarrow$ Save and Checkpoint from the menu or by clicking the saving icon from the left of the toolbar:
Notebooks will be saved in .ipynb file format. Saved notebooks can be looked and opened with the dashboard.
In the dashboard the Files tab is for exploring the files and the Running tab for exploring the Jupyter processes which are running. In this tutorial the Clusters tab is not handled.
Files shows the content of the place where Jupyter saves files (computer, server, cloud service). In the Files tab notebooks can be opened, deleted, duplicated and renamed. If a logo of some notebook is green (check the image above) it means that the notebook is running.
Jupyter doesn't automatically shut down notebooks and disconnect them from the kernel when tabs that contain the notebooks are closed. In stead the notebooks must be shutted down manually after the use. This can be done by two different ways. The first way is to click the checkbox of the running notebook in the Files tab and to click the button Shutdown on the toolbar (see image below) that will appear.
The second way to shut down the notebook is to open the Running tab and then click the button Shutdown on the right of the name of the notebook:
Ready notebooks can be used in two different ways: as interactive versions or as static versions. When notebooks are opened in Jupyter, the interactivity of the notebooks will remain. This means that the user can run the cells and edit them. Additionally notebooks can be viewed also as static versions. Then the content of the cells is viewable but the cells can't be run or edited. Jupyter Notebook application is not needed for viewing the static versions.
Static versions of notebooks can be created with different ways. A notebook can be for example saved as a .html file (which can be viewed in a browser) by selecting File $\rightarrow$ Download as $\rightarrow$ HTML from the menu. Another handy way to view static notebooks is nbviewer application (https://nbviewer.jupyter.org/). With nbviewer it is possible to view online published notebooks as static .html versions. Either the url of the notebook or the GitHub username (if the notebook is saved in GitHub (https://github.com/)) is given to nbviewer.
Sometimes running incorrect or too complex code cell can jam Jupyter. Running the code cell can be interrupted by selecting Kernel $\rightarrow$ Interrupt from the menu or by clicking the interrupt kernel button (see the image below) from the toolbar.
The code cell which is still running can be recognized by the asterisk inside the In[ ] mark on the left side of the cell
or by the text (busy) shown in the name of the tab of the notebook.
If there was an error in your code previously and you fixed it, it might be that the saved variable is not updated. The easiest solution is to restart the kernel with
Your text or code won't be erased, only the variables saved in the memory of the program.
Notebook can lost a connection to a kernel where it is connected. Broken connection can be seen from the icon on the right side of the menu. When the kernel is functioning normally the icon looks like an entire ball
If the reconnecting won't help, the restarting of the kernel can be tried. It has to be noted that all variables created in notebook will be disappeared when the kernel starts again. The restart can be done by selecting Kernel $\rightarrow$ Restart from the menu or by clicking the restart the kernel (with dialog) button from the toolbar:
If the code cell won't be compiled right when it is run, the possible reasons can be for example incorrectly written code or accidentally selected wrong cell type. For example if code is written in Markdown cell it won't do the actions it is meant to but will just be transferred to text.
Also a wrong kernel can be a reason for unwanted behaviour of a code cell. The kernel will determine in which programming language the code written in code cells are handled.
This tutorial includes information about starting the usage of Jupyter Notebook. In addition to these basics Jupyter offers lots of different possibilities for example for calculations, data-analysis, teaching or learning of programming. A good way to learn the usage of Jupyter or programming is to challenge oneself. What will this piece of code do? How could I write a notebook that would calculate an average of grades? Could it be possible to do a histogram from the grades?
Page https://github.com/jupyter/jupyter/wiki/A-gallery-of-interesting-Jupyter-Notebooks includes lots of interesting examples about notebooks created. These examples provide a picture about which kind of material it is possible to do with Jupyter Notebook.
Have a nice time with Jupyter!
(Hint: section 5)