Prepare the environment: Jupyter Notebooks

This notebook is about preparing everything we need for the next exercises.

You should have already installed CollateX and Jupyter Notebooks. They are both installed in the computers in the classroom. For more information about the installation, see the installation instructions.

In the following exercises we'll focus on CollateX. Here we'll see how to work with Jupyter Notebooks, that is the environment we choose to use CollateX.

What is a Notebook?

The Notebook is a place where you can run code, document your program and see the results.

The tutorials in this workshop, including the one you reading right now, are Jupyter Notebooks.

The official home page of Jupyter Notebook is https://jupyter.org/.

Download the materials

  • Go to https://github.com/elespdn/CollateX_tutorial and download the entire repository, clicking on the Clone/Download green button on the right. This will download a zip folder.
  • Unzip the folder
  • You can leave the folder where it is or move it to a location of your choice, for example the Documents folder in your computer. In both cases, remember where it is.

Start Jupyter notebook

To launch Jupyter notebook, you can

  • use the launcher (for example, in the Windows computers in the rooms, start writing 'Jupyter' in the bottom left launcher)
  • or use the terminal. This what you probably have to do on Linux. Open a terminal and type

    jupyter notebook

In both cases, the terminal will show that Jupyter is starting and a window will open in your default web browser (Firefox, Chrome, Safari, etc.). You can ignore the terminal after that; your interaction with Jupyter will happen entirely in the browser window.

Open a Jupyter Notebook

In the browser you can navigate into your local files. This might be confusing, but it is as simple as it appears: your file system is available in the web browser.

Go to the materials folder that you downloaded before, just double-clicking on the icons of the folders as you would do in your computer.

When you are in the materials directory (directory and folders are synonyms), choose '02_PrepareEnvironment' and inside this dir (abbreviation for directory), double-click on 'JupyterNotebook.ipynb'. Please note that 'ipynb' is the extension for a Jupyter Notebook file (as, for example, 'docx' is the extension for a Microsoft Word file). When you double-click on a Jupyter Notebook file, it will open in a new tab in the broswer.

Done! Now you can continue read in this notebook that you have just opened.

Basic operations in Jupyter Notebook

Now you are inside a Jupyter Notebook. It is a file, where you can write stuff, but it is special because you can also run code and see the output.

First, a Jupyter Notenook is made of cells, just like a text is made of paragraphs. Each cell can be edited in two modes:

  1. Markdown: this is the styled text mode that we use when we’re not writing code, to add documentation and instructions. What you are reading is a markdown cell.
  2. Code: this is the default mode used for Python code. Python is a programming language.

Let's see how they work.

Create a new cell

Go the tha last cell, at the bottom of this file, the one entitles 'More about Jupyter Notebook'. Click in it and you will see the borders of the cell appearing.

Now create a new cell after that, you can do it in multiple ways:

  • use the button with the sign '+' (second from the left in the toolbar)
  • go the the menu 'Insert' and choose 'Insert cell below'

A new cell will appear below. Click on it and you are inside. Before start writing, we need to choose the editing mode.

Markdown Cells

Select Markdown mode from the dropdown menu in the toolbar.

Then type the following text:

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

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 and select below
  • hit Shift+Enter

Note that the Markdown language defines that

  • the sign # indicates a title
  • the sign _ indicates italic

There is much more in the Markdown language, but we won't enter into details here. Markdown is used in a variety of cases, and not only in Jupyter Notebooks. Plenty of tutorials are available online if you are interested.

The instructions here are Markdown themselves. Double-click here to see what's behind! And don't forget to run the cell afterwards, in order to have the nice rendition back.

Code Cells

Now create a new cell, as we have seeen above.

Select Code mode from the dropdown menu in the toolbar.

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. Write the following in your cell and than run the cell as we've seen for the Markwodn cell.

print("Hello world!")

The result should appear below.

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.

Input and output sections

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).

Open a new Notebook

Navigate to the folder in which you want to open a new file. Select the type of file you want to create from the 'New' dropdown menu on the right: for a Jupyter Notebook, select 'Python 3'. A new tab with the new file will open. Give it a name by double-clicking on the name 'Untitled' and typing your new name. That's it! The new file will be saved on your computer together with the others.

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

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. It is the same as for a Microsoft Word file: you edit it through the program and you store it in your computer, the only difference is that the program runs in the broswer for a Jupyter Notebook.

More about Jupyter notebook

Resources about Jupyter Notebook are available through

For a DH oriented introduction, have a look at the first chapters (Getting setup and Getting started) of The Art of Literary Text Analysis by Stéfan Sinclair & Geoffrey Rockwell.

Getting started!

This is Hello World!, my first Jupyter Notebook.


In [1]:
print("Ciao Roma!")


Ciao Roma!