The IPython notebook has an extensive user interface that makes it appropriate for the creation of richly formatted documents. In this chapter, we will thoroughly explore the notebook's capabilities. We will also consider the pitfalls and best practices of using the notebook.
In this chapter, the following topics will be covered:
- Notebook editing and navigation, which includes cell types; adding, deleting, and moving cells; loading and saving notebooks; and keyboard shortcuts
- IPython magics
- Interacting with the operating system
- Running scripts, loading data, and saving data
- Embedding images, video, and other media with IPython's rich display system
When we open a notebook (by either clicking on its name in the dashboard or creating a new notebook), we see the following in the browser window:
In the preceding screenshot, from the top to the bottom, we see the following components:
- The Title bar (area marked 1) that contains the name of the notebook (in the preceding example, we can see Chapter 2) and information about the notebook version
- The Menu bar (area marked 2) looks like a regular application menu
- The Toolbar (area marked 3) is used for quick access to the most frequently used functionality
- In the area marked 4, an empty computation cell is shown
Starting with IPython Version 2.0, the notebook has two modes of operation:
- Edit: In this mode, a single cell comes into focus and we can enter text, execute code, and perform tasks related to that single cell. The Edit mode is activated by clicking on a cell or pressing the Enter key.
- Command: In this mode, we perform tasks related to the whole notebook structure, such as moving, copying, cutting, and pasting cells. A series of keyboard shortcuts are available to make these operations more efficient. The Command mode is activated by clicking anywhere on the notebook, outside any cell, or by pressing the Esc key.
When we open a notebook, it's in the Command mode. Let's enter into the Edit mode in our new notebook. For this, either click on the empty cell or hit Enter. The notebook's appearance will change slightly, as shown in the following screenshot:
Notice the thick border around the selected cell and the small pencil icon on the top-right corner of the notebook menu. These indicate that the notebook is in the Edit mode.
In the upcoming subsections, we will explore each of the notebook modes in detail.
The notebook is a complex tool that integrates several different technologies. It is unlikely that new (or even experienced) users will be able to memorize all the commands and shortcuts. The Help menu in the notebook has links to relevant documentation that should be consulted as often as necessary.
Note
Newcomers may want to visit the Notebook Interface Tour, which is available at http://nbviewer.ipython.org/github/ipython/ipython/blob/2.x/examples/Notebook/User%20Interface.ipynb, to get started.
It is also easy to get help on any object (including functions and methods). For example, to access help on the sum() function, run the following line of code in a cell:
sum?
Appending ?? to an object's name will provide more detailed information. Incidentally, just running ? by itself in a cell displays information about IPython features.
The other important thing to know right from the start is how to interrupt a computation. This can be done through the Kernel menu, where the kernel process running the notebook code can be interrupted and restarted. The kernel can also be interrupted by clicking on the Stop button on the toolbar.
The Edit mode is used to enter text in cells and to execute code. Let's type some code in the fresh notebook we created. As usual, we want to import NumPy and matplotlib to the current namespace, so we enter the following magic command in the first cell:
%pylab inline
Press Shift + Enter or click on the Play button on the toolbar to execute the code. Notice that either of the options causes a new cell to be added under the current cell.
Just to have something concrete to work with, let's suppose we want to compute the interest accumulated in an investment. Type the following code in three successive cells:
- In cell 1, enter the following command lines:
def return_on_investment(principal, interest_rate, number_of_years): return principal * e ** (interest_rate * number_of_years)
- In cell 2, enter the following command lines:
principal = 250 interest_rate = .034 tstart = 0.0 tend = 5.0 npoints = 6
- In cell 3, enter the following command lines:
tvalues = linspace(tstart, tend, npoints) amount_values = return_on_investment(principal, interest_rate, tvalues) plot(tvalues, amount_values, 'o') title('Return on investment, years {} to {}'.format(tstart, tend)) xlabel('Years') ylabel('Return') tstart += tend tend += tend
Now, perform the following steps:
- Run cell 1 and cell 2 in the usual way by pressing Shift + Enter.
- Run cell 3 by pressing Ctrl + Enter instead.
Notice that cell 3 continues to be selected after being executed. Keep pressing Ctrl + Enter while having cell 3 selected. The plot will be updated each time to display the return on the investment for a different 5-year period.
This is how the code works:
- In cell 1, we defined a function that computes the return on investment for given principal, interest rate, and number of years.
- In cell 2, we set actual values for the principal and interest, and then initialized variables to define the period for which we want to do the computation.
- Cell 3 computed the amount returned for a period of 5 years and plotted the results.
- Then, the variables
tstartandtendwere updated. The command lines are as follows:tstart += tend tend += tend
The effect is that, the next time the cell gets updated, time advances to the next 5-year period. So, by repeatedly pressing Ctrl + Enter, we can quickly see how the investment grows in successive 5-year periods.
There is a third way to run commands in a cell. Select cell 2 again by clicking on it. Then, press Alt + Enter in Windows or Option + Enter on a Mac. This will run cell 2 and insert a new cell under it. Leave the new cell alone for a while. We don't really need that cell, and we will learn how to delete it in the next subsection.
So, there are three ways to run the contents of a cell:
- Pressing Shift + Enter or the Play button on the toolbar. This will run the cell and select the next cell (create a new cell if at the end of the notebook). This is the most usual way to execute a cell.
- Pressing Ctrl + Enter. This will run the cell and keep the same cell selected. It's useful when we want to repeatedly execute the same cell. For example, if we want to make modifications to the existing code.
- Pressing Alt + Enter. This will run the cell and insert a new cell immediately below it.
Another useful feature of the Edit mode is tab completion. Select an empty cell and type the following command:
print am
Then, press the Tab key. A list of suggested completions appears. Using the arrow keys of the keyboard or the mouse, we can select amount_values and then press Enter to accept the completion.
A very important feature of IPython is easy access to help information. Click on an empty cell and type:
linspace
Then, press Shift + Tab. A tooltip containing information about the linspace function will appear. More information can be obtained by clicking on the + symbol at the top-right of the tooltip window. By clicking on the ^ symbol, the information is displayed in an information area at the bottom of the notebook.
The number of shortcuts available in the Command mode is substantially larger than those available in the Edit mode. Fortunately, it is not necessary to memorize all of them at once, since most actions in the Command mode are also available in the menu. In this section, we will only describe some common features of the Command mode. The following table lists some of the useful shortcuts for editing cells; the other shortcuts will be described later:
|
Shortcut |
Action |
|---|---|
|
Enter | |
|
Esc | |
|
H | |
|
S or Ctrl + S | |
|
A | |
|
B | |
|
D (press twice) | |
|
Z |
Undoes the last delete |
|
Ctrl + K | |
|
Ctrl + J | |
|
X | |
|
C | |
|
V | |
|
Shift + V |
Note
One of the most common (and frustrating) mistakes when using the notebook is to type something in the wrong mode. Remember to use Esc to switch to the Command mode and Enter to switch to the Edit mode. Also, remember that clicking on a cell automatically places it in the Edit mode, so it will be necessary to press Esc to go to the Command mode.
Go ahead and try some of the editing shortcuts in the sample notebook. Here is one example that you can try:
- Press Esc to go to the Command mode.
- Use the arrow keys to move to the empty cell we created between cell 2 and cell 3 in the previous subsection.
- Press D twice. This will cause the cell to be deleted. To get the cell back, press Z.
So far, we have used the notebook cells only to enter code. We can, however, use cells to enter the explanatory text and give structure to the notebook. The notebook uses the Markdown language to allow easy insertion of rich text in a cell. Markdown was created by John Gruber for plain text editing of HTML. See the project page at http://daringfireball.net/projects/markdown/basics for the basics of the syntax.
Let's see how it works in the notebook. If you created any other cells to experiment with the keyboard shortcuts in the previous section, delete them now so that the notebook only has the %pylab inline cell and the three cells where the interest computation is done.
Click on the %pylab inline cell and insert a cell right below it. You can either use the menu, or go to the Command mode (using the Esc key) and use the shortcut key B.
We now want to convert the new cell type to Markdown. There are three ways to do that. Start by clicking on the cell to select it, and then perform one of the following steps:
- Click on the notebook menu item Cell, select Cell Type, and then click on Markdown as shown in the following screenshot
- Select Markdown from the drop-down box on the notebook's toolbar
- Go to the Command mode by pressing Esc and then press M
Notice that once the cell is converted to Markdown, it is automatically in the Edit mode. Now, enter the following in the new Markdown cell (be careful to leave an extra blank line where indicated):
We want to know how an investment grows with a fixed interest. The *compound interest* formula states that: $$R = Pe^{rt}$$ where: - $P$ is the principal (initial investment). - $r$ is the annual interest rate, as a decimal. - $t$ is the time in years. - $e$ is the base of natural logarithms. - $R$ is the total return after $t$ years (including principal) For details, see the [corresponding Wikipedia entry](http://en.wikipedia.org/wiki/Compound_interest). We start by defining a Python function that implements this formula.
After the text is entered, press Shift + Enter to execute the cell. Instead of using the IPython interpreter to evaluate the cell, the notebook runs it through the Markdown interpreter and the cell is rendered using HTML, producing the output displayed in the following screenshot:
In this example, we use the following Markdown features:
- Text is entered normally and a new paragraph is indicated by letting an extra blank line within the text.
- Italics are indicated by enclosing the text between asterisks, as in
*compound interest*. - Formulae enclosed in double dollar (
$$) signs, as in$$R = Pe^{rt}$$, are displayed centered in the page. - An unordered list is indicated by lines starting with a dash (
-). It is important to leave blank lines before and after the list. - A single dollar (
$) sign causes the formula to be typeset inline. - Hyperlinks are specified in the following format:
[corresponding Wikipedia entry]( http://en.wikipedia.org/wiki/Compound_interest).
In a Markdown cell, mathematical formulae can be entered in LaTeX, which is an extensive language for technical typesetting that is beyond the scope of this book. Fortunately, we don't need to use the full-fledged formatting capabilities of LaTeX, but only the formula-editing features. A good quick introduction to LaTeX can be found at http://en.wikibooks.org/wiki/LaTeX/Mathematics. Learning a bit of LaTeX is very useful, since it is also used in other Python libraries. For instance, matplotlib allows LaTeX to be used in plot titles and axis labels. In the notebook, LaTeX is rendered by MathJax, a LaTeX interpreter implemented in JavaScript by Davide Cervone. Visit http://www.mathjax.org/ for details.
To add structure to the notebook, we can add headings of different sizes. Let's add a global heading to our notebook:
- Add a new cell at the very top of the notebook and change its type to Heading 1. Recall that there are three alternatives to do this:
- By navigating to Cell | Cell Type
- Using the Cell Type dropdown on the toolbar
- Using the keyboard shortcut 1 in the Command mode
- Enter a title for the notebook and run the cell using Shift + Enter.
The notebook supports six heading sizes, from Heading 1 (the largest) to Heading 6 (the smallest).
Note
The Markdown language also allows the insertion of headings, using the hash (#) symbol. Even though this saves typing, we recommend the use of the Heading 1 to Heading 6 cells. Having the headings in separate cells keeps the structure of the notebook when it is saved. This structure is used by the nbconvert utility.
The following table summarizes the types of cells we considered so far: