From ed4f296fca51e6672c23f51199a8bfc222853497 Mon Sep 17 00:00:00 2001 From: Eric Wieser Date: Sun, 24 Feb 2019 18:34:59 -0800 Subject: [PATCH 1/2] DOC: Remove incorrect statement about `randn` accepting floats as sizes This gives an error at least as far back as 1.12.x --- numpy/random/mtrand/mtrand.pyx | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/numpy/random/mtrand/mtrand.pyx b/numpy/random/mtrand/mtrand.pyx index ca98400555bd..890e85e5402c 100644 --- a/numpy/random/mtrand/mtrand.pyx +++ b/numpy/random/mtrand/mtrand.pyx @@ -1372,13 +1372,11 @@ cdef class RandomState: Return a sample (or samples) from the "standard normal" distribution. - If positive, int_like or int-convertible arguments are provided, - `randn` generates an array of shape ``(d0, d1, ..., dn)``, filled + If positive int_like arguments are provided, `randn` generates an array + of shape ``(d0, d1, ..., dn)``, filled with random floats sampled from a univariate "normal" (Gaussian) - distribution of mean 0 and variance 1 (if any of the :math:`d_i` are - floats, they are first converted to integers by truncation). A single - float randomly sampled from the distribution is returned if no - argument is provided. + distribution of mean 0 and variance 1. A single float randomly sampled + from the distribution is returned if no argument is provided. This is a convenience function. If you want an interface that takes a tuple as the first argument, use `numpy.random.standard_normal` instead. From dac6fdcc40c5d27a36b562fc99383df4bd263fdb Mon Sep 17 00:00:00 2001 From: Eric Wieser Date: Sun, 24 Feb 2019 18:51:00 -0800 Subject: [PATCH 2/2] DOC: Encourage users to use the non-matlab-style random functions In response to twitter conversations that complain that `randn` is inconsistent with `zeros`, to which the answer is "that's because randn is a wrapper to make things look like matlab". --- doc/source/user/numpy-for-matlab-users.rst | 2 +- numpy/random/mtrand/mtrand.pyx | 66 ++++++++++++++++------ 2 files changed, 50 insertions(+), 18 deletions(-) diff --git a/doc/source/user/numpy-for-matlab-users.rst b/doc/source/user/numpy-for-matlab-users.rst index 16ee48c5ecd5..e53d1ca45558 100644 --- a/doc/source/user/numpy-for-matlab-users.rst +++ b/doc/source/user/numpy-for-matlab-users.rst @@ -436,7 +436,7 @@ Linear Algebra Equivalents ``a`` * - ``rand(3,4)`` - - ``random.rand(3,4)`` + - ``random.rand(3,4)`` or ``random.random_sample((3, 4))`` - random 3x4 matrix * - ``linspace(1,3,4)`` diff --git a/numpy/random/mtrand/mtrand.pyx b/numpy/random/mtrand/mtrand.pyx index 890e85e5402c..a19bdeffbd0c 100644 --- a/numpy/random/mtrand/mtrand.pyx +++ b/numpy/random/mtrand/mtrand.pyx @@ -1328,6 +1328,12 @@ cdef class RandomState: Random values in a given shape. + .. note:: + This is a convenience function for users porting code from Matlab, + and wraps `numpy.random.random_sample`. That function takes a + tuple to specify the size of the output, which is consistent with + other NumPy functions like `numpy.zeros` and `numpy.ones`. + Create an array of the given shape and populate it with random samples from a uniform distribution over ``[0, 1)``. @@ -1347,12 +1353,6 @@ cdef class RandomState: -------- random - Notes - ----- - This is a convenience function. If you want an interface that - takes a shape-tuple as the first argument, refer to - np.random.random_sample . - Examples -------- >>> np.random.rand(3,2) @@ -1372,15 +1372,18 @@ cdef class RandomState: Return a sample (or samples) from the "standard normal" distribution. + .. note:: + This is a convenience function for users porting code from Matlab, + and wraps `numpy.random.standard_normal`. That function takes a + tuple to specify the size of the output, which is consistent with + other NumPy functions like `numpy.zeros` and `numpy.ones`. + If positive int_like arguments are provided, `randn` generates an array of shape ``(d0, d1, ..., dn)``, filled with random floats sampled from a univariate "normal" (Gaussian) distribution of mean 0 and variance 1. A single float randomly sampled from the distribution is returned if no argument is provided. - This is a convenience function. If you want an interface that takes a - tuple as the first argument, use `numpy.random.standard_normal` instead. - Parameters ---------- d0, d1, ..., dn : int, optional @@ -1397,6 +1400,7 @@ cdef class RandomState: See Also -------- standard_normal : Similar, but takes a tuple as its argument. + normal : Also accepts mu and sigma arguments. Notes ----- @@ -1407,14 +1411,13 @@ cdef class RandomState: Examples -------- >>> np.random.randn() - 2.1923875335537315 #random + 2.1923875335537315 # random Two-by-four array of samples from N(3, 6.25): - >>> 2.5 * np.random.randn(2, 4) + 3 - array([[-4.49401501, 4.00950034, -1.81814867, 7.29718677], #random - [ 0.39924804, 4.68456316, 4.99394529, 4.84057254]]) #random - + >>> 3 + 2.5 * np.random.randn(2, 4) + array([[-4.49401501, 4.00950034, -1.81814867, 7.29718677], # random + [ 0.39924804, 4.68456316, 4.99394529, 4.84057254]]) # random """ if len(args) == 0: return self.standard_normal() @@ -1534,20 +1537,43 @@ cdef class RandomState: Returns ------- out : float or ndarray - Drawn samples. + A floating-point array of shape ``size`` of drawn samples, or a + single sample if ``size`` was not specified. + + Notes + ----- + For random samples from :math:`N(\\mu, \\sigma^2)`, use one of:: + + mu + sigma * np.random.standard_normal(size=...) + np.random.normal(mu, sigma, size=...) + + See Also + -------- + normal : + Equivalent function with additional ``loc`` and ``scale`` arguments + for setting the mean and standard deviation. Examples -------- + >>> np.random.standard_normal() + 2.1923875335537315 #random + >>> s = np.random.standard_normal(8000) >>> s - array([ 0.6888893 , 0.78096262, -0.89086505, ..., 0.49876311, #random - -0.38672696, -0.4685006 ]) #random + array([ 0.6888893 , 0.78096262, -0.89086505, ..., 0.49876311, # random + -0.38672696, -0.4685006 ]) # random >>> s.shape (8000,) >>> s = np.random.standard_normal(size=(3, 4, 2)) >>> s.shape (3, 4, 2) + Two-by-four array of samples from :math:`N(3, 6.25)`: + + >>> 3 + 2.5 * np.random.standard_normal(size=(2, 4)) + array([[-4.49401501, 4.00950034, -1.81814867, 7.29718677], # random + [ 0.39924804, 4.68456316, 4.99394529, 4.84057254]]) # random + """ return cont0_array(self.internal_state, rk_gauss, size, self.lock) @@ -1640,6 +1666,12 @@ cdef class RandomState: ... linewidth=2, color='r') >>> plt.show() + Two-by-four array of samples from N(3, 6.25): + + >>> np.random.normal(3, 2.5, size=(2, 4)) + array([[-4.49401501, 4.00950034, -1.81814867, 7.29718677], # random + [ 0.39924804, 4.68456316, 4.99394529, 4.84057254]]) # random + """ cdef ndarray oloc, oscale cdef double floc, fscale