document new api and restore seaborn compat

Author: phobson

docs/api.rst

@@ -6,3 +6,6 @@ API and Source Reference
 
    api/viz.rst
    api/probscale.rst
+   api/formatters.rst
+   api/transforms.rst
+   api/validate.rst

docs/tutorial/closer_look_at_plot_pos.ipynb

@@ -69,10 +69,13 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "collapsed": true
+    "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",

docs/tutorial/closer_look_at_viz.ipynb

@@ -50,6 +50,7 @@
     "clear_bkgd = {'axes.facecolor':'none', 'figure.facecolor':'none'}\n",
     "seaborn.set(style='ticks', context='talk', color_codes=True, rc=clear_bkgd)\n",
     "\n",
+    "# load up some example data from the seaborn package\n",
     "tips = seaborn.load_dataset(\"tips\")\n",
     "iris = seaborn.load_dataset(\"iris\")"
    ]
@@ -109,11 +110,9 @@
    "outputs": [],
    "source": [
     "fig, ax = pyplot.subplots(figsize=(6, 3))\n",
-    "fig = probscale.probplot(tips['total_bill'], ax=ax, plottype='pp',\n",
-    "                         datascale='log', label='Bill Amount', \n",
-    "                         xlabel='Percentile', ylabel='Total Bill (USD)',\n",
-    "                         scatter_kws=dict(marker='.', linestyle='none'))\n",
-    "ax.legend(loc='upper left')\n",
+    "fig = probscale.probplot(tips['total_bill'], ax=ax, plottype='pp', datascale='log',\n",
+    "                         problabel='Percentile', datalabel='Total Bill (USD)',\n",
+    "                         scatter_kws=dict(marker='.', linestyle='none', label='Bill Amount'))\n",
     "seaborn.despine()"
    ]
   },
@@ -128,7 +127,7 @@
     "The default distribution is the standard-normal distribution.\n",
     "Using a different distribution is covered further down.\n",
     "\n",
-    "Usings the same dataset as a above let's make a quantile plot, again from scratch and then using `probplot`."
+    "Usings the same dataset as a above let's make a quantile plot. Like above, we'll do it from scratch and then using `probplot`."
    ]
   },
   {
@@ -169,10 +168,9 @@
    "outputs": [],
    "source": [
     "fig, ax = pyplot.subplots(figsize=(6, 3))\n",
-    "fig = probscale.probplot(tips['total_bill'], ax=ax, plottype='qq',\n",
-    "                         datascale='log', label='Bill Amount', \n",
-    "                         xlabel='Normal Quantiles', ylabel='Total Bill (USD)',\n",
-    "                         scatter_kws=dict(marker='.', linestyle='none'))\n",
+    "fig = probscale.probplot(tips['total_bill'], ax=ax, plottype='qq', datascale='log', \n",
+    "                         problabel='Normal Quantiles', datalabel='Total Bill (USD)',\n",
+    "                         scatter_kws=dict(marker='.', linestyle='none', label='Bill Amount'))\n",
     "ax.legend(loc='upper left')\n",
     "seaborn.despine()"
    ]
@@ -198,16 +196,13 @@
     "fig, (ax1, ax2) = pyplot.subplots(figsize=(6, 6), ncols=2, sharex=True)\n",
     "\n",
     "fig = probscale.probplot(tips['total_bill'], ax=ax1, plottype='pp', probax='y',\n",
-    "                         datascale='log', label='Bill Amount', \n",
-    "                         ylabel='Percentile', xlabel='Total Bill (USD)',\n",
-    "                         scatter_kws=dict(marker='.', linestyle='none'))\n",
-    "ax.legend()\n",
+    "                         datascale='log', problabel='Percentile', datalabel='Total Bill (USD)',\n",
+    "                         scatter_kws=dict(marker='.', linestyle='none', label='Bill Amount'))\n",
     "\n",
     "fig = probscale.probplot(tips['total_bill'], ax=ax2, plottype='qq', probax='y',\n",
-    "                         datascale='log', label='Bill Amount', \n",
-    "                         ylabel='Normal Quantiles', xlabel='Total Bill (USD)',\n",
-    "                         scatter_kws=dict(marker='.', linestyle='none'))\n",
-    "ax.legend()\n",
+    "                         datascale='log', problabel='Normal Quantiles',datalabel='Total Bill (USD)',\n",
+    "                         scatter_kws=dict(marker='.', linestyle='none', label='Bill Amount'))\n",
+    "ax.legend(loc='upper left')\n",
     "fig.tight_layout()\n",
     "seaborn.despine()"
    ]
@@ -240,24 +235,23 @@
     "common_opts = dict(\n",
     "    probax='y', \n",
     "    datascale='log', \n",
-    "    label='Bill Amount', \n",
-    "    xlabel='Total Bill (USD)',\n",
+    "    datalabel='Total Bill (USD)',\n",
     "    scatter_kws=dict(marker='.', linestyle='none')\n",
     ")\n",
     "\n",
     "fig = probscale.probplot(tips['total_bill'], ax=ax1, \n",
     "                         plottype='pp',\n",
-    "                         ylabel='percentile', \n",
+    "                         problabel='percentile', \n",
     "                         **common_opts)\n",
     "\n",
     "fig = probscale.probplot(tips['total_bill'], ax=ax2, \n",
     "                         plottype='qq',\n",
-    "                         ylabel='Normal Quantiles', \n",
+    "                         problabel='Normal Quantiles', \n",
     "                         **common_opts)\n",
     "\n",
     "fig = probscale.probplot(tips['total_bill'], ax=ax3, \n",
     "                         plottype='prob',\n",
-    "                         ylabel='Normal Probabilities', \n",
+    "                         problabel='Normal Probabilities', \n",
     "                         **common_opts)\n",
     "ax3.set_ylim(bottom=0.13, top=99.87)\n",
     "fig.tight_layout()\n",
@@ -290,8 +284,7 @@
     "    plottype='prob',\n",
     "    probax='y',\n",
     "    datascale='log',\n",
-    "    label='Bill Amount',\n",
-    "    xlabel='Total Bill (USD)',\n",
+    "    datalabel='Total Bill (USD)',\n",
     "    scatter_kws=dict(marker='+', linestyle='none', mew=1)\n",
     ")\n",
     "\n",
@@ -300,13 +293,13 @@
     "\n",
     "fig, (ax1, ax2, ax3) = pyplot.subplots(figsize=(9, 6), ncols=3, sharey=True)\n",
     "fig = probscale.probplot(tips['total_bill'], ax=ax1, dist=alpha, \n",
-    "                         ylabel='Alpha Probabilities', **common_opts)\n",
+    "                         problabel='Alpha Probabilities', **common_opts)\n",
     "\n",
     "fig = probscale.probplot(tips['total_bill'], ax=ax2, dist=beta, \n",
-    "                         ylabel='Beta Probabilities', **common_opts)\n",
+    "                         problabel='Beta Probabilities', **common_opts)\n",
     "\n",
     "fig = probscale.probplot(tips['total_bill'], ax=ax3, dist=None,\n",
-    "                         ylabel='Normal Probabilities', **common_opts)\n",
+    "                         problabel='Normal Probabilities', **common_opts)\n",
     "\n",
     "ax3.set_ylim(bottom=0.2, top=99.8)\n",
     "seaborn.despine()\n",
@@ -332,8 +325,7 @@
     "    plottype='qq',\n",
     "    probax='y',\n",
     "    datascale='log',\n",
-    "    label='Bill Amount',\n",
-    "    xlabel='Total Bill (USD)',\n",
+    "    datalabel='Total Bill (USD)',\n",
     "    scatter_kws=dict(marker='+', linestyle='none', mew=1)\n",
     ")\n",
     "\n",
@@ -342,13 +334,13 @@
     "\n",
     "fig, (ax1, ax2, ax3) = pyplot.subplots(figsize=(9, 6), ncols=3)\n",
     "fig = probscale.probplot(tips['total_bill'], ax=ax1, dist=alpha, \n",
-    "                         ylabel='Alpha Quantiles', **common_opts)\n",
+    "                         problabel='Alpha Quantiles', **common_opts)\n",
     "\n",
     "fig = probscale.probplot(tips['total_bill'], ax=ax2, dist=beta, \n",
-    "                         ylabel='Beta Quantiles', **common_opts)\n",
+    "                         problabel='Beta Quantiles', **common_opts)\n",
     "\n",
     "fig = probscale.probplot(tips['total_bill'], ax=ax3, dist=None,\n",
-    "                         ylabel='Normal Quantiles', **common_opts)\n",
+    "                         problabel='Normal Quantiles', **common_opts)\n",
     "\n",
     "ax.legend(loc='upper left')\n",
     "ax.set_ylim(bottom=0.1, top=99.9)\n",
@@ -389,16 +381,16 @@
     "\n",
     "common_opts = dict(\n",
     "    plottype='qq',\n",
-    "    probax='y',\n",
-    "    ylabel='Theoretical Quantiles',\n",
-    "    xlabel='Emperical Quantiles',\n",
-    "    label='Bill amounts'\n",
+    "    probax='x',\n",
+    "    problabel='Theoretical Quantiles',\n",
+    "    datalabel='Emperical Quantiles',\n",
+    "    scatter_kws=dict(label='Bill amounts')\n",
     ")\n",
     "\n",
     "fig = probscale.probplot(tips['total_bill'], ax=ax, dist=norm, **common_opts)\n",
     "\n",
     "equality_line(ax, label='Guessed Normal Distribution')\n",
-    "ax.legend(loc='upper left')\n",
+    "ax.legend(loc='lower right')\n",
     "seaborn.despine()"
    ]
   },
@@ -427,6 +419,7 @@
     "fig = probscale.probplot(tips['total_bill'], ax=ax, dist=lognorm, **common_opts)\n",
     "\n",
     "equality_line(ax, label='Fit Lognormal Distribution')\n",
+    "ax.legend(loc='lower right')\n",
     "seaborn.despine()"
    ]
   },
@@ -466,9 +459,9 @@
    "source": [
     "fig, ax = pyplot.subplots(figsize=(6, 3))\n",
     "fig = probscale.probplot(tips['total_bill'], ax=ax, plottype='pp', bestfit=True,\n",
-    "                         label='Bill Amount', xlabel='Percentile', ylabel='Total Bill (USD)',\n",
-    "                         scatter_kws=dict(marker='.', linestyle='none', alpha=0.5),\n",
-    "                         line_kws=dict(label='Best-fit line', linestyle='--', linewidth=2.5))\n",
+    "                         problabel='Percentile', datalabel='Total Bill (USD)',\n",
+    "                         scatter_kws=dict(label='Bill Amount'),\n",
+    "                         line_kws=dict(label='Best-fit line'))\n",
     "ax.legend(loc='upper left')\n",
     "seaborn.despine()"
    ]
@@ -493,16 +486,79 @@
    "outputs": [],
    "source": [
     "fig, ax = pyplot.subplots(figsize=(4, 6))\n",
-    "fig = probscale.probplot(tips['total_bill'], ax=ax, plottype='prob', bestfit=True, \n",
-    "                         probax='y', datascale='log',label='Bill Amount',\n",
-    "                         ylabel='Probabilities', xlabel='Total Bill (USD)',\n",
-    "                         scatter_kws=dict(marker='+', linestyle='none', alpha=0.75, mew=1),\n",
-    "                         line_kws=dict(label='Best-fit line', linewidth=2.5, zorder=0))\n",
+    "fig = probscale.probplot(tips['total_bill'], ax=ax, plottype='prob', probax='y', bestfit=True, \n",
+    "                         datascale='log', problabel='Probabilities', datalabel='Total Bill (USD)',\n",
+    "                         scatter_kws=dict(label='Bill Amount'),\n",
+    "                         line_kws=dict(label='Best-fit line'))\n",
     "ax.legend(loc='upper left')\n",
     "ax.set_ylim(bottom=0.1, top=99.9)\n",
     "seaborn.despine()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Controlling the aesthetics of the plot elements\n",
+    "\n",
+    "As it has been hinted in the examples above, the `probplot` function takes two dictionaries to customize the data series and the best-fit line (`scatter_kws` and `line_kws`, respectively.\n",
+    "These dictionaries are passed directly to the `plot` method of current axes.\n",
+    "\n",
+    "By default, the data series assumes that `linestyle='none'` and `marker='o'`.\n",
+    "These can be overwritten through `scatter_kws`\n",
+    "\n",
+    "Revisting the previous example, we can customize it like so:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "scatter_options = dict(\n",
+    "    marker='^',\n",
+    "    markerfacecolor='none',\n",
+    "    markeredgecolor='firebrick',\n",
+    "    markeredgewidth=1.25,\n",
+    "    linestyle='none',\n",
+    "    alpha=0.35,\n",
+    "    zorder=5,\n",
+    "    label='Meal Cost ($)'\n",
+    ")\n",
+    "\n",
+    "line_options = dict(\n",
+    "    dashes=(10,2,5,2,10,2),\n",
+    "    color='0.25',\n",
+    "    linewidth=3,\n",
+    "    zorder=10,\n",
+    "    label='Best-fit line'\n",
+    ") \n",
+    "\n",
+    "fig, ax = pyplot.subplots(figsize=(4, 6))\n",
+    "fig = probscale.probplot(tips['total_bill'], ax=ax, plottype='prob', probax='y', bestfit=True, \n",
+    "                         datascale='log', problabel='Probabilities', datalabel='Total Bill (USD)',\n",
+    "                         scatter_kws=scatter_options, line_kws=line_options)\n",
+    "ax.legend(loc='upper left')\n",
+    "ax.set_ylim(bottom=0.1, top=99.9)\n",
+    "seaborn.despine()"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "metadata": {},
+   "source": [
+    ".. note::\n",
+    "   The ``probplot`` function can take two additional aesthetic parameters:\n",
+    "   `color` and `label`. If provided `color` will override the marker face color\n",
+    "   and line color options of the `scatter_kws` and `line_kws` parameters, respectively.\n",
+    "   Similarly, the label of the scatter series will be overridden by the explicit parameter.\n",
+    "   It is not recommended that `color` and `label` are used. They exist primarily for \n",
+    "   compatibility with the seaborn package."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -563,21 +619,20 @@
     "common_opts = dict(\n",
     "    plottype='prob',\n",
     "    probax='x',\n",
-    "    label='Bill Amount',\n",
-    "    ylabel='Data',\n",
+    "    datalabel='Data',\n",
     ")\n",
     "\n",
     "numpy.random.seed(0)\n",
     "x = numpy.random.normal(size=15)\n",
     "\n",
     "fig, (ax1, ax2, ax3) = pyplot.subplots(figsize=(6, 6), nrows=3, sharex=True)\n",
-    "fig = probscale.probplot(x, ax=ax1, xlabel='Cunnuane (default) plotting positions',\n",
+    "fig = probscale.probplot(x, ax=ax1, problabel='Cunnuane (default) plotting positions',\n",
     "                         **common_opts)\n",
     "\n",
-    "fig = probscale.probplot(x, ax=ax2, xlabel='Weibull plotting positions',\n",
+    "fig = probscale.probplot(x, ax=ax2, problabel='Weibull plotting positions',\n",
     "                         pp_kws=dict(postype='weibull'), **common_opts)\n",
     "\n",
-    "fig = probscale.probplot(x, ax=ax3, xlabel='Custom plotting positions',\n",
+    "fig = probscale.probplot(x, ax=ax3, problabel='Custom plotting positions',\n",
     "                         pp_kws=dict(alpha=0.6, beta=0.1), **common_opts)\n",
     "ax1.set_xlim(left=1, right=99)\n",
     "seaborn.despine()\n",
@@ -666,4 +721,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 0
-}
+}