notebooks/04.00-Introduction-To-Matplotlib.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!--NAVIGATION-->\n",
    "< [Further Resources](03.13-Further-Resources.ipynb) | [Contents](Index.ipynb) | [Simple Line Plots](04.01-Simple-Line-Plots.ipynb) >\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Visualization with Matplotlib"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We'll now take an in-depth look at the Matplotlib package for visualization in Python.\n",
    "Matplotlib is a multi-platform data visualization library built on NumPy arrays, and designed to work with the broader SciPy stack.\n",
    "It was conceived by John Hunter in 2002, originally as a patch to IPython for enabling interactive MATLAB-style plotting via gnuplot from the IPython command line.\n",
    "IPython's creator, Fernando Perez, was at the time scrambling to finish his PhD, and let John know he wouldn’t have time to review the patch for several months.\n",
    "John took this as a cue to set out on his own, and the Matplotlib package was born, with version 0.1 released in 2003.\n",
    "It received an early boost when it was adopted as the plotting package of choice of the Space Telescope Science Institute (the folks behind the Hubble Telescope), which financially supported Matplotlib’s development and greatly expanded its capabilities.\n",
    "\n",
    "One of Matplotlib’s most important features is its ability to play well with many operating systems and graphics backends.\n",
    "Matplotlib supports dozens of backends and output types, which means you can count on it to work regardless of which operating system you are using or which output format you wish.\n",
    "This cross-platform, everything-to-everyone approach has been one of the great strengths of Matplotlib.\n",
    "It has led to a large user base, which in turn has led to an active developer base and Matplotlib’s powerful tools and ubiquity within the scientific Python world.\n",
    "\n",
    "In recent years, however, the interface and style of Matplotlib have begun to show their age.\n",
    "Newer tools like ggplot and ggvis in the R language, along with web visualization toolkits based on D3js and HTML5 canvas, often make Matplotlib feel clunky and old-fashioned.\n",
    "Still, I'm of the opinion that we cannot ignore Matplotlib's strength as a well-tested, cross-platform graphics engine.\n",
    "Recent Matplotlib versions make it relatively easy to set new global plotting styles (see [Customizing Matplotlib: Configurations and Style Sheets](04.11-Settings-and-Stylesheets.ipynb)), and people have been developing new packages that build on its powerful internals to drive Matplotlib via cleaner, more modern APIs—for example, Seaborn (discussed in [Visualization With Seaborn](04.14-Visualization-With-Seaborn.ipynb)), [ggpy](http://yhat.github.io/ggpy/), [HoloViews](http://holoviews.org/), [Altair](http://altair-viz.github.io/), and even Pandas itself can be used as wrappers around Matplotlib's API.\n",
    "Even with wrappers like these, it is still often useful to dive into Matplotlib's syntax to adjust the final plot output.\n",
    "For this reason, I believe that Matplotlib itself will remain a vital piece of the data visualization stack, even if new tools mean the community gradually moves away from using the Matplotlib API directly."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## General Matplotlib Tips\n",
    "\n",
    "Before we dive into the details of creating visualizations with Matplotlib, there are a few useful things you should know about using the package."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Importing Matplotlib\n",
    "\n",
    "Just as we use the ``np`` shorthand for NumPy and the ``pd`` shorthand for Pandas, we will use some standard shorthands for Matplotlib imports:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib as mpl\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``plt`` interface is what we will use most often, as we shall see throughout this chapter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Setting Styles\n",
    "\n",
    "We will use the ``plt.style`` directive to choose appropriate aesthetic styles for our figures.\n",
    "Here we will set the ``classic`` style, which ensures that the plots we create use the classic Matplotlib style:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "plt.style.use('classic')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Throughout this section, we will adjust this style as needed.\n",
    "Note that the stylesheets used here are supported as of Matplotlib version 1.5; if you are using an earlier version of Matplotlib, only the default style is available.\n",
    "For more information on stylesheets, see [Customizing Matplotlib: Configurations and Style Sheets](04.11-Settings-and-Stylesheets.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### ``show()`` or No ``show()``? How to Display Your Plots"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A visualization you can't see won't be of much use, but just how you view your Matplotlib plots depends on the context.\n",
    "The best use of Matplotlib differs depending on how you are using it; roughly, the three applicable contexts are using Matplotlib in a script, in an IPython terminal, or in an IPython notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Plotting from a script\n",
    "\n",
    "If you are using Matplotlib from within a script, the function ``plt.show()`` is your friend.\n",
    "``plt.show()`` starts an event loop, looks for all currently active figure objects, and opens one or more interactive windows that display your figure or figures.\n",
    "\n",
    "So, for example, you may have a file called *myplot.py* containing the following:\n",
    "\n",
    "```python\n",
    "# ------- file: myplot.py ------\n",
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "\n",
    "x = np.linspace(0, 10, 100)\n",
    "\n",
    "plt.plot(x, np.sin(x))\n",
    "plt.plot(x, np.cos(x))\n",
    "\n",
    "plt.show()\n",
    "```\n",
    "\n",
    "You can then run this script from the command-line prompt, which will result in a window opening with your figure displayed:\n",
    "\n",
    "```\n",
    "$ python myplot.py\n",
    "```\n",
    "\n",
    "The ``plt.show()`` command does a lot under the hood, as it must interact with your system's interactive graphical backend.\n",
    "The details of this operation can vary greatly from system to system and even installation to installation, but matplotlib does its best to hide all these details from you.\n",
    "\n",
    "One thing to be aware of: the ``plt.show()`` command should be used *only once* per Python session, and is most often seen at the very end of the script.\n",
    "Multiple ``show()`` commands can lead to unpredictable backend-dependent behavior, and should mostly be avoided."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Plotting from an IPython shell\n",
    "\n",
    "It can be very convenient to use Matplotlib interactively within an IPython shell (see [IPython: Beyond Normal Python](01.00-IPython-Beyond-Normal-Python.ipynb)).\n",
    "IPython is built to work well with Matplotlib if you specify Matplotlib mode.\n",
    "To enable this mode, you can use the ``%matplotlib`` magic command after starting ``ipython``:\n",
    "\n",
    "```ipython\n",
    "In [1]: %matplotlib\n",
    "Using matplotlib backend: TkAgg\n",
    "\n",
    "In [2]: import matplotlib.pyplot as plt\n",
    "```\n",
    "\n",
    "At this point, any ``plt`` plot command will cause a figure window to open, and further commands can be run to update the plot.\n",
    "Some changes (such as modifying properties of lines that are already drawn) will not draw automatically: to force an update, use ``plt.draw()``.\n",
    "Using ``plt.show()`` in Matplotlib mode is not required."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Plotting from an IPython notebook\n",
    "\n",
    "The IPython notebook is a browser-based interactive data analysis tool that can combine narrative, code, graphics, HTML elements, and much more into a single executable document (see [IPython: Beyond Normal Python](01.00-IPython-Beyond-Normal-Python.ipynb)).\n",
    "\n",
    "Plotting interactively within an IPython notebook can be done with the ``%matplotlib`` command, and works in a similar way to the IPython shell.\n",
    "In the IPython notebook, you also have the option of embedding graphics directly in the notebook, with two possible options:\n",
    "\n",
    "- ``%matplotlib notebook`` will lead to *interactive* plots embedded within the notebook\n",
    "- ``%matplotlib inline`` will lead to *static* images of your plot embedded in the notebook\n",
    "\n",
    "For this book, we will generally opt for ``%matplotlib inline``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After running this command (it needs to be done only once per kernel/session), any cell within the notebook that creates a plot will embed a PNG image of the resulting graphic:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "x = np.linspace(0, 10, 100)\n",
    "\n",
    "fig = plt.figure()\n",
    "plt.plot(x, np.sin(x), '-')\n",
    "plt.plot(x, np.cos(x), '--');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Saving Figures to File\n",
    "\n",
    "One nice feature of Matplotlib is the ability to save figures in a wide variety of formats.\n",
    "Saving a figure can be done using the ``savefig()`` command.\n",
    "For example, to save the previous figure as a PNG file, you can run this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig.savefig('my_figure.png')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now have a file called ``my_figure.png`` in the current working directory:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!ls -lh my_figure.png"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To confirm that it contains what we think it contains, let's use the IPython ``Image`` object to display the contents of this file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import Image\n",
    "Image('my_figure.png')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In ``savefig()``, the file format is inferred from the extension of the given filename.\n",
    "Depending on what backends you have installed, many different file formats are available.\n",
    "The list of supported file types can be found for your system by using the following method of the figure canvas object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig.canvas.get_supported_filetypes()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that when saving your figure, it's not necessary to use ``plt.show()`` or related commands discussed earlier."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Two Interfaces for the Price of One\n",
    "\n",
    "A potentially confusing feature of Matplotlib is its dual interfaces: a convenient MATLAB-style state-based interface, and a more powerful object-oriented interface. We'll quickly highlight the differences between the two here."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### MATLAB-style Interface\n",
    "\n",
    "Matplotlib was originally written as a Python alternative for MATLAB users, and much of its syntax reflects that fact.\n",
    "The MATLAB-style tools are contained in the pyplot (``plt``) interface.\n",
    "For example, the following code will probably look quite familiar to MATLAB users:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.figure()  # create a plot figure\n",
    "\n",
    "# create the first of two panels and set current axis\n",
    "plt.subplot(2, 1, 1) # (rows, columns, panel number)\n",
    "plt.plot(x, np.sin(x))\n",
    "\n",
    "# create the second panel and set current axis\n",
    "plt.subplot(2, 1, 2)\n",
    "plt.plot(x, np.cos(x));"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is important to note that this interface is *stateful*: it keeps track of the \"current\" figure and axes, which are where all ``plt`` commands are applied.\n",
    "You can get a reference to these using the ``plt.gcf()`` (get current figure) and ``plt.gca()`` (get current axes) routines.\n",
    "\n",
    "While this stateful interface is fast and convenient for simple plots, it is easy to run into problems.\n",
    "For example, once the second panel is created, how can we go back and add something to the first?\n",
    "This is possible within the MATLAB-style interface, but a bit clunky.\n",
    "Fortunately, there is a better way."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Object-oriented interface\n",
    "\n",
    "The object-oriented interface is available for these more complicated situations, and for when you want more control over your figure.\n",
    "Rather than depending on some notion of an \"active\" figure or axes, in the object-oriented interface the plotting functions are *methods* of explicit ``Figure`` and ``Axes`` objects.\n",
    "To re-create the previous plot using this style of plotting, you might do the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# First create a grid of plots\n",
    "# ax will be an array of two Axes objects\n",
    "fig, ax = plt.subplots(2)\n",
    "\n",
    "# Call plot() method on the appropriate object\n",
    "ax[0].plot(x, np.sin(x))\n",
    "ax[1].plot(x, np.cos(x));"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For more simple plots, the choice of which style to use is largely a matter of preference, but the object-oriented approach can become a necessity as plots become more complicated.\n",
    "Throughout this chapter, we will switch between the MATLAB-style and object-oriented interfaces, depending on what is most convenient.\n",
    "In most cases, the difference is as small as switching ``plt.plot()`` to ``ax.plot()``, but there are a few gotchas that we will highlight as they come up in the following sections."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!--NAVIGATION-->\n",
    "< [Further Resources](03.13-Further-Resources.ipynb) | [Contents](Index.ipynb) | [Simple Line Plots](04.01-Simple-Line-Plots.ipynb) >\n",
    "\n"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "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.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}