Merge pull request #28 from phobson/new-api-doc

New api doc

Author: phobson

.travis.yml

@@ -32,15 +32,15 @@ before_install:
   - ./miniconda.sh -b -p $HOME/miniconda
   - export PATH="$HOME/miniconda/bin:$PATH"
   - conda update --yes conda
+  - conda install --yes nomkl
 
 install:
 
   # We just set up a conda environment with the right Python version. This
   # should not need changing.
 
-  - conda create --yes -n test python=$TRAVIS_PYTHON_VERSION
+  - conda create --yes -n test python=$TRAVIS_PYTHON_VERSION numpy matplotlib docopt requests pyyaml
   - source activate test
-  - conda install --yes --channel=conda-forge numpy matplotlib docopt requests pyyaml
   - conda install --yes --channel=${TESTERS}
   - if [ ${COVERAGE} = true ]; then conda install scipy --yes; fi
   - pip install coveralls

docs/api/validate.rst

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

docs/conf.py

@@ -17,6 +17,9 @@
 import os
 import shlex
 
+import seaborn
+clear_bkgd = {'axes.facecolor':'none', 'figure.facecolor':'none'}
+seaborn.set(style='ticks', context='talk', color_codes=True, rc=clear_bkgd)
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -60,6 +63,12 @@
 # source_suffix = ['.rst', '.md']
 source_suffix = '.rst'
 
+# Include the example source for plots in API docs
+plot_include_source = True
+plot_formats = [("png", 150)]
+plot_html_show_formats = False
+plot_html_show_source_link = False
+
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
 

probscale/formatters.py

@@ -94,6 +94,17 @@ class PctFormatter(_FormatterMixin):
     """
     Formatter class for MPL axes to display probalities as percentages.
 
+    Examples
+    --------
+    >>> from probscale import formatters
+    >>> fmt = formatters.PctFormatter()
+    >>> fmt(0.2)
+    '0.2'
+    >>> fmt(10)
+    '10'
+    >>> fmt(99.999)
+    '99.999'
+
     """
 
     factor = 1.0
@@ -105,6 +116,19 @@ class ProbFormatter(_FormatterMixin):
     """
     Formatter class for MPL axes to display probalities as decimals.
 
+    Examples
+    --------
+    >>> from probscale import formatters
+    >>> fmt = formatters.ProbFormatter()
+    >>> fmt(0.01)
+    '0,01'
+    >>> fmt(0.2)
+    '0.20'
+    >>> try:
+    ...    fmt(10.5)
+    ... except(ValueError):
+    ...     print('formatter out of bounds')
+    formatter out of bounds
     """
 
     factor = 100.0

probscale/probscale.py

@@ -85,8 +85,8 @@ class ProbScale(ScaleBase):
         >>> from matplotlib import pyplot
         >>> import probscale
         >>> fig, ax = pyplot.subplots()
-        >>> ax.set_xlim(left=0.2, right=99.9)
-        >>> ax.set_xscale('prob')
+        >>> ax.set_ylim(bottom=0.2, top=99.9)
+        >>> ax.set_yscale('prob')
 
     """
 

probscale/tests/baseline_images/test_probscale/test_the_scale_default.png

@@ -6,7 +6,7 @@
 
 try:
     from scipy import stats
-except:
+except:  # pragma: no cover
     stats = None
 
 import pytest

probscale/tests/baseline_images/test_viz/test_probplot_beta_dist_best_fit_y.png

@@ -22,69 +22,81 @@ def test__clip_out_of_bounds():
     assert numpy.all(diff < 0.0001)
 
 
-class Mixin_Transform(object):
-    known_input_dims = 1
-    known_output_dims = 1
-    known_is_separable = True
-    known_has_inverse = True
 
-    def test_input_dims(self):
-        assert hasattr(self.trans, 'input_dims')
-        assert self.trans.input_dims == self.known_input_dims
+@pytest.fixture
+def prob_trans():
+    cls = transforms.ProbTransform
+    return cls(_minimal_norm)
 
-    def test_output_dims(self):
-        assert hasattr(self.trans, 'output_dims')
-        assert self.trans.output_dims == self.known_output_dims
 
-    def test_is_separable(self):
-        assert hasattr(self.trans, 'is_separable')
-        assert self.trans.is_separable == self.known_is_separable
+@pytest.fixture
+def quant_trans():
+    cls = transforms.QuantileTransform
+    return cls(_minimal_norm)
 
-    def test_has_inverse(self):
-        assert hasattr(self.trans, 'has_inverse')
-        assert self.trans.has_inverse == self.known_has_inverse
 
-    def test_dist(self):
-        assert hasattr(self.trans, 'dist')
-        assert self.trans.dist == _minimal_norm
+@pytest.mark.parametrize('trans', [prob_trans(), quant_trans()])
+def test_transform_input_dims(trans):
+    assert trans.input_dims == 1
 
-    def test_transform_non_affine(self):
-        assert hasattr(self.trans, 'transform_non_affine')
-        diff = numpy.abs(self.trans.transform_non_affine([0.5]) - self.known_tras_na)
-        assert numpy.all(diff < 0.0001)
 
-    def test_inverted(self):
-        assert hasattr(self.trans, 'inverted')
+@pytest.mark.parametrize('trans', [prob_trans(), quant_trans()])
+def test_transform_output_dims(trans):
+    assert trans.output_dims == 1
 
-    def test_bad_non_pos(self):
-        with pytest.raises(ValueError):
-            self._trans(_minimal_norm, nonpos='junk')
 
-    def test_non_pos_clip(self):
-        self._trans(_minimal_norm, nonpos='clip')
+@pytest.mark.parametrize('trans', [prob_trans(), quant_trans()])
+def test_transform_is_separable(trans):
+    assert trans.is_separable
+
 
+@pytest.mark.parametrize('trans', [prob_trans(), quant_trans()])
+def test_transform_has_inverse(trans):
+    assert trans.has_inverse
 
-class Test_ProbTransform(Mixin_Transform):
-    def setup(self):
-        self._trans = transforms.ProbTransform
-        self.trans = transforms.ProbTransform(_minimal_norm)
-        self.known_tras_na = [-2.569150498]
 
-    def test_inverted(self):
-        inv_trans = self.trans.inverted()
-        assert self.trans.dist == inv_trans.dist
-        assert self.trans.factor == inv_trans.factor
-        assert self.trans.nonpos == inv_trans.nonpos
+@pytest.mark.parametrize('trans', [prob_trans(), quant_trans()])
+def test_transform_dist(trans):
+    trans.dist == _minimal_norm
 
 
-class Test_QuantileTransform(Mixin_Transform):
-    def setup(self):
-        self._trans = transforms.QuantileTransform
-        self.trans = transforms.QuantileTransform(_minimal_norm)
-        self.known_tras_na = [69.1464492]
+@pytest.mark.parametrize(('trans', 'known_trans_na'), [
+    (prob_trans(), -2.569150498), (quant_trans(), 69.1464492)
+])
+def test_transform_non_affine(trans, known_trans_na):
+    diff = numpy.abs(trans.transform_non_affine([0.5]) - known_trans_na)
+    assert numpy.all(diff < 0.0001)
 
-    def test_inverted(self):
-        inv_trans = self.trans.inverted()
-        assert self.trans.dist == inv_trans.dist
-        assert self.trans.factor == inv_trans.factor
-        assert self.trans.nonpos == inv_trans.nonpos
+
+@pytest.mark.parametrize(('trans', 'inver_cls'), [
+    (prob_trans(), transforms.QuantileTransform),
+    (quant_trans(), transforms.ProbTransform),
+])
+def test_transform_inverted(trans, inver_cls):
+    t_inv = trans.inverted()
+    assert isinstance(t_inv, inver_cls)
+    assert trans.dist == t_inv.dist
+    assert trans.as_pct == t_inv.as_pct
+    assert trans.out_of_bounds == t_inv.out_of_bounds
+
+
+@pytest.mark.parametrize('cls', [transforms.ProbTransform, transforms.QuantileTransform])
+def test_bad_out_of_bounds(cls):
+    with pytest.raises(ValueError):
+        cls(_minimal_norm, out_of_bounds='junk')
+
+
+@pytest.mark.parametrize('cls', [transforms.ProbTransform, transforms.QuantileTransform])
+@pytest.mark.parametrize(('method', 'func'), [
+    ('clip', transforms._clip_out_of_bounds),
+    ('mask', transforms._mask_out_of_bounds),
+    ('junk', None),
+])
+def test_out_of_bounds(cls, method, func):
+    if func is None:
+        with pytest.raises(ValueError):
+            cls(_minimal_norm, out_of_bounds=method)
+    else:
+        t = cls(_minimal_norm, out_of_bounds=method)
+        assert t.out_of_bounds == method
+        assert t._handle_out_of_bounds == func

probscale/tests/baseline_images/test_viz/test_probplot_color_and_label.png

@@ -3,7 +3,7 @@
 import numpy
 import matplotlib.pyplot as plt
 
-if sys.version_info.major == 2:
+if sys.version_info.major == 2:  # pragma: no cover
     import mock
 else:
     from unittest import mock
@@ -12,7 +12,7 @@
 
 try:
     from scipy import stats
-except:
+except:  # pragma: no cover
     stats = None
 
 from probscale import viz
@@ -392,6 +392,16 @@ def test_probplot_qq(plot_data):
     return fig
 
 
+@pytest.mark.mpl_image_compare(baseline_dir=BASELINE_DIR, tolerance=10)
+@pytest.mark.skipif(stats is None, reason="no scipy")
+def test_probplot_qq_dist(plot_data):
+    fig, ax = plt.subplots()
+    norm = stats.norm(*stats.norm.fit(plot_data))
+    fig = viz.probplot(plot_data, ax=ax, plottype='qq', dist=norm,
+                       datalabel='Test label')
+    return fig
+
+
 @pytest.mark.mpl_image_compare(baseline_dir=BASELINE_DIR, tolerance=10)
 def test_probplot_pp(plot_data):
     fig, ax = plt.subplots()
@@ -482,7 +492,7 @@ def test_probplot_pp_bestfit_probax_y(plot_data):
     return fig
 
 
-@pytest.mark.mpl_image_compare(baseline_dir=BASELINE_DIR, tolerance=15)
+@pytest.mark.mpl_image_compare(baseline_dir=BASELINE_DIR, tolerance=10)
 @pytest.mark.skipif(stats is None, reason="no scipy")
 def test_probplot_beta_dist_best_fit_y(plot_data):
     fig, (ax1, ax2) = plt.subplots(ncols=2)
@@ -526,8 +536,6 @@ def test_probplot_test_results(plot_data):
     return fig
 
 
-
-
 @pytest.mark.parametrize('probax', ['x', 'y'])
 @pytest.mark.parametrize(('N', 'minval', 'maxval'), [
     (8, 10, 90),
@@ -544,3 +552,11 @@ def test__set_prob_limits_x(probax, N, minval, maxval):
             ax.set_xlim.assert_called_once_with(left=minval, right=maxval)
         elif probax == 'y':
             ax.set_ylim.assert_called_once_with(bottom=minval, top=maxval)
+
+
+@pytest.mark.mpl_image_compare(baseline_dir=BASELINE_DIR, tolerance=10)
+def test_probplot_color_and_label(plot_data):
+    fig, ax = plt.subplots()
+    fig = viz.probplot(plot_data, ax=ax, color='pink', label='A Top-Level Label')
+    ax.legend(loc='lower right')
+    return fig

probscale/tests/baseline_images/test_viz/test_probplot_qq_dist.png

@@ -39,29 +39,43 @@ class _ProbTransformMixin(Transform):
     is_separable = True
     has_inverse = True
 
-    def __init__(self, dist, as_pct=True, nonpos='mask'):
+    def __init__(self, dist, as_pct=True, out_of_bounds='mask'):
         Transform.__init__(self)
         self.dist = dist
         self.as_pct = as_pct
-        self.nonpos = nonpos
+        self.out_of_bounds = out_of_bounds
         if self.as_pct:
             self.factor = 100.0
         else:
             self.factor = 1.0
 
-        if self.nonpos == 'mask':
+        if self.out_of_bounds == 'mask':
             self._handle_out_of_bounds = _mask_out_of_bounds
-        elif self.nonpos == 'clip':
+        elif self.out_of_bounds == 'clip':
             self._handle_out_of_bounds = _clip_out_of_bounds
         else:
-            raise ValueError("`nonpos` muse be either 'mask' or 'clip'")
+            raise ValueError("`out_of_bounds` muse be either 'mask' or 'clip'")
 
 
 class ProbTransform(_ProbTransformMixin):
     """
     MPL axes tranform class to convert quantiles to probabilities
     or percents.
 
+    Parameters
+    ----------
+    dist : scipy.stats distribution
+        The distribution whose ``cdf`` and ``pdf`` methods wiil set the
+        scale of the axis.
+    as_pct : bool, optional (True)
+        Toggles the formatting of the probabilities associated with the
+        tick labels as percentanges (0 - 100) or fractions (0 - 1).
+    out_of_bounds : string, optionals ('mask' or 'clip')
+        Determines how data outside the range of valid values is
+        handled. The default behavior is to mask the data.
+        Alternatively, the data can be clipped to values arbitrarily
+        close to the limits of the scale.
+
     """
 
     def transform_non_affine(self, prob):
@@ -70,19 +84,33 @@ def transform_non_affine(self, prob):
         return q
 
     def inverted(self):
-        return QuantileTransform(self.dist, as_pct=self.as_pct, nonpos=self.nonpos)
+        return QuantileTransform(self.dist, as_pct=self.as_pct, out_of_bounds=self.out_of_bounds)
 
 
 class QuantileTransform(_ProbTransformMixin):
     """
     MPL axes tranform class to convert probabilities or percents to
     quantiles.
 
+    Parameters
+    ----------
+    dist : scipy.stats distribution
+        The distribution whose ``cdf`` and ``pdf`` methods wiil set the
+        scale of the axis.
+    as_pct : bool, optional (True)
+        Toggles the formatting of the probabilities associated with the
+        tick labels as percentanges (0 - 100) or fractions (0 - 1).
+    out_of_bounds : string, optionals ('mask' or 'clip')
+        Determines how data outside the range of valid values is
+        handled. The default behavior is to mask the data.
+        Alternatively, the data can be clipped to values arbitrarily
+        close to the limits of the scale.
+
     """
 
     def transform_non_affine(self, q):
         prob = self.dist.cdf(q) * self.factor
         return prob
 
     def inverted(self):
-        return ProbTransform(self.dist, as_pct=self.as_pct, nonpos=self.nonpos)
+        return ProbTransform(self.dist, as_pct=self.as_pct, out_of_bounds=self.out_of_bounds)