Jupyter notebook

  • What is it?
  • Start Jupyter notebook
  • Create a new directory
  • Create a new notebook
  • Editing modes
    • Markdown Cells
    • Code cells
  • Save
  • Download
  • Quit Jupyter
  • More (optional)

What is it?

From Project Jupyter website: The majority of the tutorials in this workshop, including the one you reading right now, are Jupyter notebooks.

Start Jupyter notebook

To launch Jupyter notebook, open your terminal (that is your command line; if you don’t know what it is, read the Command line tutorial) and type:

jupyter notebook

Then wait for a window to open in your Web browser. You can ignore the command line after that; your interaction with Jupyter will happen entirely in the Web browser window. In the browser you can navigate into your local files; note that the directory displayed in the broswer when you launch Jupyter corresponds to the directory where you are when typing the command jupyter notebook; this means that if you open the terminal and launch Jupyter, the Home directory will appear to you.

If, for whatever reason, nothing happens in your Web browser, then once you see a pair of lines in the command-line terminal like:

[I 23:14:13.260 NotebookApp] The Jupyter Notebook is running at: http://localhost:8888/
[I 23:14:13.260 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).

you can navigate in a browser to http://localhost:8888/

In rare cases some users may already be running another application that uses that address, in which case IPython notebook will refuse to start. You can tell IPython notebook to use a different address with:

jupyter notebook --port 8889

Numbers between 8889 and 8899 are likely to be free.

Create a new directory

During the workshop we will work with Jupyter and we will need to create new notebooks. We probably want to organize these new notebooks in a directory: remember that we created a directory for the workshop, we can now create a sub-directory.

We have now launched Jupyter and can see our Home directory in the Web browser. Go to the “Workshop” directory. For creating a new sub-directory, press the button New at the top right and select Folder. This will create a new directory, called “Untitled folder”. Check it and rename it “Notebooks”, as in the image below.

Create a new notebook

Now we have Jupyter running and we have a new directory for our notebooks. Navigate to the new directory (the one that you renamed as “Workshop” or “Notebooks”) and press the New button again: this time select Python 3 or Python [default] from the menu.

New notebook

By default this will create a new notebook with a name like “Untitled” - we can rename it immediately by clicking on the name at the top (beside the Jupyter logo) and providing another name in the dialog box that appears. This is the actual filename (without the file extension) and we’ll use the file naming conventions explained in the Command line tutorial.

This is probably as good a time as any to step through the “User Interface Tour” that’s available from the Help menu of the Jupyter interface (the File menu within the notebook page, not the File menu of the browser).

Editing modes

We’ve created a new notebook and had a quick tour of the Juypter interface, now we’re ready to edit. Jupyter has two main editing modes:

  1. Markdown: this is the styled text mode that we use when we’re not writing python code
  2. Code: this is the default mode used for python code and we’ll see it in the next section

Markdown Cells

Markdown is the format used for text (not code) in Jupyter. Markdown is intended to be more succinct and simpler to read and write than HTML (the system converts Markdown automatically to HTML for display in the browser). For instance, we can easily create headers by using one or more hash (#) symbols at the beginning of a line, we can easily have text appear in **bold** or _italics_, paragraphs are created from newlines, and links like http://python.org/ appear automatically as links. Another powerful feature is the creation of lists. For instance, we can create a bulleted list by putting an asterisk in front of every item or a numbered list by putting 1. in front of each item (the numbering will increase automatically).

We will now go to the first editing box and select Markdown mode from the format menu, then type the following text, as in the image below:

# Getting started!
This is _Hello World!_, my first iPython Notebook.

Markdown cell

Now you can render the markdown, which is the same as run the code. You have multiple options for the command “run cell, select below”:

  • press the corresponding button on the toolbar (right-pointing triangle)
  • click on the Cell menu and then select run cells or run cells and select below
  • hit Shift+Enter

Code Cells

Go to the following editing box (or insert another one using Insert cell below from the Insert Menu or pressing the button “+” in the toolbar). The default mode for an editing box is Code, so you don’t need to change the editing mode as we did for Markdown.

Our first bit of code is going to follow tradition: what better place to start than the classic Hello World! program. It’s easy to describe what we want to do for our Hello World! program: we want to write code that will display the string (or sequence of characters) “Hello World!”. Let’s use the print function and indicate that “Hello world” is a string using the double quotes:

print("Hello world!")

The result should appear, as here below.

In [21]:
print("Hello world!")
Hello world!

Yay, our first program! That was easy, wasn’t it? :)

Try to remove the double quotes around Hello world and run the code again:

print(Hello world!)

You will get an error message, because the syntax of your code is not correct.

The sequence above shows a key aspect of Jupyter code cells: there’s an input section and an output section: the input section is where you write the code and is indicated on the left of the editing box with the word “In” followed by a number in square brackets; the output section is where the result of running your code will appear, below the input section.

Save

If we have been working on a notebook, we would of course want to save our work before quitting. For saving the notebook you are working on, you have again several options:

  • press the file icon, that is the first button on the left
  • select Save and checkpoint from the File menu
  • hit Ctrl+s

Download

You can download the notebook in different formats (menu File > Download as).

Quit Jupyter

The browser window opened when Jupyter was launched is just a regular window. For quitting Jupyter we can close the browser window(s) opened by Jupyter, then switch to the terminal and follow the instruction:

Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).


Where are my notebooks

Now that we’ve quit Jupyter, the directory that we created using the Jupyter interface is still there where we put it: in the subdirectory “Notebooks” of our “Workshop” directory, and we can access it with cd, just like any other directory. The new notebook is inside. Go and check!

To summarize, everything that we do through the Jupyter interface is stored locally on our computer. Just remember that in order to open and edit the notebooks, we have to launch Jupyter again!

More (optional)

During the workshop we will run commands like the following. You can give it a try: copy paste the code below into a new code cell, run it, and see the result.

In [22]:
from collatex import *
collation = Collation()
collation.add_plain_witness("A", "The quick brown fox jumps over the dog.")
collation.add_plain_witness("B", "The brown fox jumps over the lazy dog.")
alignment_table = collate(collation)
print(alignment_table)
+---+-----+-------+--------------------------+------+------+
| A | The | quick | brown fox jumps over the | -    | dog. |
| B | The | -     | brown fox jumps over the | lazy | dog. |
+---+-----+-------+--------------------------+------+------+

To test your Graphviz integration, type into another code cell the following and run the code:

In [23]:
collate(collation,output="svg")
%3 1 quick Sigla quick A 7 brown fox jumps over the Sigla brown fox jumps over the B, A 1->7 A 2 2 4 The Sigla The B, A 2->4 A, B 3 3 4->1 A 4->7 B 5 dog. Sigla dog. B, A 5->3 A, B 6 lazy Sigla lazy B 6->5 B 7->5 A 7->6 B

A graphic representation of the collation should appear below the cell (your font may look different from the one in the tutorial).

More about Jupyter notebook

available through the official Jupyter page.


Note: this tutorial is built upon the IPython section in the CollateX workshop Installation tutorial and upon the first chapters (Getting setup and Getting started) of The Art of Literary Text Analysis by Stéfan Sinclair & Geoffrey Rockwell, with modifications.

CC BY-SA From DiXiT Code and collation workshop.
Created October 10, 2016 and last modified October 12, 2016