An introduction to the IPython notebook

The IPython web notebook is a frontend that allows for new modes of interaction with IPython: this web-based interface allows you to execute Python and IPython commands in each input cell just like you would at the IPython terminal, but you can also save an entire session as a document in a file with the .ipynb extension.

The document you are reading now is precisely an example of one such notebook, and we will show you here how to best use this new interface.

The first thing to understand is that a notebook consists of a sequence of 'cells' that can contain either text (such as this one) or code meant for execution (such as the next one):

Text cells can be written using Markdown syntax
Code cells take IPython input (i.e. Python code, %magics, !system calls, etc) like IPython at the terminal or at the Qt Console. The only difference is that in order to execute a cell, you must use Shift-Enter, as pressing Enter will add a new line of text to the cell. When you type Shift-Enter, the cell content is executed, output displayed and a new cell is created below. Try it now by putting your cursor on the next cell and typing Shift-Enter:



In [1]:

    
"This is the new IPython notebook"









    Out[1]:





'This is the new IPython notebook'

You can re-execute the same cell over and over as many times as you want. Simply put your cursor in the cell again, edit at will, and type Shift-Enter to execute.

IPython can execute shell commands, which shall be prefixed with !. For example, in the next cell, try issuing several system commands in-place with Ctrl-Enter, such as pwd and then ls:



In [2]:

    
!ls









    



00-abc-ipython.ipynb       04-howto-folding.ipynb
00-intro-ROOT.ipynb        05-howto-plot.ipynb
00-intro_ipython.ipynb     06-howto-neural-nets.ipynb
01-howto-Classifiers.ipynb Dockerfile
02-howto-Factory.ipynb     config_plotly
03-howto-gridsearch.ipynb  toy_datasets



In [3]:

    
!ls -la









    



total 24048
drwxr-xr-x  15 antares  LD\Domain Users       510 12 окт 16:52 .
drwxr-xr-x  21 antares  LD\Domain Users       714 28 сен 16:11 ..
drwxr-xr-x   5 antares  LD\Domain Users       170 12 окт 15:00 .ipynb_checkpoints
-rw-r--r--   1 antares  LD\Domain Users     20947  4 сен 19:02 00-abc-ipython.ipynb
-rw-r--r--   1 antares  LD\Domain Users    101562 12 окт 14:58 00-intro-ROOT.ipynb
-rw-r--r--   1 antares  LD\Domain Users    366615  4 сен 19:02 00-intro_ipython.ipynb
-rw-r--r--   1 antares  LD\Domain Users     37009 22 авг 22:32 01-howto-Classifiers.ipynb
-rw-r--r--   1 antares  LD\Domain Users   1048306 22 авг 22:32 02-howto-Factory.ipynb
-rw-r--r--   1 antares  LD\Domain Users     30378  4 сен 19:02 03-howto-gridsearch.ipynb
-rw-r--r--   1 antares  LD\Domain Users    115812 22 авг 22:32 04-howto-folding.ipynb
-rw-r--r--   1 antares  LD\Domain Users  10529639 12 окт 16:52 05-howto-plot.ipynb
-rw-r--r--   1 antares  LD\Domain Users     33690 22 авг 22:32 06-howto-neural-nets.ipynb
-rw-r--r--   1 antares  LD\Domain Users       146 22 авг 22:32 Dockerfile
-rw-r--r--   1 antares  LD\Domain Users        63 22 авг 22:32 config_plotly
drwxr-xr-x   5 antares  LD\Domain Users       170 12 окт 14:56 toy_datasets

In a cell, you can type anything from a single python expression to an arbitrarily long amount of code (although for reasons of readability, you are recommended to limit this to a few dozen lines):



In [4]:

    
def f(x):
    """My function
    x : parameter"""
    
    return x + 1

print "f(3) = ", f(3)









    



f(3) =  4

User interface

When you start a new notebook server with ipython notebook, your browser should open into the Dashboard, a page listing all notebooks available in the current directory as well as letting you create new notebooks. In this page, you can also drag and drop existing .py files over the file list to import them as notebooks (see the manual for further details on how these files are interpreted).

Once you open an existing notebook (like this one) or create a new one, you are in the main notebook interface, which consists of a main editing area (where these cells are contained) as well as a collapsible left panel, a permanent header area at the top, and a pager that rises from the bottom when needed and can be collapsed again.

Main editing area

Here, you can move with the arrow keys or using the scroll bars. The cursor enters code cells immediately, but only selects text (markdown) cells without entering in them; to enter a text cell, use Enter, and Shift-Enter to exit it again (just like to execute a code cell).

Header bar

The header area at the top allows you to rename an existing notebook and open up a short help tooltip. This area also indicates with a Busy mark on the right whenever the kernel is busy executing code.

Header panel

This panel contains a number of panes that can be collapsed vertically by clicking on their title bar, and the whole panel can also be collapsed by clicking on the vertical divider (note that you can not drag the divider, for now you can only click on it).

The Notebook section contains actions that pertain to the whole notebook, such as downloading the current notebook either in its original format or as a .py script, and printing/exporting it to different markup languages.

The Cell section lets you manipulate individual cells, and the names should be fairly self-explanatory.

The Kernel section lets you signal the kernel executing your code. Interrupt does the equivalent of hitting Ctrl-C at a terminal, and Restart fully kills the kernel process and starts a fresh one. Obviously this means that all your previous variables are destroyed, but it also makes it easy to get a fresh kernel in which to re-execute a notebook.

The Help section contains links to the documentation of some projects closely related to IPython as well as the minimal keybindings you need to know. But you should use Esc-h (or click the QuickHelp button at the top) and learn some of the other keybindings, as it will make your workflow much more fluid and efficient.

Please pay attention that there are two modes: Command mode and Edit mode (details in the reference: press Esc-h).

Whenever IPython needs to display additional information, such as when you type somefunction? in a cell, the notebook opens a pane at the bottom where this information is shown. You can keep this pager pane open for reference (it doesn't block input in the main area) or dismiss it by clicking on its divider bar.

Try by executing the following cell:



In [5]:

    
dict??

Tab completion and tooltips

The notebook uses the same underlying machinery for tab completion that IPython uses at the terminal, but displays the information differently. Whey you complete with the Tab key, IPython shows a drop list with all available completions. If you type more characters while this list is open, IPython automatically eliminates from the list options that don't match the new characters; once there is only one option left you can hit Tab once more (or Enter) to complete. You can also select the completion you want with the arrow keys or the mouse, and then hit Enter.

In addition, if you hit Tab inside of open parentheses, IPython will search for the docstring of the last object left of the parens and will display it on a tooltip. For example, type list(<TAB> and you will see the docstring for the builtin list constructor:



In [6]:

    
# Position your cursor after the ( and hit the Tab key:
list()









    Out[6]:





[]

Display of complex objects

As the 'tour' notebook shows, the IPython notebook has fairly sophisticated display capabilities. In addition to the examples there, you can study the display_protocol notebook in this same examples folder, to learn how to customize arbitrary objects (in your own code or external libraries) to display in the notebook in any way you want, including graphical forms or mathematical expressions.

Plotting support

To turn on inline plotting, you can use %matplotlib magic, after executing it the plots will not be shown in a new window (as done usually), but will be shown in notebook:



In [7]:

    
%matplotlib inline

# an alternative is the following code:
# %pylab inline
# which does also many imports from numpy and matplotlib libraries and this is very handy, 
# though one shall remember that global imports are evil



In [8]:

    
import matplotlib.pyplot as plt

plt.plot([1, 2, 4, 8, 16])









    Out[8]:





[<matplotlib.lines.Line2D at 0x10c944710>]

Other handy features

IPython allows you upload files on the server and modify any text files on the server. Revisit Dashboard to check these features. Also, from Dashboard you can start shell sessions, which is good when some configuring on a server-side is needed.

However, running IPython locally is very popular option and doesn't require much experience. But the greatest benefit you can get from using IPython on your server. Note, that apart from installing IPython and giving access from network, you should protect access .

IPython quick reference

short summary of special commands available will be shown after executing this cell:



In [9]:

    
%quickref