Minor doc tweaks (titles, formatting, organization) (#19)

Author: phobson

docs/api/formatters.rst

@@ -0,0 +1,11 @@
+.. _formatters_auto:
+
+   The ``formatters`` API
+
+``formatters`` API Reference
+============================
+
+.. automodule:: probscale.formatters
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/transforms.rst

@@ -0,0 +1,11 @@
+.. _transforms_auto:
+
+   The ``transforms`` API
+
+``transforms`` API Reference
+============================
+
+.. automodule:: probscale.transforms
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/tutorial/Makefile

@@ -1,4 +1,4 @@
 notebooks:
 
-	tools/nb_to_doc.py getting_started  
+	tools/nb_to_doc.py getting_started
 	tools/nb_to_doc.py closer_look_at_viz

docs/tutorial/closer_look_at_viz.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# A closer look probability plots\n",
+    "# A closer look at probability plots\n",
     "\n",
     "## Overview\n",
     "\n",
@@ -39,6 +39,9 @@
    },
    "outputs": [],
    "source": [
+    "import warnings\n",
+    "warnings.simplefilter('ignore')\n",
+    "\n",
     "import numpy\n",
     "from matplotlib import pyplot\n",
     "import seaborn\n",
@@ -520,28 +523,28 @@
     "\n",
     "The most common values can be selected via the ``postype`` parameter and are described as follows:\n",
     "\n",
-    "    \"type 4\" : (0, 1)\n",
+    "    \"type 4\" (α=2, β=1)\n",
     "        Linear interpolation of the empirical CDF.\n",
-    "    \"type 5\" or \"hazen\" : (0.5, 0.5)\n",
+    "    \"type 5\" or \"hazen\" (α=0.5, β=0.5)\n",
     "        Piecewise linear interpolation.\n",
-    "    \"type 6\" or \"weibull\" : (0, 0)\n",
+    "    \"type 6\" or \"weibull\" (α=0, β=0)\n",
     "        Weibull plotting positions. Unbiased exceedance probability\n",
     "        for all distributions. This is will be the default value.\n",
-    "    \"type 7\" : (1, 1)\n",
+    "    \"type 7\" (α=1, β=1)\n",
     "        The default values in R.\n",
-    "    \"type 8\" : (1/3, 1/3)\n",
+    "    \"type 8\" (α=1/3, β=1/3)\n",
     "        Approximately median-unbiased.\n",
-    "    \"type 9\" or \"blom\" : (0.375, 0.375)\n",
+    "    \"type 9\" or \"blom\" (α=0.375, β=0.375)\n",
     "        Approximately unbiased positions if the data are normally\n",
     "        distributed.\n",
-    "    \"median\" : (0.3175, 0.3175)\n",
+    "    \"median\" (α=0.3175, β=0.3175)\n",
     "        Median exceedance probabilities for all distributions\n",
     "        (used in ``scipy.stats.probplot``).\n",
-    "    \"apl\" or \"pwm\" : (0.35, 0.35)\n",
+    "    \"apl\" or \"pwm\" (α=0.35, β=0.35)\n",
     "        Used with probability-weighted moments.\n",
-    "    \"cunnane\" : (0.4, 0.4)\n",
+    "    \"cunnane\" (α=0.4, β=0.4)\n",
     "        Nearly unbiased quantiles for normally distributed data.\n",
-    "    \"gringorten\" : (0.44, 0.44)\n",
+    "    \"gringorten\" (α=0.44, β=0.44)\n",
     "        Used for Gumble distributions.\n",
     "        \n",
     "These are controlled via the `pp_kws` parameter in `probplot`"
@@ -661,4 +664,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 0
-}
+}

docs/tutorial/getting_started.ipynb

@@ -197,27 +197,23 @@
    "source": [
     "fig, (ax1, ax2, ax3, ax4) = pyplot.subplots(figsize=(8, 4), 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_xlim(left=2, right=98)\n",
     "ax1.set_xlabel('Normal probability scale, as percents')\n",
-    "ax1.set_yticks([])\n",
     "\n",
     "beta1 = stats.beta(a=3, b=2)\n",
     "ax2.set_xscale('prob', dist=beta1)\n",
-    "ax2.set_xlim(left=2, right=98)\n",
     "ax2.set_xlabel('Beta probability scale (α=3, β=2)')\n",
-    "ax2.set_yticks([])\n",
     "\n",
     "beta2 = stats.beta(a=2, b=7)\n",
     "ax3.set_xscale('prob', dist=beta2)\n",
-    "ax3.set_xlim(left=2, right=98)\n",
     "ax3.set_xlabel('Beta probability scale (α=2, β=7)')\n",
-    "ax3.set_yticks([])\n",
     "\n",
-    "ax4.set_xlim(left=2, right=98)\n",
     "ax4.set_xticks(ax1.get_xticks()[12:-12])\n",
     "ax4.set_xlabel('Linear scale (for reference)')\n",
-    "ax4.set_yticks([])\n",
     "\n",
     "seaborn.despine(fig=fig, left=True)"
    ]
@@ -398,4 +394,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 0
-}
+}

probscale/formatters.py

@@ -3,9 +3,12 @@
 
 
 class _FormatterMixin(Formatter):
+    """ A mpl-axes formatter mixin class """
+
     @classmethod
     def _sig_figs(cls, x, n, expthresh=5, forceint=False):
-        """ Formats a number with the correct number of sig figs.
+        """
+        Formats a number with the correct number of significant digits.
 
         Parameters
         ----------
@@ -85,12 +88,22 @@ def __call__(self, x, pos=None):
 
 
 class PctFormatter(_FormatterMixin):
+    """
+    Formatter class for MPL axes to display probalities as percentages.
+
+    """
+
     factor = 1.0
     offset = 2
     top = 100
 
 
 class ProbFormatter(_FormatterMixin):
+    """
+    Formatter class for MPL axes to display probalities as decimals.
+
+    """
+
     factor = 100.0
     offset = 0
     top = 1

probscale/probscale.py

@@ -12,6 +12,12 @@
 
 
 class _minimal_norm(object):
+    """
+    A basic implmentation of a normal distribution, minimally
+    API-complient with scipt.stats.norm
+
+    """
+
     _A = -(8 * (numpy.pi - 3.0) / (3.0 * numpy.pi * (numpy.pi - 4.0)))
 
     @classmethod
@@ -71,10 +77,16 @@ class ProbScale(ScaleBase):
 
     Examples
     --------
-    >>> from matplotlib import pyplot
-    >>> import probscale
-    >>> fig, ax = pyplot.subplots()
-    >>> ax.set_xscale('prob')
+    The most basic use:
+
+    .. plot::
+        :context: close-figs
+
+        >>> from matplotlib import pyplot
+        >>> import probscale
+        >>> fig, ax = pyplot.subplots()
+        >>> ax.set_xlim(left=0.2, right=99.9)
+        >>> ax.set_xscale('prob')
 
     """
 
@@ -111,6 +123,7 @@ def _get_probs(cls, nobs, as_pct):
             new_lower = lower_fringe / 10**(n)
             new_upper = upper_fringe / 10**(n) + axis_probs.max()
             axis_probs = numpy.hstack([new_lower, axis_probs, new_upper])
+
         locs = axis_probs / factor
         return locs
 

probscale/transforms.py

@@ -28,6 +28,12 @@ def _clip_out_of_bounds(a):
 
 
 class _ProbTransformMixin(Transform):
+    """
+    Mixin for MPL axes transform for quantiles/probabilities or
+    percentages.
+
+    """
+
     input_dims = 1
     output_dims = 1
     is_separable = True
@@ -52,6 +58,12 @@ def __init__(self, dist, as_pct=True, nonpos='mask'):
 
 
 class ProbTransform(_ProbTransformMixin):
+    """
+    MPL axes tranform class to convert quantiles to probabilities
+    or percents.
+
+    """
+
     def transform_non_affine(self, prob):
         prob = self._handle_out_of_bounds(numpy.asarray(prob) / self.factor)
         q = self.dist.ppf(prob)
@@ -62,6 +74,12 @@ def inverted(self):
 
 
 class QuantileTransform(_ProbTransformMixin):
+    """
+    MPL axes tranform class to convert probabilities or percents to
+    quantiles.
+
+    """
+
     def transform_non_affine(self, q):
         prob = self.dist.cdf(q) * self.factor
         return prob

probscale/viz.py

@@ -242,6 +242,7 @@ def plot_pos(data, postype=None, alpha=None, beta=None):
         'cunnane': (0.4, 0.4),
         'gringorten': (0.44, 0.44), # Gumble
     }
+
     postype = 'cunnane' if postype is None else postype
     if alpha is None and beta is None:
         alpha, beta = pos_params[postype.lower()]