Merge pull request #312 from sciunto/docstrings

Improvements to the stats.rv_discrete docstring.

scipy/stats/distributions.py

@@ -5521,14 +5521,8 @@ class rv_discrete(rv_generic):
 
     Notes
     -----
-    Alternatively, the object may be called (as a function) to fix the shape
-    and location parameters returning a "frozen" discrete RV object::
-
-        myrv = generic(<shape(s)>, loc=0)
-            - frozen RV object with the same methods but holding the given
-              shape and location fixed.
 
-    You can construct an aribtrary discrete rv where ``P{X=xk} = pk``
+    You can construct an arbitrary discrete rv where ``P{X=xk} = pk``
     by passing to the rv_discrete initialization method (through the
     values=keyword) a tuple of sequences (xk, pk) which describes only those
     values of X (xk) that occur with nonzero probability (pk).
@@ -5547,14 +5541,33 @@ def _pmf(self, k, mu):
 
     The docstring can be created from a template.
 
+    Alternatively, the object may be called (as a function) to fix the shape
+    and location parameters returning a "frozen" discrete RV object::
+
+        myrv = generic(<shape(s)>, loc=0)
+            - frozen RV object with the same methods but holding the given
+              shape and location fixed.
+
     Examples
     --------
+
+    Custom made discrete distribution:
+
     >>> import matplotlib.pyplot as plt
-    >>> numargs = generic.numargs
-    >>> [ <shape(s)> ] = ['Replace with resonable value', ]*numargs
+    >>> from scipy import stats
+    >>> xk = np.arange(7)
+    >>> pk = (0.1, 0.2, 0.3, 0.1, 0.1, 0.1, 0.1)
+    >>> custm = stats.rv_discrete(name='custm', values=(xk, pk))
+    >>> h = plt.plot(xk, custm.pmf(xk))
+
+    Random number generation:
+
+    >>> R = custm.rvs(size=100)
 
     Display frozen pmf:
 
+    >>> numargs = generic.numargs
+    >>> [ <shape(s)> ] = ['Replace with resonable value', ]*numargs
     >>> rv = generic(<shape(s)>)
     >>> x = np.arange(0, np.min(rv.dist.b, 3)+1)
     >>> h = plt.plot(x, rv.pmf(x))
@@ -5566,16 +5579,6 @@ def _pmf(self, k, mu):
     >>> prb = generic.cdf(x, <shape(s)>)
     >>> h = plt.semilogy(np.abs(x-generic.ppf(prb, <shape(s)>))+1e-20)
 
-    Random number generation:
-
-    >>> R = generic.rvs(<shape(s)>, size=100)
-
-    Custom made discrete distribution:
-
-    >>> vals = [arange(7), (0.1, 0.2, 0.3, 0.1, 0.1, 0.1, 0.1)]
-    >>> custm = rv_discrete(name='custm', values=vals)
-    >>> h = plt.plot(vals[0], custm.pmf(vals[0]))
-
     """
 
     def __init__(self, a=0, b=inf, name=None, badvalue=None,