{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introducing the Notebook"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> **This is a sample section from [Learning IPython for Interactive Computing and Data Visualization, second edition](http://ipython-books.github.io/minibook/).**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Originally, IPython provided an enhanced command-line console to run Python code interactively. The Jupyter Notebook is a more recent and more sophisticated alternative to the console. Today, both tools are available, and we recommend that you learn to use both."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Launching the IPython console"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To run the IPython console, type `ipython` in an OS terminal. There, you can write Python commands and see the results instantly. Here is a screenshot:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![IPython console](images/ipython-console.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The IPython console is most convenient when you have a command-line-based workflow and you want to execute some quick Python commands."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can exit the IPython console by typing `exit`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> INFO (The Qt console): Let's mention the **Qt console**, which is similar to the IPython console, but offers additional features such as multiline editing, enhanced tab completion, image support, and so on. The Qt console can also be integrated within a graphical application written with Python and Qt. See http://jupyter.org/qtconsole/stable/ for more information."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "### Launching the Jupyter Notebook"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To run the Jupyter Notebook, open an OS terminal, go to `~/minibook/` (or into the directory where you've downloaded the book's notebooks), and type `jupyter notebook`. This will start the Jupyter server and open a new window in your browser (if that's not the case, go to the following URL: `http://localhost:8888`). Here is a screenshot of Jupyter's entry point, the **Notebook dashboard**:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![The Notebook dashboard](images/nbui-1.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> INFO: At the time of writing, the following browsers are officially supported: Chrome 13 and greater; Safari 5 and greater; Firefox 6 or greater. Other browsers may work also. Your mileage may vary."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Notebook is most convenient when you start a complex analysis project that will involve a substantial amount of interactive experimentation with your code. Other common use-cases include keeping track of your interactive session (like a lab notebook), or writing technical documents that involve code, equations, and figures."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the rest of this section, we will focus on the Notebook interface."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> TIP (Closing the Notebook server): To close the Notebook server, go to the OS terminal where you launched the server from, and press *Ctrl-C*. You may need to confirm with *y*."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "### The Notebook dashboard"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The dashboard contains several tabs:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* *Files* shows all files and notebooks in the current directory.\n",
    "* *Running* shows all kernels currently running on your computer.\n",
    "* *Clusters* lets you launch kernels for parallel computing (covered in *Chapter 5, High-Performance Computing*)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A **notebook** is an interactive document containing code, text, and other elements. A notebook is saved in a file with the `.ipynb` extension. This file is a plain text file storing a JSON data structure."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A **kernel** is a process running an interactive session. When using IPython, this kernel is a Python process. There are kernels in many languages other than Python."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> INFO (Notebook and notebook): We follow the convention to use the term of *notebook* for a file, and *Notebook* for the application and the web interface."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In Jupyter, notebooks and kernels are strongly separated. A notebook is a file, whereas a kernel is a process. The kernel receives snippets of code from the Notebook interface, executes them, and sends the outputs and possible errors back to the Notebook interface. Thus, in general, the kernel has no notion of Notebook. A notebook is persistent (it's a file), whereas a kernel may be closed at the end of an interactive session and it is therefore not persistent. When a notebook is re-opened, it needs to be re-executed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In general, no more than one Notebook interface can be connected to a given kernel. However, several IPython console can be connected to a given kernel."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "### The Notebook user interface"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To create a new notebook, click on the *New* button, and select `Notebook (Python 3)`. A new browser tab opens and shows the Notebook interface:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![A new notebook](images/nbui-2.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here are the main components of the interface, from top to bottom:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* The *notebook name*, that you can change by clicking on it. This is also the name of the `.ipynb` file.\n",
    "* The *menu bar* gives you access to several actions pertaining to either the notebook or the kernel.\n",
    "* To the right of the menu bar is the *Kernel* name. You can change the kernel language of your notebook from the *Kernel* menu. We will see in *Chapter 6, Customizing IPython* how to manage different kernel languages.\n",
    "* The *toolbar* contains icons for common actions. In particular, the dropdown menu showing `Code` lets you change the type of a cell.\n",
    "* Below is the main component of the UI: the actual Notebook. It consists of a linear list of *cells*. We will detail below the structure of a cell."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "### Structure of a notebook cell"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are two main types of cells: Markdown cells and code cells."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* A **Markdown cell** contains rich text. In addition to classic formatting options like bold or italics, we can add links, images, HTML elements, LaTeX mathematical equations, and more. We will cover Markdown in more detail in the *Ten Jupyter/IPython essentials* section of this chapter.\n",
    "* A **code cell** contains code to be executed by the kernel. The programming language corresponds to the kernel's language. We will only use Python in this book, but you can use many other languages."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can change the type of a cell by first clicking on a cell to select it, and then choosing the cell's type in the toolbar's dropdown menu showing `Markdown` or `Code`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "#### Markdown cells"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here is a screenshot of a Markdown cell:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![A Markdown cell](images/markdown-both.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The top panel shows the cell in edit mode, while the bottom one shows it in render mode. The edit mode lets you edit the text, while the render mode lets you display the rendered cell. We will explain the differences between these modes in greater detail below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "#### Code cells"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here is a screenshot of a complex code cell:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Structure of a code cell](images/nbui-3.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This code cell contains several parts:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* The **prompt number** shows the cell's number. This number increases everytime you run the cell. Since you can run cells of a notebook out of order, nothing guarantees that code numbers are linearly increasing in a given notebook.\n",
    "* The **input area** contains a multiline text editor that lets you write one or several lines of code with syntax highlighting.\n",
    "* The **widget area** may contain graphical controls; here, it displays a slider.\n",
    "* The **output area** can contain multiple outputs, here:\n",
    "    * Standard output (text in black)\n",
    "    * Error output (text with a red background)\n",
    "    * Rich output (an HTML table and an image here)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "### The Notebook modal interface"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Notebook implements a modal interface similar to some text editors such as vim. Mastering this interface may represent a small learning curve for some users."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Use the **edit mode** to write code (the selected cell has a green border, and a pen icon appears at the top right of the interface). Click inside a cell to enable the edit mode for this cell (you need to double-click with Markdown cells).\n",
    "* Use the **command mode** to operate on cells (the selected cell has a gray border, and there is no pen icon). Click outside the text area of a cell to enable the command mode (you can also press the *Escape* key)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Keyboard shortcuts are available in the Notebook interface. Type `h` to show them. We review here the most common ones (for Windows and Linux; shortcuts for Mac OS X may be slightly different)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "#### Keyboard shortcuts available in both modes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here are a few keyboard shortcuts that are always available when a cell is selected:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* `Ctrl`-`Enter`: run the cell\n",
    "* `Shift`-`Enter`: run the cell and select the cell below\n",
    "* `Alt`-`Enter`: run the cell and insert a new cell below\n",
    "* `Ctrl`-`s`: save the notebook"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "#### Keyboard shortcuts available in edit mode"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In edit mode, you can type code as usual, and you have access to the following keyboard shortcuts:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* `Esc`: switch to command mode\n",
    "* `Ctrl`-`Shift`-`-`: split the cell"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "#### Keyboard shortcuts available in command mode"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In command mode, keystrokes are bound to cell operations. **Don't write code in command mode** or unexpected things will happen! For example, typing `dd` in command mode will delete the selected cell! Here are some keyboard shortcuts available in command mode:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* `Enter`: switch to edit mode\n",
    "* `Up` or `k`: select the previous cell\n",
    "* `Down` or `j`: select the next cell\n",
    "* `y` / `m`: change the cell type to code cell / Markdown cell\n",
    "* `a` / `b`: insert a new cell above / below the current cell\n",
    "* `x` / `c` / `v`: cut / copy / paste the current cell\n",
    "* `dd`: delete the current cell\n",
    "* `z`: undo the last delete operation\n",
    "* `Shift`-`=`: merge the cell below\n",
    "* `h`: display the help menu with the list of keyboard shorcuts"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Spending some time learning these shortcuts is highly recommended."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### References"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here are a few references:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Main documentation of Jupyter at http://jupyter.readthedocs.org/en/latest/\n",
    "* Jupyter Notebook interface explained at http://jupyter-notebook.readthedocs.org/en/latest/notebook.html"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.4.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}