bpo-37905: Improve docs for NormalDist (GH-15486) (GH-15487)
(cherry picked from commit 8371799e300475c8f9f967e900816218d3500e5d)
Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>
diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst
index 1a19e37..cbe2b82 100644
--- a/Doc/library/statistics.rst
+++ b/Doc/library/statistics.rst
@@ -667,12 +667,8 @@
.. 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 @@
>>> [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 @@
... 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.