DOC: typo in the docstring of random.multinomial

Discuss a loaded dice with six sides. Also add the
text about handling of input probabilities, as written
by Robert Kern in gh-6612.

[ci skip]

1 files changed, 15 insertions, 2 deletions

diff --git a/numpy/random/mtrand/mtrand.pyx b/numpy/random/mtrand/mtrand.pyx
index d6ba58bb2..a2cee28b8 100644
--- a/numpy/random/mtrand/mtrand.pyx
+++ b/numpy/random/mtrand/mtrand.pyx
@@ -4461,8 +4461,21 @@ cdef class RandomState:
 
         A loaded dice is more likely to land on number 6:
 
-        >>> np.random.multinomial(100, [1/7.]*5)
-        array([13, 16, 13, 16, 42])
+        >>> np.random.multinomial(100, [1/7.]*5 + [2/7.])
+        array([11, 16, 14, 17, 16, 26])
+
+        The probability inputs should already be normalized. The value of the
+        last entry is always ignored and assumed to take up any leftover
+        probability mass. To sample a biased coin which has twice as much
+        weight on one side than the other should *not* be sampled like so:
+
+        >>> np.random.multinomial(100, [1.0, 2.0])  # WRONG
+        array([100,   0])
+
+        but rather, like so:
+
+        >>> np.random.multinomial(100, [1.0 / 3, 2.0 / 3])  # RIGHT
+        array([38, 62])
 
         """
         cdef npy_intp d