bpo-37905: Improve docs for NormalDist (GH-15486) (GH-15487)

miss-islington · rhettinger · rhettinger · commit 970548c00b36 · 2019-08-25T01:04:24.000-07:00
(cherry picked from commit 8371799) Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>
diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst
@@ -667,12 +667,8 @@ of applications in statistics.
 
     .. method:: NormalDist.overlap(other)
 
-       Compute the `overlapping coefficient (OVL)
-       <http://www.iceaaonline.com/ready/wp-content/uploads/2014/06/MM-9-Presentation-Meet-the-Overlapping-Coefficient-A-Measure-for-Elevator-Speeches.pdf>`_
-       between two normal distributions, giving a measure of agreement.
-       Returns a value between 0.0 and 1.0 giving `the overlapping area for
-       the two probability density functions
-       <https://www.rasch.org/rmt/rmt101r.htm>`_.
+       Returns a value between 0.0 and 1.0 giving the overlapping area for
+       the two probability density functions.
 
     Instances of :class:`NormalDist` support addition, subtraction,
     multiplication and division by a constant.  These operations
@@ -734,16 +730,6 @@ Find the `quartiles <https://en.wikipedia.org/wiki/Quartile>`_ and `deciles
     >>> [round(sat.inv_cdf(p / 10)) for p in range(1, 10)]
     [810, 896, 958, 1011, 1060, 1109, 1162, 1224, 1310]
 
-What percentage of men and women will have the same height in `two normally
-distributed populations with known means and standard deviations
-<http://www.usablestats.com/lessons/normal>`_?
-
-    >>> men = NormalDist(70, 4)
-    >>> women = NormalDist(65, 3.5)
-    >>> ovl = men.overlap(women)
-    >>> round(ovl * 100.0, 1)
-    50.3
-
 To estimate the distribution for a model than isn't easy to solve
 analytically, :class:`NormalDist` can generate input samples for a `Monte
 Carlo simulation <https://en.wikipedia.org/wiki/Monte_Carlo_method>`_:
@@ -754,11 +740,12 @@ Carlo simulation <https://en.wikipedia.org/wiki/Monte_Carlo_method>`_:
     ...     return (3*x + 7*x*y - 5*y) / (11 * z)
     ...
     >>> n = 100_000
-    >>> X = NormalDist(10, 2.5).samples(n)
-    >>> Y = NormalDist(15, 1.75).samples(n)
-    >>> Z = NormalDist(5, 1.25).samples(n)
+    >>> seed = 86753099035768
+    >>> X = NormalDist(10, 2.5).samples(n, seed=seed)
+    >>> Y = NormalDist(15, 1.75).samples(n, seed=seed)
+    >>> Z = NormalDist(50, 1.25).samples(n, seed=seed)
     >>> NormalDist.from_samples(map(model, X, Y, Z))     # doctest: +SKIP
-    NormalDist(mu=19.640137307085507, sigma=47.03273142191088)
+    NormalDist(mu=1.8661894803304777, sigma=0.65238717376862)
 
 Normal distributions commonly arise in machine learning problems.
 
