An introduction to the Jupyter Notebook. Intentionally very light. It assumes that "fortune" and "cowsay" are installed.

notebook_introduction.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A Jupyter Notebook allows for combining text, code and commands. It's kind of like Google Docs for science. Because of this, it has begun to be a powerful mechanism for reproducible science as you can distrubute your whole analysis. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Notebook itself is a series of \"cells.\" This cell is just text, but as you'll see shortly, there are other cell types as well. \n",
    "\n",
    "You can edit this cell by double clicking on the text within the cell -- please do this now. You'll know you're editing the cell because it'll visibly change and allow you to type into it. In addition, the cell itself will be highlighted with a green border."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you click out of the cell you're editing, you'll see that it remains grey. Please try that now by clicking on the text in this cell.\n",
    "\n",
    "Why does the cell remain grey when it looked pretty before? It's because the cell has not been reevaluated. The reason a cell needs to be evaluated before being shown in its pretty form is because the content within the cell might contain formatting constructs or code. The type of cell determines how the cell is evaluated (you can see what type the cell is by looking at the first pulldown menu on the toolbar). This cell has a type called Markdown. \n",
    "\n",
    "**IMPORTANT**: In order to evaluate a cell that is highlighted, press \"shift + enter\" on your keyboard."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Markdown is a very simple way to do **formatting**, embedding [hyperlinks](https://www.ihighfive.com/) and media. Included in this cell is an example of how to embed a graphic. However, the Markdown syntax to show the graphic has been commented out. In order to see the image, please:\n",
    "\n",
    "* edit this cell (double click on it)\n",
    "* find the line in this cell containing `<!---` and delete the line\n",
    "* find the line in this cell containing `--->` and delete the line\n",
    "* execute the cell (shift + enter)\n",
    "\n",
    "Those marks, the `<!---` and `--->` lines, indicate that the text that follows is a \"comment\" and should not be interpreted as Markdown. Once the \"comment\" markers are removed, the line between the markers will be interpreted.\n",
    "\n",
    "\n",
    "<!---\n",
    "\n",
    "![Rick and Morty is awesome](http://vignette2.wikia.nocookie.net/rickandmorty/images/1/1e/Rick_and_morty_icon.png/revision/latest/scale-to-width-down/309?cb=20150805041642)\n",
    "\n",
    "--->"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are other cell types as well. The other one that we need to know about right now is called a \"code\" cell. When \"code\" cells are evaluated, anything inside of them is interpreted in the programming language the notebook is using. By default, Jupyter Notebooks use Python. The next cell is an example of a code cell. \n",
    "\n",
    "Please click on the next cell now.\n",
    "\n",
    "The first thing you might notice is that the first pulldown menu on the toolbar will say \"Code\" instead of \"Markdown.\" The code in the cell will first produce a string of As, Ts, Gs, and Cs, and then print k-mers within the sequence.\n",
    "\n",
    "Please evaluate the code cell to see the k-mers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# This is a code cell. \n",
    "# In a code cell, assuming the language is Python, anything starting with a hash (#) is a comment\n",
    "# Please evaluate this cell by first clicking on the cell and then pressing \"shift + enter\" on your keyboard\n",
    "n = 10\n",
    "k = 5\n",
    "seq = ''.join('ATGC'[i % 4] for i in range(n))\n",
    "for i in range(n - k):\n",
    "    print(seq[i:i+k])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Code cells can also be used to execute bash commands (e.g., `ls`, `grep`, `less`) just like you would in a terminal."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# A code cell can be used to execute bash commands\n",
    "# Let's look at what our current working directory is and what files are in that directory.\n",
    "!pwd"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When you run a bash command, it must be prefixed with an exclamation point (\"!\"). The exclamation point tells Jupyter that the line should be run through bash as though it were run on the terminal. So for instance, let's list out all of the files in the current working directory using a long listing."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "!ls -l"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You might wonder what system this is running on? Well, let's find out!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "!echo \"You're currently connected to: `hostname`\" | cowsay"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What happens if a code cell takes a long time to complete? Well, lets try that:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# This is a code cell that will take a long time to complete. Please click on it, and evalute it.\n",
    "# While this cell evaluates, it will print out messages.\n",
    "print(\"You cannot evaluate other cells while a cell is currently being evaluated.\")\n",
    "print(\"The asterisk symbol ('*') to the left of this cell indicates that it is currently running.\")\n",
    "print(\"This cell will now run for 10 seconds.\")\n",
    "print(\"\")\n",
    "\n",
    "for i in range(10):\n",
    "    print(\"Still running...\")\n",
    "    !sleep 1\n",
    "\n",
    "print(\"\")\n",
    "print('This cell is \"complete\" once you see this message printed.')\n",
    "print('Please note that there is no longer an asterisk to the left.')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the event of an internet hiccup, you might find that cells no longer execute or that there is a warning message at the top of the page. You can tell Jupyter to reconnect by going to the \"Kernel\" pulldown menu and selecting \"Reconnect.\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Last, there are a few other things that we won't need for the QIIME tutorial. Briefly, you can add and remove cells using the toolbar above, run all of the cells in a notebook easily, save, copy/paste, etc. You can even use the Notebook for slideshow [presentations](http://www.damian.oquanta.info/posts/make-your-slides-with-ipython.html). \n",
    "\n",
    "Where to get more information:\n",
    "\n",
    "* [Project Jupyter](http://jupyter.org/)\n",
    "* Want a temporary Notebook? Try [tmpnb](http://tmpnb.org)\n",
    "* A Markdown [cheat sheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "!fortune | cowsay"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}