Introduction to matplotlib.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Michael Droettboom, Space Telescope Science Institute\n",
    "- Damon McDougall, University of Texas at Austin\n",
    "\n",
    "based on materials by:\n",
    "- Nicolas Rougier, INRIA http://www.labri.fr/perso/nrougier/teaching/matplotlib/\n",
    "\n",
    "This notebook is available at: http://github.com/dmcdougall/strata-mpl-tutorial"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "matplotlib is probably the single most used Python package for 2D-graphics. It provides both a very quick way to visualize data from Python and publication-quality figures in many formats. We are going to explore matplotlib in interactive mode covering most common cases.\n",
    "\n",
    "This tutorial assumes matplotlib 1.4.3 and Jupyter/IPython 4.0.0.  Some things may work differently on earlier or later versions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Some terminology"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Parts of a figure](fig_map.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Starting Jupyter with matplotlib"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Set up matplotlib for use with the Jupyter (IPython) notebook using the `%matplotlib` magic:\n",
    "\n",
    "   `%matplotlib [backend]`\n",
    "   \n",
    "Where backend is one of:\n",
    "\n",
    "  - `notebook`/`nbagg`: Interactive plots inline in the notebook\n",
    "  - `osx`, `qt4`, `qt5`, `gtk`, `gtk3`, `wx`, `tk`: Open plots in another window using the given GUI toolkit\n",
    "  \n",
    "**You can not change the backend once selected for the kernel session**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/home/mdboom/miniconda/envs/matplotlib-tutorial/lib/python2.7/site-packages/IPython/kernel/__init__.py:13: ShimWarning: The `IPython.kernel` package has been deprecated. You should import from ipykernel or jupyter_client instead.\n",
      "  \"You should import from ipykernel or jupyter_client instead.\", ShimWarning)\n"
     ]
    }
   ],
   "source": [
    "%matplotlib notebook"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also use `%pylab` magic, which will also import a bunch of things into the top-level namespace.  While this can be convenient, it increases the likelihood of namespace clashes, and makes it harder to copy code from the notebook to a script for use in \"production\".\n",
    "\n",
    "Instead, we recommend:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from matplotlib import pyplot as plt\n",
    "plt.ion()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For this tutorial, it's most useful to draw the plots in a separate window, so we'll restart the kernel and use a GUI backend from here on out."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%matplotlib tk"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before we start the tutorial, we'll make sure to use all of matplotlib's defaults settings.  Everyone taking this tutorial will therefore see identical output."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from matplotlib import rcdefaults\n",
    "rcdefaults()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Pyplot vs. Object-oriented API"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "matplotlib has two APIs: `pyplot` and the object-oriented API.\n",
    "\n",
    "`pyplot` is convenient for interactive plotting, since it remembers \"state\", such as the last `Axes` that was plotted to, in order to plot the next item to it again.  **Because it is stateful, `pyplot` is not recommended for use in application code.**\n",
    "\n",
    "The object oriented API addresses objects directly, and while more verbose, doesn't have the state pitfalls that `pyplot` does."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Part I: Simple plot"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Matplotlib comes with a set of default settings that allow customizing all kinds of properties. You can control the defaults of almost every property in matplotlib: figure size and dpi, line width, color and style, axes, axis and grid properties, text and font properties and so on. While matplotlib defaults are rather good in most cases, you may want to modify some properties for specific cases."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "# Numbers 0 - 256\n",
    "X = np.linspace(-np.pi, np.pi, 256, endpoint=True)\n",
    "# cosine(X), sin(X)\n",
    "C, S = np.cos(X), np.sin(X)\n",
    "\n",
    "line1, = plt.plot(X, C)\n",
    "line2, = plt.plot(X, S)\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Changing colors and line widths"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First step, we want to have the cosine in blue and the sine in red and a slightly thicker line for both of them.\n",
    "\n",
    "**Since we're not creating a new figure here, these changes will affect the open figure above.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<matplotlib.lines.Line2D at 0x7f4032ebef50>]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "line1.set_color('blue')\n",
    "line2.set_color('red')\n",
    "\n",
    "line1.set_linewidth(2.5)\n",
    "line2.set_linewidth(2.5)\n",
    "\n",
    "# You could also set these at creation time:\n",
    "plt.plot(X, C, color=\"blue\", linewidth=2.5)\n",
    "plt.plot(X, S, color=\"red\",  linewidth=2.5)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setting limits"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Current limits of the figure are a bit too tight and we want to make some space in order to clearly see all data points."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(-1.1000000000000001, 1.0999165211263138)"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plt.xlim(X.min()*1.1, X.max()*1.1)\n",
    "plt.ylim(C.min()*1.1, C.max()*1.1)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setting ticks"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Current ticks are not ideal because they do not show the interesting values ($\\pm\\pi$, $\\pm\\pi/2$) for sine and cosine. We'll change them such that they show only these values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "([<matplotlib.axis.YTick at 0x7f4032f81f50>,\n",
       "  <matplotlib.axis.YTick at 0x7f4032f81a50>,\n",
       "  <matplotlib.axis.YTick at 0x7f4032f09790>],\n",
       " <a list of 3 Text yticklabel objects>)"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plt.xticks( [-np.pi, -np.pi/2, 0, np.pi/2, np.pi])\n",
    "plt.yticks([-1, 0, +1])\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setting tick labels"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ticks are now properly placed but their label is not very explicit. We could guess that 3.142 is π but it would be better to make it explicit. When we set tick values, we can also provide a corresponding label in the second argument list. Note that we'll use $\\LaTeX$ to allow for nice rendering of the label: we could also use Unicode."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "([<matplotlib.axis.YTick at 0x7f4032f81f50>,\n",
       "  <matplotlib.axis.YTick at 0x7f4032f81a50>,\n",
       "  <matplotlib.axis.YTick at 0x7f4032f09790>],\n",
       " <a list of 3 Text yticklabel objects>)"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plt.xticks([-np.pi, -np.pi/2, 0, np.pi/2, np.pi],\n",
    "       [r'$-\\pi$', r'$-\\pi/2$', r'$0$', r'$+\\pi/2$', r'$+\\pi$'])\n",
    "\n",
    "plt.yticks([-1, 0, +1],\n",
    "       [r'$-1$', r'$0$', r'$+1$'])\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Moving spines"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Spines are the lines connecting the axis tick marks and noting the boundaries of the data area. They can be placed at arbitrary positions and until now, they were on the border of the axis. We'll change that since we want to have them in the middle. Since there are four of them (top/bottom/left/right), we'll discard the top and right by setting their visibility to `False` and we'll move the bottom and left ones to coordinate 0 in data space coordinates."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "ax = plt.gca()\n",
    "ax.spines['right'].set_visible(False)\n",
    "ax.spines['top'].set_visible(False)\n",
    "ax.xaxis.set_ticks_position('bottom')\n",
    "ax.spines['bottom'].set_position(('data',0))\n",
    "ax.yaxis.set_ticks_position('left')\n",
    "ax.spines['left'].set_position(('data',0))\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Adding a legend"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's add a legend in the upper left corner. This only requires adding labels to the lines."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<matplotlib.legend.Legend at 0x7f4032e9ef10>"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "line1.set_label(\"cosine\")\n",
    "line2.set_label(\"sine\")\n",
    "\n",
    "plt.legend(loc=\"upper left\", frameon=False)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Annotate some points"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's annotate some interesting points using the annotate command. We chose the $2\\pi/3$ value and we want to annotate both the sine and the cosine. We'll first draw a marker on the curve as well as a straight dotted line. Then, we'll use the annotate command to display some text with an arrow."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<matplotlib.text.Annotation at 0x7f4032e13510>"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "t = 2*np.pi/3\n",
    "plt.plot([t,t],[0,np.cos(t)], color ='blue', linewidth=2.5, linestyle=\"--\")\n",
    "plt.scatter([t,],[np.cos(t),], 50, color ='blue')\n",
    "\n",
    "plt.annotate(r'$\\sin(\\frac{2\\pi}{3})=\\frac{\\sqrt{3}}{2}$',\n",
    "             xy=(t, np.sin(t)), xycoords='data',\n",
    "             xytext=(+10, +30), textcoords='offset points', fontsize=16,\n",
    "             arrowprops=dict(arrowstyle=\"->\", connectionstyle=\"arc3,rad=.2\"))\n",
    "\n",
    "plt.plot([t,t],[0,np.sin(t)], color ='red', linewidth=2.5, linestyle=\"--\")\n",
    "plt.scatter([t,],[np.sin(t),], 50, color ='red')\n",
    "\n",
    "plt.annotate(r'$\\cos(\\frac{2\\pi}{3})=-\\frac{1}{2}$',\n",
    "             xy=(t, np.cos(t)), xycoords='data',\n",
    "             xytext=(-90, -50), textcoords='offset points', fontsize=16,\n",
    "             arrowprops=dict(arrowstyle=\"->\", connectionstyle=\"arc3,rad=.2\"))\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Devil is in the details"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The tick labels are now hardly visible because of the blue and red lines. We can make them bigger and we can also adjust their properties such that they'll be rendered on a semi-transparent white background. This will allow us to see both the data and the labels."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "for label in ax.get_xticklabels() + ax.get_yticklabels():\n",
    "    label.set_fontsize(16)\n",
    "    label.set_bbox(dict(facecolor='white', edgecolor='None', alpha=0.65 ))\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Interlude: Styling"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Almost all style defaults can be controlled in the `matplotlibrc` which lives in:\n",
    "    \n",
    "- `~/.config/matplotlib` on Linux\n",
    "- `~/.matplotlib` on Mac\n",
    "- `C:\\Documents and Settings\\$USER\\.matplotlib` on Windows\n",
    "    \n",
    "See http://matplotlib.org/users/customizing.html for the list of things that may be configured.\n",
    "\n",
    "However, matplotlib also comes with a number of \"styles\" that make it easy to change defaults."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[u'dark_background', u'bmh', u'grayscale', u'ggplot', u'fivethirtyeight']"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from matplotlib import style\n",
    "style.available"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "style.use('ggplot')\n",
    "plt.figure()\n",
    "plt.plot(X, C)\n",
    "plt.plot(X, S)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "style.use('fivethirtyeight')\n",
    "plt.figure()\n",
    "plt.plot(X, C)\n",
    "plt.plot(X, S)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# Reset to defaults (more obvious method coming in matplotlib 1.5)\n",
    "import matplotlib\n",
    "matplotlib.rcdefaults()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Part II: Figures, Subplots, Axes and Ticks"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So far we have used implicit figure and axes creation. This is handy for fast plots. We can have more control over the display using figure, subplot, and axes explicitly. A figure in matplotlib means the whole window in the user interface. Within this figure there can be subplots. While subplot positions the plots in a regular grid, axes allows free placement within the figure. Both can be useful depending on your intention. We've already worked with figures and subplots without explicitly calling them. When we call plot, matplotlib calls `gca()` to get the current axes and `gca` in turn calls `gcf()` to get the current figure. If there is none it calls `figure()` to make one, strictly speaking, to make a `subplot(1, 1, 1)`. Let's look at the details."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Subplots"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With `subplot` you can arrange plots in a regular grid. You need to specify the number of rows and columns and the number of the plot. \n",
    "\n",
    "Note that the `gridspec` command is a more powerful alternative."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "plt.figure()\n",
    "plt.subplot(2, 1, 1)\n",
    "plt.subplot(2, 1, 2)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "plt.figure()\n",
    "plt.subplot(1, 2, 1)\n",
    "plt.subplot(1, 2, 2)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Axes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `axes` command allows more manual placement of the plots in the figure."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "plt.figure()\n",
    "plt.axes([0.1, 0.1, 0.8, 0.8])\n",
    "plt.axes([0.2, 0.2, 0.3, 0.3])\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "plt.figure()\n",
    "plt.axes([0.1, 0.1, 0.5, 0.5])\n",
    "plt.axes([0.2, 0.2, 0.5, 0.5])\n",
    "plt.axes([0.3, 0.3, 0.5, 0.5])\n",
    "plt.axes([0.4, 0.4, 0.5, 0.5])\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Ticks"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Well-formatted ticks are an important part of publishing-ready figures. Matplotlib provides a totally configurable system for ticks. There are tick locators to specify where ticks should appear and tick formatters to give ticks the appearance you want. Major and minor ticks can be located and formatted independently from each other. Per default minor ticks are not shown, i.e. there is only an empty list for them because it is as `NullLocator` (see below)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- `NullLocator`: no ticks\n",
    "\n",
    "![NullLocator](ticks-NullLocator.png)\n",
    "\n",
    "- `IndexLocator`: Place a tick on every multiple of some base number of points plotted.\n",
    "\n",
    "![IndexLocator](ticks-IndexLocator.png)\n",
    "\n",
    "- `FixedLocator`: Tick locations are fixed.\n",
    "\n",
    "![FixedLocator](ticks-FixedLocator.png)\n",
    "\n",
    "- `AutoLocator`: Select no more than *n* intervals at nice locations.\n",
    "\n",
    "![AutoLocator](ticks-AutoLocator.png)\n",
    "\n",
    "- `LogLocator`: Logarithmic scale.\n",
    "\n",
    "![LogLocator](ticks-LogLocator.png)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Object-oriented interaction\n",
    "\n",
    "Instead of remembering which `figure` is the 'current' figure and which `axes` is the current axes, you can treat `plt.figure()` as a factory method that gives you the correct object with the appropriate backend.\n",
    "\n",
    "For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<matplotlib.axes._subplots.AxesSubplot at 0x10e404b38>"
      ]
     },
     "execution_count": 40,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plt.figure()\n",
    "plt.subplot(1, 1, 1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Is equivalent to:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig = plt.figure()\n",
    "ax = fig.add_subplot(1, 1, 1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The state machine can be a problem when scripting, so capturing the relevant objects in variables means you can interact with their methods in an object-oriented fashion:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "ax.plot([1, 2, 3])\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Animation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First step is to create a blank figure:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from matplotlib import pyplot as plt\n",
    "import numpy as np\n",
    "\n",
    "# New figure with white background\n",
    "fig = plt.figure(figsize=(6,6), facecolor='white')\n",
    "\n",
    "# New axis over the whole figure, no frame and a 1:1 aspect ratio\n",
    "ax = fig.add_axes([0,0,1,1], frameon=False, aspect=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we need to create several rings. For this, we can use the scatter plot object that is generally used to visualize points cloud, but we can also use it to draw rings by specifying we don't have a facecolor. We have also to take care of initial size and color for each ring such that we have all size between a minimum and a maximum size and also to make sure the largest ring is almost transparent."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "((0, 1), [])"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Number of ring\n",
    "n = 50\n",
    "size_min = 50\n",
    "size_max = 50*50\n",
    "\n",
    "# Ring position\n",
    "P = np.random.uniform(0,1,(n,2))\n",
    "\n",
    "# Ring colors\n",
    "C = np.ones((n,4)) * (0,0,0,1)\n",
    "# Alpha color channel goes from 0 (transparent) to 1 (opaque)\n",
    "C[:,3] = np.linspace(0,1,n)\n",
    "\n",
    "# Ring sizes\n",
    "S = np.linspace(size_min, size_max, n)\n",
    "\n",
    "# Scatter plot\n",
    "scat = ax.scatter(P[:,0], P[:,1], s=S, lw = 0.5,\n",
    "                  edgecolors = C, facecolors='None')\n",
    "\n",
    "# Ensure limits are [0,1] and remove ticks\n",
    "ax.set_xlim(0,1), ax.set_xticks([])\n",
    "ax.set_ylim(0,1), ax.set_yticks([])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we need to write the update function for our animation. We know that at each time step each ring should grow be more transparent while largest ring should be totally transparent and thus removed. Of course, we won't actually remove the largest ring but re-use it to set a new ring at a new random position, with nominal size and color. Hence, we keep the number of ring constant."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def update(frame):\n",
    "    global P, C, S\n",
    "\n",
    "    # Every ring is made more transparent\n",
    "    C[:,3] = np.maximum(0, C[:,3] - 1.0/n)\n",
    "\n",
    "    # Each ring is made larger\n",
    "    S += (size_max - size_min) / n\n",
    "\n",
    "    # Reset ring specific ring (relative to frame number)\n",
    "    i = frame % 50\n",
    "    P[i] = np.random.uniform(0,1,2)\n",
    "    S[i] = size_min\n",
    "    C[i,3] = 1\n",
    "\n",
    "    # Update scatter object\n",
    "    scat.set_edgecolors(C)\n",
    "    scat.set_sizes(S)\n",
    "    scat.set_offsets(P)\n",
    "\n",
    "    # Return the modified object\n",
    "    return scat,"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Last step is to tell matplotlib to use this function as an update function for the animation and display the result or save it as a movie:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from matplotlib.animation import FuncAnimation\n",
    "animation = FuncAnimation(fig, update, interval=10, blit=True, frames=200)\n",
    "# animation.save('rain.gif', writer='imagemagick', fps=30, dpi=40)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Further Examples"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![scatter](scatter.png)\n",
    "\n",
    "![bar](bar.png)\n",
    "\n",
    "![contour](contour.png)\n",
    "\n",
    "![imshow](imshow.png)\n",
    "\n",
    "![quiver](quiver.png)\n",
    "\n",
    "![pie](pie.png)\n",
    "\n",
    "![grid](grid.png)\n",
    "\n",
    "![polar](polar.png)\n",
    "\n",
    "![plot3d](plot3d.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Fun stuff"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## An extra dimension\n",
    "\n",
    "There is limited support in matplotlib for three-dimensional visualisations:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "from mpl_toolkits.mplot3d import Axes3D\n",
    "import matplotlib.tri as mtri\n",
    "\n",
    "# u, v are parameterisation variables\n",
    "u = (np.linspace(0, 2.0 * np.pi, endpoint=True, num=50) * np.ones((10, 1))).flatten()\n",
    "v = np.repeat(np.linspace(-0.5, 0.5, endpoint=True, num=10), repeats=50).flatten()\n",
    "\n",
    "# This is the Mobius mapping, taking a u, v pair and returning an x, y, z\n",
    "# triple\n",
    "x = (1 + 0.5 * v * np.cos(u / 2.0)) * np.cos(u)\n",
    "y = (1 + 0.5 * v * np.cos(u / 2.0)) * np.sin(u)\n",
    "z = 0.5 * v * np.sin(u / 2.0)\n",
    "\n",
    "# Triangulate parameter space to determine the triangles\n",
    "tri = mtri.Triangulation(u, v)\n",
    "\n",
    "fig = plt.figure()\n",
    "ax = fig.add_subplot(1, 1, 1, projection='3d')\n",
    "\n",
    "# The triangles in parameter space determine which x, y, z points are\n",
    "# connected by an edge\n",
    "ax.plot_trisurf(x, y, z, triangles=tri.triangles, cmap=plt.cm.CMRmap)\n",
    "ax.set_zlim(-1, 1)\n",
    "plt.show()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Publication tricks\n",
    "\n",
    "For scientific publications, it's common to use the LaTeX typesetting language.  Matplotlib supports this natively, embedding LaTeX output in place of all text:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import matplotlib\n",
    "matplotlib.rcdefaults()\n",
    "\n",
    "# Set fancy LaTeX fonts\n",
    "matplotlib.rcParams['text.usetex'] = True\n",
    "matplotlib.rcParams['font.family'] = 'serif'\n",
    "matplotlib.rcParams['font.serif'] = 'Computer Modern Roman'\n",
    "\n",
    "from matplotlib import pyplot as plt\n",
    "\n",
    "# Set up very scientific data\n",
    "x = np.linspace(0, 0.28, num=500, endpoint=True)\n",
    "gaussian1 = np.exp(-x * x / (2.0 * 0.06 * 0.06))\n",
    "gaussian2 = np.exp(-(x - 0.14) * (x - 0.14) / (2.0 * 0.002 * 0.002))\n",
    "\n",
    "fig = plt.figure()\n",
    "ax = fig.add_subplot(1, 1, 1)\n",
    "\n",
    "ax.plot(x, gaussian1 + 3 * gaussian2)\n",
    "ax.set_xlim(0, 0.28)\n",
    "ax.set_yticklabels([])\n",
    "ax.set_xlabel(r'Blood alcohol concentration ($\\%$)')\n",
    "ax.set_ylabel(r'Programming skill')\n",
    "ax.set_title(r'The Ballmer peak')\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The default LaTeX font is Computer Modern Roman.  Using this font in your figures will mean that all the fonts in the produced publication are consistent.  The results look very professional with this approach.\n",
    "\n",
    "If you're submitting to a journal that uses a different font, find out what it is and make matplotlib use it in place of all text."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "## XKCD\n",
    "\n",
    "With just one function, `plt.xkcd()`, we can disregard all scientific validity:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import matplotlib\n",
    "matplotlib.rcdefaults()\n",
    "from matplotlib import pyplot as plt\n",
    "plt.xkcd()\n",
    "\n",
    "# Set up very scientific data\n",
    "x = np.linspace(0, 0.28, num=500, endpoint=True)\n",
    "gaussian1 = np.exp(-x * x / (2.0 * 0.06 * 0.06))\n",
    "gaussian2 = np.exp(-(x - 0.14) * (x - 0.14) / (2.0 * 0.002 * 0.002))\n",
    "\n",
    "fig = plt.figure()\n",
    "ax = fig.add_subplot(1, 1, 1)\n",
    "\n",
    "ax.plot(x, gaussian1 + 3 * gaussian2)\n",
    "ax.set_xlim(0, 0.28)\n",
    "ax.set_yticklabels([])\n",
    "ax.set_xlabel('Blood alcohol concentration (%)')\n",
    "ax.set_ylabel('Programming skill')\n",
    "ax.set_title('The Ballmer peak')\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Where can I learn more?\n",
    "\n",
    "Mike Droettboom and I borrowed heavily (with permission) from Nicolas Rougier's tutorial.  We recommend you go and read it: http://www.labri.fr/perso/nrougier/teaching/matplotlib/\n",
    "\n",
    "The [matplotlib website](http://matplotlib.org/) is a good place to start, but there are several major areas that provide help:\n",
    "\n",
    "1.  If you know what your plot looks like but not what it's called, check out the [gallery](http://matplotlib.org/gallery.html), as we might already have example usage demonstrated here;\n",
    "2.  We also have a [list of all matplotlib examples](http://matplotlib.org/examples/index.html) which you can browse online;\n",
    "3.  If you know the name of the plotting command you're trying to use and need quick access to its documentation, there's a [list of plotting commands](http://matplotlib.org/api/pyplot_summary.html) available;\n",
    "\n",
    "## External learning resources\n",
    "\n",
    "The scientific python community have [produced some excellent resources](http://matplotlib.org/resources/index.html) that lie external to matplotlib's website.  There are web tutorials, video tutorials from the SciPy conferences, and various published works.  Check them out.\n",
    "\n",
    "## Still need help?\n",
    "\n",
    "If all the above didn't answer your question or problem, check out the [faq](http://matplotlib.org/faq/index.html), matplotlib has a friendly and inclusive community of users and developers.  Feel free to pick their brains on the users mailing list: https://mail.python.org/mailman/listinfo/matplotlib-users\n",
    "\n",
    "## I want to use matplotlib for my research\n",
    "\n",
    "Awesome!  It's free and open source software.  All we ask is that you cite matplotlib in your paper's bibliography.  See [here](http://matplotlib.org/citing.html) for more details."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "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.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}