docs/tutorial/getting_started.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting started with `mpl-probscale`\n",
    "\n",
    "## Installation\n",
    "\n",
    "`mpl-probscale` is developed on Python 3.6. It is also tested on Python 3.4, 3.5, and even 2.7 (for the time being).\n",
    "\n",
    "### From conda\n",
    "Official releases of `mpl-probscale` can be found on conda-forge:\n",
    "\n",
    "`conda install --channel=conda-forge mpl-probscale`\n",
    "\n",
    "Fairly recent builds of the development version are available on my channel:\n",
    "\n",
    "`conda install --channel=conda-forge mpl-probscale`\n",
    "\n",
    "\n",
    "### From PyPI\n",
    "\n",
    "Official source releases are also available on PyPI\n",
    "`pip install probscale`\n",
    "\n",
    "### From source\n",
    "\n",
    "`mpl-probscale` is a pure python package. It should be fairly trivial to install from source on any platform. To do that, download or clone from [github](https://github.com/matplotlib/mpl-probscale), unzip the archive if necessary then do:\n",
    "\n",
    "```\n",
    "cd mpl-probscale # or wherever the setup.py got placed\n",
    "pip install .\n",
    "```\n",
    "\n",
    "I recommend `pip install .` over `python setup.py install` for [reasons I don't fully understand](https://github.com/numpy/numpy/issues/6551#issuecomment-150392865cd)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import warnings\n",
    "warnings.simplefilter('ignore')\n",
    "\n",
    "import numpy\n",
    "from matplotlib import pyplot\n",
    "from scipy import stats\n",
    "import seaborn\n",
    "\n",
    "clear_bkgd = {'axes.facecolor':'none', 'figure.facecolor':'none'}\n",
    "seaborn.set(style='ticks', context='talk', color_codes=True, rc=clear_bkgd)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Background\n",
    "\n",
    "### Built-in matplotlib scales\n",
    "\n",
    "To the casual user, you can set matplotlib scales to either \"linear\" or \"log\" (logarithmic). There are others (e.g., logit, symlog), but I haven't seen them too much in the wild.\n",
    "\n",
    "Linear scales are the default:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, ax = pyplot.subplots()\n",
    "seaborn.despine(fig=fig)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Logarithmic scales can work well when your data cover several orders of magnitude and don't have to be in base 10."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, (ax1, ax2) = pyplot.subplots(nrows=2, figsize=(8,3))\n",
    "ax1.set_xscale('log')\n",
    "ax1.set_xlim(left=1e-3, right=1e3)\n",
    "ax1.set_xlabel(\"Base 10\")\n",
    "ax1.set_yticks([])\n",
    "\n",
    "ax2.set_xscale('log', basex=2)\n",
    "ax2.set_xlim(left=2**-3, right=2**3)\n",
    "ax2.set_xlabel(\"Base 2\")\n",
    "ax2.set_yticks([])\n",
    "\n",
    "seaborn.despine(fig=fig, left=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Probability Scales "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`mpl-probscale` lets you use probability scales. All you need to do is import it.\n",
    "\n",
    "Before importing, there is no probability scale available in matplotlib:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "try:\n",
    "    fig, ax = pyplot.subplots()\n",
    "    ax.set_xscale('prob')\n",
    "except ValueError as e:\n",
    "    pyplot.close(fig)\n",
    "    print(e)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To access probability scales, simply import the `probscale` module."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "import probscale\n",
    "fig, ax = pyplot.subplots(figsize=(8, 3))\n",
    "ax.set_xscale('prob')\n",
    "ax.set_xlim(left=0.5, right=99.5)\n",
    "ax.set_xlabel('Normal probability scale (%)')\n",
    "seaborn.despine(fig=fig)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Probability scales default to the standard normal distribution (note that the formatting is a percentage-based probability)\n",
    "\n",
    "You can even use different probability distributions, though it can be tricky. You have to pass a frozen distribution from either [scipy.stats](http://docs.scipy.org/doc/scipy/reference/stats.html#continuous-distributions) or [paramnormal](http://phobson.github.io/paramnormal/) to the `dist` kwarg in `ax.set_[x|y]scale`.\n",
    "\n",
    "Here's a standard normal scale with two different beta scales and a linear scale for comparison."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, (ax1, ax2, ax3, ax4) = pyplot.subplots(figsize=(9, 5), nrows=4)\n",
    "\n",
    "for ax in [ax1, ax2, ax3, ax4]:\n",
    "    ax.set_xlim(left=2, right=98)\n",
    "    ax.set_yticks([])\n",
    "\n",
    "ax1.set_xscale('prob')\n",
    "ax1.set_xlabel('Normal probability scale, as percents')\n",
    "\n",
    "beta1 = stats.beta(a=3, b=2)\n",
    "ax2.set_xscale('prob', dist=beta1)\n",
    "ax2.set_xlabel('Beta probability scale (α=3, β=2)')\n",
    "\n",
    "beta2 = stats.beta(a=2, b=7)\n",
    "ax3.set_xscale('prob', dist=beta2)\n",
    "ax3.set_xlabel('Beta probability scale (α=2, β=7)')\n",
    "\n",
    "ax4.set_xticks(ax1.get_xticks()[12:-12])\n",
    "ax4.set_xlabel('Linear scale (for reference)')\n",
    "\n",
    "seaborn.despine(fig=fig, left=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Ready-made probability plots\n",
    "`mpl-probscale` ships with a small `viz` module that can help you make a probability plot of a sample.\n",
    "\n",
    "With only the sample data, `probscale.probplot` will create a figure, compute the plotting position and non-exceedance probabilities, and plot everything:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "numpy.random.seed(0)\n",
    "sample = numpy.random.normal(loc=4, scale=2, size=37)\n",
    "\n",
    "fig = probscale.probplot(sample)\n",
    "seaborn.despine(fig=fig)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You should specify the matplotlib axes on which the plot should occur if you want to customize the plot using matplotlib commands directly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, ax = pyplot.subplots(figsize=(7, 3))\n",
    "\n",
    "probscale.probplot(sample, ax=ax)\n",
    "\n",
    "ax.set_ylabel('Normal Values')\n",
    "ax.set_xlabel('Non-exceedance probability')\n",
    "ax.set_xlim(left=1, right=99)\n",
    "seaborn.despine(fig=fig)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Lots of other options are directly accessible from the `probplot` function signature."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, ax = pyplot.subplots(figsize=(3, 7))\n",
    "\n",
    "numpy.random.seed(0)\n",
    "new_sample = numpy.random.lognormal(mean=2.0, sigma=0.75, size=37)\n",
    "\n",
    "probscale.probplot(\n",
    "    new_sample,\n",
    "    ax=ax,\n",
    "    probax='y', # flip the plot\n",
    "    datascale='log', # scale of the non-probability axis\n",
    "    bestfit=True, # draw a best-fit line\n",
    "    estimate_ci=True,\n",
    "    datalabel='Lognormal Values',  # labels and markers...\n",
    "    problabel='Non-exceedance probability',\n",
    "    scatter_kws=dict(marker='d', zorder=2, mew=1.25, mec='w', markersize=10),\n",
    "    line_kws=dict(color='0.17', linewidth=2.5, zorder=0, alpha=0.75),\n",
    ")\n",
    "\n",
    "ax.set_ylim(bottom=1, top=99)\n",
    "seaborn.despine(fig=fig)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Percentile and Quantile plots\n",
    "For convenience, you can do percentile and quantile plots with the same function."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    ".. note::\n",
    "   The percentile and probability axes are plotted against the\n",
    "   same values. The difference is only that \"percentiles\" \n",
    "   are plotted on a linear scale."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "fig, (ax1, ax2, ax3) = pyplot.subplots(nrows=3, figsize=(8, 7))\n",
    "\n",
    "probscale.probplot(sample, ax=ax1, plottype='pp', problabel='Percentiles')\n",
    "probscale.probplot(sample, ax=ax2, plottype='qq', problabel='Quantiles')\n",
    "probscale.probplot(sample, ax=ax3, plottype='prob', problabel='Probabilities')\n",
    "\n",
    "ax2.set_xlim(left=-2.5, right=2.5)\n",
    "ax3.set_xlim(left=0.5, right=99.5)\n",
    "fig.tight_layout()\n",
    "seaborn.despine(fig=fig)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Working with seaborn `FacetGrids`\n",
    "\n",
    "Good news, everyone. The ``probplot`` function generally works as expected with [FacetGrids](http://stanford.edu/~mwaskom/software/seaborn/tutorial/axis_grids.html#subsetting-data-with-facetgrid)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "plot = (\n",
    "    seaborn.load_dataset(\"tips\")\n",
    "        .assign(pct=lambda df: 100 * df['tip'] / df['total_bill'])\n",
    "        .pipe(seaborn.FacetGrid, hue='sex', col='time', row='smoker', margin_titles=True, aspect=1., size=4)\n",
    "        .map(probscale.probplot, 'pct', bestfit=True, scatter_kws=dict(alpha=0.75), probax='y')\n",
    "        .add_legend()\n",
    "        .set_ylabels('Non-Exceedance Probability')\n",
    "        .set_xlabels('Tips as percent of total bill')\n",
    "        .set(ylim=(0.5, 99.5), xlim=(0, 100))\n",
    ")"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "kernelspec": {
   "display_name": "Python [default]",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.5.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}