matplotlib_beyond_basics.ipynb

{
 "metadata": {
  "name": "matplotlib_beyond_basics"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      " Matplotlib: Beyond the basics\n",
      "===============================\n",
      "\n",
      "Status and plan for today\n",
      "=========================\n",
      "\n",
      "By now you know the basics of:\n",
      "\n",
      "- Numpy array creation and manipulation.\n",
      "- Display of data in numpy arrays, sufficient for interactive exploratory work.\n",
      "\n",
      "Hopefully after this week you will:\n",
      "\n",
      "- Know how to polish those figures to the point where they can go to a journal.\n",
      "- Understand matplotlib's internal model enough to:\n",
      "  - know where to look for knobs to fine-tune\n",
      "  - better understand the help and examples online\n",
      "  - use it as a development platform for complex visualization\n",
      "\n",
      "<style type=\"text/css\">\n",
      "    .exercise {\n",
      "        border: solid 3px #AAE;\n",
      "        background: #EEF;\n",
      "        padding: 50px 10px 50px 10px;\n",
      "        display: inline-block;\n",
      "        font-size: 110%;\n",
      "    }\n",
      "</style>"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Matplotlib's main APIs: ``pyplot`` and object-oriented\n",
      "======================================================\n",
      "\n",
      "Matplotlib is a library that can be thought of as having two main ways of being\n",
      "used:\n",
      "\n",
      "- via ``pyplot`` calls, as a high-level, matlab-like library that automatically\n",
      "  manages details like figure creation.\n",
      "\n",
      "- via its internal object-oriented structure, at the cost of slightly more verbose calls for the\n",
      "  most common use cases.\n",
      "\n",
      "The pyplot api:\n",
      "\n",
      "- Easiest to use, especially for those familiar with MATLAB.\n",
      "- Sufficient for simple and moderately complex plots.\n",
      "- Does not offer complete control over all details.\n",
      "\n",
      "Before we look at our first simple example, we must activate pylab support in the notebook. Execute one of the following:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# use this for floating figures:\n",
      "#%pylab\n",
      "\n",
      "# use this for inlined figures:\n",
      "%pylab inline"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "x = np.linspace(0, 2 * np.pi)\n",
      "y = np.sin(x)\n",
      "\n",
      "plt.plot(x,y, label='sin(x)')\n",
      "plt.legend()\n",
      "plt.title('Harmonic')\n",
      "plt.xlabel('x')\n",
      "plt.ylabel('y')\n",
      "\n",
      "# Add one line to that plot\n",
      "z = np.cos(x)\n",
      "plt.plot(x, z, label='cos(x)')\n",
      "\n",
      "# Make a second figure with a simple plot\n",
      "plt.figure()\n",
      "plt.plot(x, np.sin(2 * x), label='sin(2x)')\n",
      "plt.legend()\n",
      "\n",
      "# ^^ Hard to keep track of switching state with multiple figures, axes"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Here is how to create the same two plots using the object oriented interface:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "f, ax0 = plt.subplots()         # we manually make a figure and axis\n",
      "ax0.plot(x, y, label='sin(x)')  # it's the axis who plots\n",
      "ax0.legend()\n",
      "ax0.set_title('Harmonic')       # we set the title on the axis\n",
      "ax0.set_xlabel('x')             # same with labels\n",
      "ax0.set_ylabel('y')\n",
      "\n",
      "# Make a second figure with a simple plot.  We can name the figure with a\n",
      "# different variable name as well as its axes, and then control each\n",
      "f1, ax1 = plt.subplots()\n",
      "ax1.plot(x, np.sin(2 * x), label='sin(2x)')\n",
      "ax1.legend()\n",
      "\n",
      "# Since we now have variables for each axis, we can add back to the first\n",
      "# figure even after making the second\n",
      "ax0.plot(x, np.cos(x), label='cos(x)')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Note that these objects (figures, axes, etc.) still exist, even if you use mostly the top-level pyplot calls.\n",
      "\n",
      "Important commands to know about, and which matplotlib uses internally a lot:\n",
      "\n",
      "    gcf()  # get current figure\n",
      "    gca()  # get current axis"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Making subplots\n",
      "===============\n",
      "\n",
      "The simplest command is:\n",
      "\n",
      "    f, ax = plt.subplots()  or  plt.subplots(1, 1)\n",
      "\n",
      "which is a convenience function that does:\n",
      "\n",
      "    f = plt.figure()\n",
      "    ax = f.add_subplot(1, 1, 1)   # (M, N, S) -> in an M x N grid, choose subplot nr S\n",
      "\n",
      "By passing arguments to `subplots`, you can easily create a regular plot grid:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "x = np.linspace(0, 2 * np.pi, 400)\n",
      "y = np.sin(x**2)\n",
      "\n",
      "# Just a figure and one subplot\n",
      "f, ax = plt.subplots()\n",
      "ax.plot(x, y)\n",
      "ax.set_title('Simple plot')\n",
      "\n",
      "# Two subplots, unpack the output array immediately\n",
      "f, (ax1, ax2) = plt.subplots(1, 2, sharey=True)\n",
      "ax1.plot(x, y)\n",
      "ax2.scatter(x, y)\n",
      "\n",
      "# Put a figure-level title\n",
      "f.suptitle('Sharing Y axis')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "And finally, an arbitrarily complex grid can be made with ``subplot2grid``:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "f = plt.figure()\n",
      "\n",
      "# subplot2grid(A, B) -> create a grid of shape A\n",
      "#                    -> return the axis at position B\n",
      "\n",
      "ax1 = plt.subplot2grid((3, 3), (0, 0), colspan=3)\n",
      "ax2 = plt.subplot2grid((3, 3), (1, 0), colspan=2)\n",
      "ax3 = plt.subplot2grid((3, 3), (1, 2), rowspan=2)\n",
      "ax4 = plt.subplot2grid((3, 3), (2, 0))\n",
      "ax5 = plt.subplot2grid((3, 3), (2, 1))\n",
      "\n",
      "# Turn off tick labels\n",
      "for ax in f.axes:\n",
      "    ax.set_xticks([])\n",
      "    ax.set_yticks([])\n",
      "    \n",
      "# Plot something in the bottom right box\n",
      "ax3.plot([1, 2, 3])"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Manipulating properties across matplotlib\n",
      "=========================================\n",
      "\n",
      "In matplotlib, most properties for lines, colors, etc, can be set directly in\n",
      "the plot call:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "plt.plot([1, 2, 3], linestyle='--', color='r')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "But for finer control you can get a hold of the returned line object (more on\n",
      "these objects later)::\n",
      "\n",
      "    In [1]: line, = plot([1,2,3])\n",
      "\n",
      "These line objects have a lot of properties you can control, a full list is\n",
      "seen here by tab-completing in IPython::\n",
      "\n",
      "    In [2]: line.set\n",
      "    line.set                     line.set_drawstyle           line.set_mec\n",
      "    line.set_aa                  line.set_figure              line.set_mew\n",
      "    line.set_agg_filter          line.set_fillstyle           line.set_mfc\n",
      "    line.set_alpha               line.set_gid                 line.set_mfcalt\n",
      "    line.set_animated            line.set_label               line.set_ms\n",
      "    line.set_antialiased         line.set_linestyle           line.set_picker\n",
      "    line.set_axes                line.set_linewidth           line.set_pickradius\n",
      "    line.set_c                   line.set_lod                 line.set_rasterized\n",
      "    line.set_clip_box            line.set_ls                  line.set_snap\n",
      "    line.set_clip_on             line.set_lw                  line.set_solid_capstyle\n",
      "    line.set_clip_path           line.set_marker              line.set_solid_joinstyle\n",
      "    line.set_color               line.set_markeredgecolor     line.set_transform\n",
      "    line.set_contains            line.set_markeredgewidth     line.set_url\n",
      "    line.set_dash_capstyle       line.set_markerfacecolor     line.set_visible\n",
      "    line.set_dashes              line.set_markerfacecoloralt  line.set_xdata\n",
      "    line.set_dash_joinstyle      line.set_markersize          line.set_ydata\n",
      "    line.set_data                line.set_markevery           line.set_zorder\n",
      "    \n",
      "\n",
      "Alternatively, the ``setp`` call (short for set property) can be used to list and set properties::\n",
      "\n",
      "    In [7]: line, = plot([1,2,3])\n",
      "\n",
      "    In [8]: plt.setp(line)\n",
      "      agg_filter: unknown\n",
      "      alpha: float (0.0 transparent through 1.0 opaque)         \n",
      "      animated: [True | False]         \n",
      "      antialiased or aa: [True | False]\n",
      "      ...\n",
      "      ... much more output elided\n",
      "      ...\n",
      "\n",
      "    In [9]: plt.setp(line, 'linestyle')\n",
      "      linestyle: [ ``'-'`` | ``'--'`` | ``'-.'`` | ``':'`` | ``'None'`` | ``' '`` | ``''`` ]         and any drawstyle in combination with a linestyle, e.g. ``'steps--'``.         \n",
      "\n",
      "The ``setp`` command can be used to list properties and their valid values,\n",
      "making it very easy to discover how to customize your figures to get the visual results\n",
      "you need.\n",
      "\n",
      "Furthermore, ``setp`` can manipulate multiple objects at a time:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "x = linspace(0, 2*pi)\n",
      "y1 = sin(x)\n",
      "y2 = sin(2*x)\n",
      "lines = plt.plot(x, y1, x, y2)\n",
      "\n",
      "# We will set the width and color of all lines in the figure at once:\n",
      "plt.setp(lines, linewidth=2, color='r');"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Understanding what matplotlib returns: lines, axes and figures\n",
      "==============================================================\n",
      "\n",
      "Lines\n",
      "-----\n",
      "\n",
      "In a simple plot:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "plt.plot([1,2,3])"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The return value of the plot call is a list of lines, which can be manipulated\n",
      "further.  If you capture the line object (in this case it's a single line so we\n",
      "use a one-element tuple):"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "line, = plt.plot([1,2,3])\n",
      "line.set_color('r')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "One line property that is particularly useful to be aware of is ``set_data``:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# Create a plot and hold the line object\n",
      "f, ax = plt.subplots()\n",
      "line, = ax.plot([1, 2, 3], label='my data')\n",
      "\n",
      "ax.grid()\n",
      "ax.set_title('My title')\n",
      "\n",
      "# ... later, we may want to modify the x/y data but keeping the rest of the\n",
      "# figure intact, with our new data (think, e.g., animation):\n",
      "x = np.linspace(0, 1)\n",
      "y = x**2\n",
      "\n",
      "# This can be done by operating on the data object itself\n",
      "line.set_data(x, y)\n",
      "\n",
      "# Now we must set the axis limits manually. Note that we can also use xlim\n",
      "# and ylim to set the x/y limits separately.\n",
      "ax.set_xlim(0, 1)\n",
      "ax.set_ylim(0, 1)\n",
      "\n",
      "## Note, alternatively this can be done with:\n",
      "#ax.relim()\n",
      "#ax.autoscale_view()\n",
      "\n",
      "## as well as requesting matplotlib to draw\n",
      "#plt.draw()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Anatomy of a common plot\n",
      "========================\n"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Axes are the main object that contains a lot of the user-facing functionality of matplotlib::\n",
      "\n",
      "    In [15]: f = plt.figure()\n",
      "\n",
      "    In [16]: ax = f.add_subplot(111)\n",
      "\n",
      "    In [17]: ax.\n",
      "    Display all 299 possibilities? (y or n)\n",
      "    ax.acorr                                 ax.hitlist\n",
      "    ax.add_artist                            ax.hlines\n",
      "    ax.add_callback                          ax.hold\n",
      "    ax.add_collection                        ax.ignore_existing_data_limits\n",
      "    ax.add_line                              ax.images\n",
      "    ax.add_patch                             ax.imshow\n",
      "    \n",
      "    ... etc.\n",
      "\n",
      "Many of the commands in ``plt.<command>`` are nothing but wrappers around axis\n",
      "calls, with machinery to automatically create a figure and add an axis to it if\n",
      "there wasn't one to begin with.  The output of most axis actions that draw\n",
      "something is a collection of lines (or other more complex geometric objects)."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Enclosing it all, the figure\n",
      "----------------------------\n",
      "\n",
      "The enclosing object is the ``figure``, that holds all axes::\n",
      "\n",
      "    In [17]: f = plt.figure()\n",
      "\n",
      "    In [18]: f.add_subplot(211)\n",
      "    Out[18]: <matplotlib.axes.AxesSubplot object at 0x9d0060c>\n",
      "\n",
      "    In [19]: f.axes\n",
      "    Out[19]: [<matplotlib.axes.AxesSubplot object at 0x9d0060c>]\n",
      "\n",
      "    In [20]: f.add_subplot(212)\n",
      "    Out[20]: <matplotlib.axes.AxesSubplot object at 0x9eacf0c>\n",
      "\n",
      "    In [21]: f.axes\n",
      "    Out[21]: \n",
      "    [<matplotlib.axes.AxesSubplot object at 0x9d0060c>,\n",
      "     <matplotlib.axes.AxesSubplot object at 0x9eacf0c>]\n",
      "\n",
      "The basic view of matplotlib is: a figure contains one or more axes, axes draw\n",
      "and return collections of one or more geometric objects (lines, patches, etc).\n",
      "\n",
      "For all the gory details on this topic, see the matplotlib [artist tutorial](http://matplotlib.sourceforge.net/users/artists.html)."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "## Summary example"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Let's make a simple plot that contains a few commonly used decorations:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "f, ax = plt.subplots()\n",
      "\n",
      "# Three simple polyniomials\n",
      "x = np.linspace(-1, 1)\n",
      "y1, y2, y3 = [x**i for i in [1,2,3]]\n",
      "\n",
      "# Plot each with a label (for a legend)\n",
      "ax.plot(x, y1, label='linear')\n",
      "ax.plot(x, y2, label='cuadratic')\n",
      "ax.plot(x, y3, label='cubic')\n",
      "# Make all lines drawn so far thicker\n",
      "plt.setp(ax.lines, linewidth=2)\n",
      "\n",
      "# Add a grid and a legend that doesn't overlap the lines\n",
      "ax.grid()\n",
      "ax.legend(loc='lower right')\n",
      "\n",
      "# Add black horizontal and vertical lines through the origin\n",
      "ax.axhline(0, color='black')\n",
      "ax.axvline(0, color='black')\n",
      "ax.set_frame_on(False)\n",
      "\n",
      "# Set main text elements of the plot\n",
      "ax.set_title('Some polynomials')\n",
      "ax.set_xlabel('x')\n",
      "ax.set_ylabel('p(x)')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Common plot types\n",
      "=================\n",
      "\n",
      "Error plots\n",
      "-----------\n",
      "\n",
      "First a very simple error plot"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# example data\n",
      "x = np.arange(0.1, 4, 0.5)\n",
      "y = np.exp(-x)\n",
      "\n",
      "# example variable error bar values\n",
      "yerr = 0.1 + 0.2 * np.sqrt(x)\n",
      "xerr = 0.1 + x / 15\n",
      "\n",
      "# First illustrate basic pyplot interface, using defaults where possible.\n",
      "plt.figure()\n",
      "plt.errorbar(x, y, xerr=xerr, yerr=yerr, fmt='o', ecolor='g')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Logarithmic plots\n",
      "-----------------"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "x = np.linspace(-5, 5)\n",
      "y = 2 ** x\n",
      "\n",
      "f, (ax1, ax2) = plt.subplots(2, 1)\n",
      "ax1.plot(x, y)\n",
      "ax2.semilogy(x, y)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Bar plots\n",
      "---------"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "N = 5\n",
      "men_means = (20, 35, 30, 31, 27)\n",
      "men_std = (2, 3, 4, 1, 2)\n",
      "women_means = (25, 32, 34, 21, 29)\n",
      "women_std = (3, 5, 2, 3, 3)\n",
      "\n",
      "ind = np.arange(N)  # the x locations for the groups\n",
      "width = 0.35        # the width of the bars\n",
      "\n",
      "fig, ax = plt.subplots()\n",
      "\n",
      "rects1 = ax.bar(ind, men_means, width, color='r', yerr=men_std)\n",
      "rects2 = ax.bar(ind + width, women_means, width, color='y', yerr=women_std)\n",
      "\n",
      "# add some\n",
      "ax.set_ylabel('Scores')\n",
      "ax.set_title('Scores by group and gender')\n",
      "ax.set_xticks(ind + width)\n",
      "ax.set_xticklabels(('G1', 'G2', 'G3', 'G4', 'G5'))\n",
      "\n",
      "ax.legend((rects1, rects2), ('Men', 'Women'))"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Scatter plots\n",
      "-------------\n",
      "\n",
      "The ``scatter`` command produces scatter plots with arbitrary markers."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from matplotlib import cm    # cm == colormap\n",
      "\n",
      "t = linspace(0.0, 6*pi, 100)\n",
      "y = exp(-0.1 * t) * cos(t)\n",
      "phase = t % (2 * pi)\n",
      "\n",
      "f, ax = plt.subplots()\n",
      "ax.scatter(t, y, s=100 * abs(y), c=phase, cmap=cm.jet)\n",
      "ax.set_ylim(-1, 1)\n",
      "\n",
      "ax.grid()\n",
      "ax.axhline(color='black')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<div class=\"exercise\">\n",
      "    \n",
      "Exercise\n",
      "--------\n",
      "\n",
      "Consider you have the following data in a text file (The file `data/stations.txt` contains the full dataset):\n",
      "\n",
      "    # Station  Lat    Long   Elev \n",
      "    BIRA    26.4840 87.2670 0.0120\n",
      "    BUNG    27.8771 85.8909 1.1910\n",
      "    GAIG    26.8380 86.6318 0.1660\n",
      "    HILE    27.0482 87.3242 2.0880\n",
      "    ... etc.\n",
      "    \n",
      "    \n",
      "These are the names of seismographic stations in the Himalaya, with their coordinates and elevations in Kilometers.\n",
      "\n",
      "1. Use ``np.loadtxt`` to load the data, providing a custom data-type in order to to handle the string column.\n",
      "    \n",
      "2. Make a scatter plot of all of these, using both the size and the color to (redundantly) encode elevation.  Label each station by its 4-letter code, and add a colorbar on the right that shows the color-elevation map.\n",
      "    \n",
      "3. If you have the <a href=\"http://matplotlib.org/basemap/\">basemap toolkit</a> installed, repeat the same exercise but draw a grid with parallels and meridians, add rivers in cyan and country boundaries in yellow.  Also, draw the background using the NASA BlueMarble image of Earth.\n",
      "\n",
      "    \n",
      "**Tips**\n",
      "    \n",
      "* The data-type for a string of length 4 is ``(str, 4)``.\n",
      "    \n",
      "* You can check whether you have Basemap installed with:\n",
      "    \n",
      "    from mpl_toolkits.basemap import Basemap\n",
      "    \n",
      "* For the basemap part, choose a text label color that provides adequate reading contrast over the image background.\n",
      "    \n",
      "* Create your Basemap with 'i' resolution, otherwise it will take forever to draw."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Histograms\n",
      "----------\n",
      "\n",
      "Matplotlib has a built-in command for histograms."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "mu, sigma = 100, 15\n",
      "x = mu + sigma * np.random.randn(10000)\n",
      "\n",
      "# the histogram of the data\n",
      "n, bins, patches = plt.hist(x, 50, normed=1, facecolor='g', alpha=0.25)\n",
      "\n",
      "plt.xlabel('Smarts')\n",
      "plt.ylabel('Probability')\n",
      "plt.title('Histogram of IQ')\n",
      "plt.text(60, .025, r'$\\mu=100,\\ \\sigma=15$')\n",
      "plt.axis([40, 160, 0, 0.03])\n",
      "plt.grid(True)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Aribitrary text and LaTeX support\n",
      "=================================\n",
      "\n",
      "In matplotlib, text can be added either relative to an individual axis object\n",
      "or to the whole figure.\n",
      "\n",
      "These commands add text to an Axis:\n",
      "\n",
      "- title() - add a title\n",
      "- xlabel() - add an axis label to the x-axis\n",
      "- ylabel() - add an axis label to the y-axis\n",
      "- text() - add text at an arbitrary location\n",
      "- annotate() - add an annotation, with optional arrow\n",
      "\n",
      "And these act on the whole figure:\n",
      "\n",
      "- figtext() - add text at an arbitrary location\n",
      "- suptitle() - add a title\n",
      "\n",
      "And any text field can contain LaTeX expressions for mathematics, as long as\n",
      "they are enclosed in ``$`` signs.\n",
      "\n",
      "This example illustrates all of them:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "fig = plt.figure()\n",
      "fig.suptitle('bold figure suptitle', fontsize=14, fontweight='bold')\n",
      "\n",
      "ax = fig.add_subplot(111)\n",
      "fig.subplots_adjust(top=0.85)\n",
      "ax.set_title('axes title')\n",
      "\n",
      "ax.set_xlabel('xlabel')\n",
      "ax.set_ylabel('ylabel')\n",
      "\n",
      "ax.text(3, 8, 'boxed italics text in data coords', style='italic',\n",
      "        bbox={'facecolor':'red', 'alpha':0.5, 'pad':10})\n",
      "\n",
      "ax.text(2, 6, r'an equation: $E=mc^2$', fontsize=15)\n",
      "\n",
      "ax.text(3, 2, unicode('unicode: Institut f\\374r Festk\\366rperphysik',\n",
      "                      'latin-1'))\n",
      "\n",
      "ax.text(0.95, 0.01, 'colored text in axes coords',\n",
      "        verticalalignment='bottom', horizontalalignment='right',\n",
      "        transform=ax.transAxes,\n",
      "        color='green', fontsize=15)\n",
      "\n",
      "\n",
      "ax.plot([2], [1], 'o')\n",
      "ax.annotate('annotate', xy=(2, 1), xytext=(3, 4),\n",
      "            arrowprops=dict(facecolor='black', width=0.8, headwidth=7, shrink=0.08))\n",
      "\n",
      "ax.axis([0, 10, 0, 10])"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Axis sharing\n",
      "============\n",
      "\n",
      "The simplest way to share axes is to use the ``subplots`` function.  More\n",
      "fine-grained control can be obtained by individually adding subplots and adding\n",
      "share calls to those, but in most cases the functionality from ``subplots`` is sufficient:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# Simple data to display in various forms\n",
      "x = np.linspace(0, 2 * np.pi, 400)\n",
      "y = np.sin(x**2)\n",
      "\n",
      "# Two subplots, the axes array is 1-d\n",
      "f, axarr = plt.subplots(2, sharex=True)\n",
      "f.suptitle('Sharing X axis')\n",
      "axarr[0].plot(x, y)\n",
      "axarr[1].scatter(x, y)\n",
      "\n",
      "# Two subplots, unpack the axes array immediately\n",
      "f, (ax1, ax2) = plt.subplots(1, 2, sharey=True)\n",
      "f.suptitle('Sharing Y axis')\n",
      "ax1.plot(x, y)\n",
      "ax2.scatter(x, y)\n",
      "\n",
      "# Three subplots sharing both x/y axes\n",
      "f, (ax1, ax2, ax3) = plt.subplots(3, sharex=True, sharey=True)\n",
      "f.suptitle('Sharing both axes')\n",
      "ax1.plot(x, y)\n",
      "ax2.scatter(x, y)\n",
      "ax3.scatter(x, 2*y**2-1,color='r')\n",
      "# Fine-tune figure; make subplots close to each other and hide x ticks for\n",
      "# all but bottom plot.\n",
      "f.subplots_adjust(hspace=0)\n",
      "plt.setp([a.get_xticklabels() for a in f.axes[:-1]], visible=False);"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Basic event handling\n",
      "====================\n",
      "\n",
      "Matplotlib has a builtin, toolkit-independent event model that is fairly rich.\n",
      "If you want to develop full-fledged applications with very complex and fast\n",
      "interactions, you are likely better off choosing a specific Graphical User\n",
      "Interface (GUI) toolkit and using its specific event model.  But for many\n",
      "scientific uses, what matplotlib offers is more than sufficient, and it has the\n",
      "advantage of working identically regardless of the GUI toolkit you choose to\n",
      "run matplotlib under.\n",
      "\n",
      "Here we will cover the bare essentials only, for full details you should\n",
      "consult the `event handling section`_ of the matplotlib user guide.\n",
      "\n",
      ".. _event handling section: http://matplotlib.sourceforge.net/users/event_handling.html\n",
      "\n",
      "The basic idea of *all* event handling is always the same: the windowing\n",
      "environment registers an event (mouse movement, click, keyboard press, etc)\n",
      "produced by the user.  In advance, you have registered *event handlers*:\n",
      "functions you define that are meant to be called when specific types of events\n",
      "occur.  The registration action is called *connecting* the event handler, and\n",
      "is performed by the ``mpl_connect`` method of the figure canvas attribute (the\n",
      "canvas is the drawing area of the figure object, the entire raw object where\n",
      "events take place).\n",
      "\n",
      "The windowing system will then pass the event (each event has some relevant\n",
      "information that goes with it, such as which key or button was pressed) to your\n",
      "function, which can act on it.  These functions are referred to as *callbacks*,\n",
      "because they are meant to be 'called back' not by you, but by the windowing\n",
      "toolkit when the right event goes by.\n",
      "\n",
      "Here is the simplest possible matplotlib event handler::"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "fig, ax = plt.subplots()\n",
      "ax.plot(np.random.rand(10))\n",
      "\n",
      "def onclick(event):\n",
      "    print 'button=%d, x=%d, y=%d, xdata=%f, ydata=%f'%(\n",
      "        event.button, event.x, event.y, event.xdata, event.ydata)\n",
      "\n",
      "cid = fig.canvas.mpl_connect('button_press_event', onclick)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The ``FigureCanvas`` method ``mpl_connect`` returns a connection id which\n",
      "is simply an integer.  When you want to disconnect the callback, just call::\n",
      "\n",
      "    fig.canvas.mpl_disconnect(cid)\n",
      "\n",
      "The most commonly used event types are ``KeyEvent`` and ``MouseEvent``, both of\n",
      "which have the following attributes:\n",
      "\n",
      "    ``x``\n",
      "        x position - pixels from left of canvas\n",
      "\n",
      "    ``y``\n",
      "        y position - pixels from bottom of canvas\n",
      "\n",
      "    ``inaxes``\n",
      "        the ``matplotlib.axes.Axes`` instance if mouse is over axes\n",
      "\n",
      "    ``xdata``\n",
      "        x coord of mouse in data coords\n",
      "\n",
      "    ``ydata``\n",
      "        y coord of mouse in data coords\n",
      "\n",
      "In addition, ``MouseEvent`` have:\n",
      "\n",
      "    ``button``\n",
      "        button pressed None, 1, 2, 3, 'up', 'down' (up and down are used for\n",
      "        scroll events)\n",
      "\n",
      "    ``key``\n",
      "        the key pressed: None, any character, 'shift', 'win', or 'control'"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<div class=\"exercise\">\n",
      "\n",
      "Exercise\n",
      "--------\n",
      "\n",
      "Extend the scatter plot exercise above with the seismic stations, to print the location (four-letter string) of the station you click on.  Use a threshold for distance, and discriminate between a click below threshold (considered to be 'on') vs a miss, in which case you should indicate what the closest station is, its coordinates and the distance to it from the click."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Image display\n",
      "=============\n",
      "\n",
      "The ``imshow`` command can display single or multi-channel images.  A simple\n",
      "array of random numbers, plotted in grayscale:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "z = np.random.random((10, 10))\n",
      "plt.imshow(z, cmap=plt.cm.gray, interpolation='nearest')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "img = plt.imread('data/stained_glass_barcelona.png')\n",
      "\n",
      "print \"Shape:\", img.shape\n",
      "print\n",
      "print img[:5, :5, 0]"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "plt.imshow(img)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "plt.imshow(img[..., 0], cmap=plt.cm.hot)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<div class=\"exercise\">\n",
      "    \n",
      "Exercise\n",
      "--------\n",
      "\n",
      "Write a notebook where you can load an image and then perform the following operations on it:\n",
      "    \n",
      "1. Create a figure with four plots that show both the full-color image and color channel of the image with the right colormap for that color.  Ensure that the axes are linked so zooming in one image zooms the same region in the others.\n",
      "    \n",
      "2. Compute a luminosity and per-channel histogram and display all four histograms in one figure, giving each a separate plot (hint: a 4x1 plot works best for this).  Link the appropriate axes together.\n",
      "    \n",
      "3. Create a black-and-white (or more precisely, grayscale) version of the image.  Compare the results from a naive average of all three channels with that of a model that uses 30% red, 59% green and 11% blue, by displaying all three (full color and both grayscales) side by side with linked axes for zooming.\n",
      "    \n",
      "Hint: look for the matplotlib image tutorial."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Simple 3d plotting with matplotlib\n",
      "==================================\n",
      "\n",
      "Note that you must execute at least once in your session::"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": true,
     "input": [
      "from mpl_toolkits.mplot3d import Axes3D"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "One this has been done, you can create 3d axes with the ``projection='3d'`` keyword to ``add_subplot``::\n",
      "\n",
      "    fig = plt.figure()\n",
      "    fig.add_subplot(<other arguments here>, projection='3d')\n",
      "\n",
      "or"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "f, ax = plt.subplots(subplot_kw={'projection': '3d'})"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "A simple surface plot:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from mpl_toolkits.mplot3d.axes3d import Axes3D\n",
      "from matplotlib import cm\n",
      "\n",
      "f, ax = plt.subplots(subplot_kw={'projection': '3d'})\n",
      "\n",
      "X = np.arange(-5, 5, 0.25)\n",
      "Y = np.arange(-5, 5, 0.25)\n",
      "X, Y = np.meshgrid(X, Y)\n",
      "\n",
      "R = np.sqrt(X**2 + Y**2)\n",
      "Z = np.sin(R)\n",
      "\n",
      "surf = ax.plot_surface(X, Y, Z, rstride=1, cstride=1, cmap=cm.jet,\n",
      "                       linewidth=0, antialiased=False)\n",
      "ax.set_zlim3d(-1.01, 1.01)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "And a parametric surface specified in cylindrical coordinates:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "fig, ax = plt.subplots(subplot_kw={'projection': '3d'})\n",
      "\n",
      "t = np.linspace(-4*np.pi, 4*np.pi, 100)\n",
      "\n",
      "r = t**2 + 40\n",
      "x = r * np.sin(t)\n",
      "y = r * np.cos(t)\n",
      "z = t\n",
      "\n",
      "ax.plot(x, y, z)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    }
   ],
   "metadata": {}
  }
 ]
}