EC102, Lab 2, The IPython Notebook

Sep. 13, 2015

[This is the second in a series of lecture notes for the lab component of the core ‘Macroeconomics I’ course that I teach in the M.A. Economics programme at Ambedkar University, Delhi.]

Previous: Lab 1.

Getting started

In the last session we interacted with IPython using the QtConsole. While this is useful for quick calculations, there is no permanent record of the calculations we perform. Also making modifications and corrections is hard since we have to recall one command at a time to reexecute. These shortcomings are addressed by the notebook interface to IPython which stores Python code and its output together in a file which can be viewed and modified at any time using a web browser based interface.

On Linux or a Mac starting IPython Notebook is as simple as typing

$ ipython notebook

at a command shell. On Windows, the Anaconda group in the Start Menu (opened by clicking on the Windows logo on the bottom left of your screen) has an entry for starting a Notebook. However, in the current version of Anaconda this starts the program in a way which may make it impossible to access your files. A slightly more cumbersome method must be used.

From the Start Menu click on Anaconda and then click on “Anaconda Command Prompt”. This should bring up a window which shows

C:\Anaconda3>

(the text before the > sign may differ). Enter

cd %UserProfile%

and press Enter. The prompt should change to

C:\Users\your_user_name>

Now type ipython notebook and press Enter. In a while you should see some messages in this window and a new tab should open in your browser.

The browser interface of IPython does not work well with Internet Explorer. You should install a recent version of either Chrome or Firefox.

If you close the broswer tab opened by IPython by mistake, or wish to open it from another browser, just visit the enter the address localhost:8888 in the address bar at the top of your browser window.

When you are done, close your browser. Go to the Anaconda Command Prompt window and type Ctrl+C twice to shut down IPython. You can then close this window.

When IPython starts it will display in your browser the contents of the folder it was started from. Our instructions for Windows ensure that this is your home folder. IPython notebooks are ordinary files with the extension ipynb which you can store anywhere on your computer and copy or email like any other file. They can be opened for viewing, editing and executing through the web interface presented by IPython.

For now, swith to a folder where you would like to save your work. Create a new notebook by clicking on the New menu on the top-right of your browser screen and selecting Python 3. This should create a new tab. At the top, near the Jupyter logo you find the text Untitled. This is the name of your notebook and you should edit it to something meaningful. The corresponding ipynb file on your computer will get the same name. IPython will keep autosaving your work regularly, but by explicitly choosing save from the File menu or by clicking on the floppy disk icon at the top of your screen you can create a checkpoint. The File menu provides you to go back to a checkpoint if you would like to view an earlier version of your work.

Cells and editing

The grey region with In [] next to it on the left is a cell. By default cells accept Python code. Click on that region, type 2+2 and press Shift+Enter. Just like our earlier session with QtConsole the result 4 is displayed. The notebook interface also creates a new cell below the earlier cell for further input.

You can enter multiple Python statements into a single cell. Press Enter rather than Shift+Enter after all but the last line and then press Shift+Enter after the last line to execute the entire block of cell. The output shown is the value of the last statement if any (you will not see any output if the last statement is an assignment).

You can click on a cell to edit it. You must press Shift+Enter again to evaluate the modified cell. The Edit menu lets you rearrange cells in various ways.

What is happenning in essense is that each time you press Shift+Enter the cell which you have your cursor in is sent to IPython to be evaluated. Not understanding this mechanism can lead to subtle errors. The order in which IPython received inputs is the order in which you run cells by pressing Shift+Enter and not the order in which the cells are displayed on your screen. This can create results which would not make sense if you mistakenly imagine the cells as having been evaluated in the sequence in which they are written.

To see this create three separate cells in the following order and execute them in that order

x = 5
x + 2
x = 10

The output after the second cell should be 7. Now, after having executed the third cell go back and reexecute the second cell. You will get the result 12 which is not consistent with the commands in the notebook if read linearly.

Worse can happen. Use the Edit menu to delete the first and third cells. Reexecute the remaining, originally second, cell and you still get the value 12 even though in the document as it exists now the name x is not bound to any object at all. This happens because the older binding of x is still remebered from the earlier execution.

The notebook offers some mitigation against such errors. The numbers after In and Out indicated the order in which the cells were executed, so it is easy to check if the execution order is different from the document order. The option Run All in the cell menu executes all cells from the top, thereby synchronization document and execution order. Finally, the Restart option in the Kernel menu restarts the IPython process executing the statements, so that all stale name bindings are cleared and you start with a fresh slate.

Notebook cells can contain not just code. You can use the Cell Type option in the cell menu to Markdown in order to enter descriptive text. You can type any text that you would like and use the Markdown syntax to indicate formatting like headings, italics, bold, lists or links. This allows you to keep you analysis and exposition in the same place.

Notebooks can include not only textual output but also graphical output. To see a demonstration paste the following in a notebook cell and press Shift+Enter (explanations will come later).

A graph of \(f(x) = sin(x)\) should appear in the output of this cell.

Give this notebook a title by changing the Untitled at the top if you have not already done so. Save it and close the browser tab. In the command window where you had typed ipython notebook shut down the IPython process by typing Ctrl+C and then typing y when confirmation is requested. Now restart IPython and visit your saved notebook. You will find your old code and output ready for further work.

Since the output is saved along with the code in an IPython notebook it can even be viewed by those who do not have Python installed. You can use the Download as to download the document as an HTML file which can be saved and viewed by anyone with a web browser. If you upload your notebook somewhere where it has a public link (say on Dropbox or Google Drive) you can use the nbviewer service to create a new link which will display your notebook correctly formatted.

Further Reading

See the official site for IPython Notebook which has more documentation and instructional videos.