diff options
Diffstat (limited to 'numpy/random/mtrand/mtrand.pyx')
| -rw-r--r-- | numpy/random/mtrand/mtrand.pyx | 183 |
1 files changed, 110 insertions, 73 deletions
diff --git a/numpy/random/mtrand/mtrand.pyx b/numpy/random/mtrand/mtrand.pyx index ca9840055..c97c166aa 100644 --- a/numpy/random/mtrand/mtrand.pyx +++ b/numpy/random/mtrand/mtrand.pyx @@ -866,10 +866,9 @@ cdef class RandomState: """ tomaxint(size=None) - Random integers between 0 and ``sys.maxint``, inclusive. - Return a sample of uniformly distributed random integers in the interval - [0, ``sys.maxint``]. + [0, ``np.iinfo(np.int).max``]. The np.int type translates to the C long + integer type and its precision is platform dependent. Parameters ---------- @@ -891,16 +890,15 @@ cdef class RandomState: Examples -------- - >>> RS = np.random.mtrand.RandomState() # need a RandomState object - >>> RS.tomaxint((2,2,2)) - array([[[1170048599, 1600360186], + >>> rs = np.random.RandomState() # need a RandomState object + >>> rs.tomaxint((2,2,2)) + array([[[1170048599, 1600360186], # random [ 739731006, 1947757578]], [[1871712945, 752307660], [1601631370, 1479324245]]]) - >>> import sys - >>> sys.maxint + >>> np.iinfo(np.int).max 2147483647 - >>> RS.tomaxint((2,2,2)) < sys.maxint + >>> rs.tomaxint((2,2,2)) < np.iinfo(np.int).max array([[[ True, True], [ True, True]], [[ True, True], @@ -992,7 +990,7 @@ cdef class RandomState: raise ValueError("high is out of bounds for %s" % dtype) if ilow >= ihigh and np.prod(size) != 0: raise ValueError("Range cannot be empty (low >= high) unless no samples are taken") - + with self.lock: ret = randfunc(ilow, ihigh - 1, size, self.state_address) @@ -1040,7 +1038,7 @@ cdef class RandomState: .. versionadded:: 1.7.0 Parameters - ----------- + ---------- a : 1-D array-like or int If an ndarray, a random sample is generated from its elements. If an int, the random sample is generated as if a were np.arange(a) @@ -1056,12 +1054,12 @@ cdef class RandomState: entries in a. Returns - -------- + ------- samples : single item or ndarray The generated random samples Raises - ------- + ------ ValueError If a is an int and less than zero, if a or p are not 1-dimensional, if a is an array-like of size 0, if p is not a vector of @@ -1070,11 +1068,11 @@ cdef class RandomState: size See Also - --------- + -------- randint, shuffle, permutation Examples - --------- + -------- Generate a uniform random sample from np.arange(5) of size 3: >>> np.random.choice(5, 3) @@ -1170,6 +1168,9 @@ cdef class RandomState: raise ValueError("Cannot take a larger sample than " "population when 'replace=False'") + if size < 0: + raise ValueError("negative dimensions are not allowed") + if p is not None: if np.count_nonzero(p > 0) < size: raise ValueError("Fewer non-zero entries in p than size") @@ -1328,6 +1329,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 +1354,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,16 +1373,17 @@ 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 - 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. + .. 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`. - This is a convenience function. If you want an interface that takes a - tuple as the first argument, use `numpy.random.standard_normal` instead. + 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. Parameters ---------- @@ -1399,6 +1401,7 @@ cdef class RandomState: See Also -------- standard_normal : Similar, but takes a tuple as its argument. + normal : Also accepts mu and sigma arguments. Notes ----- @@ -1409,13 +1412,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: @@ -1432,8 +1435,8 @@ cdef class RandomState: Return random integers of type np.int from the "discrete uniform" distribution in the closed interval [`low`, `high`]. If `high` is None (the default), then results are from [1, `low`]. The np.int - type translates to the C long type used by Python 2 for "short" - integers and its precision is platform dependent. + type translates to the C long integer type and its precision + is platform dependent. This function has been deprecated. Use randint instead. @@ -1536,20 +1539,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) @@ -1626,11 +1652,11 @@ cdef class RandomState: Verify the mean and the variance: - >>> abs(mu - np.mean(s)) < 0.01 - True + >>> abs(mu - np.mean(s)) + 0.0 # may vary - >>> abs(sigma - np.std(s, ddof=1)) < 0.01 - True + >>> abs(sigma - np.std(s, ddof=1)) + 0.1 # may vary Display the histogram of the samples, along with the probability density function: @@ -1642,6 +1668,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 @@ -1675,7 +1707,7 @@ cdef class RandomState: .. math:: f(x; a,b) = \\frac{1}{B(\\alpha, \\beta)} x^{\\alpha - 1} (1 - x)^{\\beta - 1}, - where the normalisation, B, is the beta function, + where the normalization, B, is the beta function, .. math:: B(\\alpha, \\beta) = \\int_0^1 t^{\\alpha - 1} (1 - t)^{\\beta - 1} dt. @@ -2296,7 +2328,7 @@ cdef class RandomState: Draw samples from a noncentral chi-square distribution. - The noncentral :math:`\\chi^2` distribution is a generalisation of + The noncentral :math:`\\chi^2` distribution is a generalization of the :math:`\\chi^2` distribution. Parameters @@ -2326,7 +2358,7 @@ cdef class RandomState: .. math:: P(x;df,nonc) = \\sum^{\\infty}_{i=0} \\frac{e^{-nonc/2}(nonc/2)^{i}}{i!} - \\P_{Y_{df+2i}}(x), + P_{Y_{df+2i}}(x), where :math:`Y_{q}` is the Chi-square with q degrees of freedom. @@ -2362,6 +2394,7 @@ cdef class RandomState: >>> values = plt.hist(np.random.noncentral_chisquare(3, 20, 100000), ... bins=200, density=True) >>> plt.show() + """ cdef ndarray odf, ononc cdef double fdf, fnonc @@ -2888,7 +2921,7 @@ cdef class RandomState: Parameters ---------- a : float or array_like of floats - Parameter of the distribution. Should be greater than zero. + Parameter of the distribution. Must be non-negative. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. If size is ``None`` (default), @@ -3401,7 +3434,7 @@ cdef class RandomState: >>> # values, drawn from a normal distribution. >>> b = [] >>> for i in range(1000): - ... a = 10. + np.random.random(100) + ... a = 10. + np.random.standard_normal(100) ... b.append(np.product(a)) >>> b = np.array(b) / np.min(b) # scale values to be positive @@ -3746,8 +3779,8 @@ cdef class RandomState: product p*n <=5, where p = population proportion estimate, and n = number of samples, in which case the binomial distribution is used instead. For example, a sample of 15 people shows 4 who are left - handed, and 11 who are right handed. Then p = 4/15 = 27%. 0.27*15 = 4, - so the binomial distribution should be used in this case. + handed, and 11 who are right handed. Then p = 4/15 = 27%. Since + 0.27*15 = 4, the binomial distribution should be used in this case. References ---------- @@ -4019,7 +4052,7 @@ cdef class RandomState: Parameters ---------- a : float or array_like of floats - Distribution parameter. Should be greater than 1. + Distribution parameter. Must be greater than 1. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. If size is ``None`` (default), @@ -4170,9 +4203,9 @@ cdef class RandomState: Draw samples from a Hypergeometric distribution. Samples are drawn from a hypergeometric distribution with specified - parameters, ngood (ways to make a good selection), nbad (ways to make - a bad selection), and nsample = number of items sampled, which is less - than or equal to the sum ngood + nbad. + parameters, `ngood` (ways to make a good selection), `nbad` (ways to make + a bad selection), and `nsample` (number of items sampled, which is less + than or equal to the sum ``ngood + nbad``). Parameters ---------- @@ -4186,14 +4219,16 @@ cdef class RandomState: size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. If size is ``None`` (default), - a single value is returned if ``ngood``, ``nbad``, and ``nsample`` + a single value is returned if `ngood`, `nbad`, and `nsample` are all scalars. Otherwise, ``np.broadcast(ngood, nbad, nsample).size`` samples are drawn. Returns ------- out : ndarray or scalar - Drawn samples from the parameterized hypergeometric distribution. + Drawn samples from the parameterized hypergeometric distribution. Each + sample is the number of good items within a randomly selected subset of + size `nsample` taken from a set of `ngood` good items and `nbad` bad items. See Also -------- @@ -4208,11 +4243,11 @@ cdef class RandomState: where :math:`0 \\le x \\le n` and :math:`n-b \\le x \\le g` - for P(x) the probability of x successes, g = ngood, b = nbad, and - n = number of samples. + for P(x) the probability of ``x`` good results in the drawn sample, + g = `ngood`, b = `nbad`, and n = `nsample`. - Consider an urn with black and white marbles in it, ngood of them - black and nbad are white. If you draw nsample balls without + Consider an urn with black and white marbles in it, `ngood` of them + are black and `nbad` are white. If you draw `nsample` balls without replacement, then the hypergeometric distribution describes the distribution of black balls in the drawn sample. @@ -4387,7 +4422,7 @@ cdef class RandomState: def multivariate_normal(self, mean, cov, size=None, check_valid='warn', tol=1e-8): """ - multivariate_normal(mean, cov[, size, check_valid, tol]) + multivariate_normal(mean, cov, size=None, check_valid='warn', tol=1e-8) Draw random samples from a multivariate normal distribution. @@ -4414,6 +4449,7 @@ cdef class RandomState: Behavior when the covariance matrix is not positive semidefinite. tol : float, optional Tolerance when checking the singular values in covariance matrix. + cov is cast to double before the check. Returns ------- @@ -4525,6 +4561,8 @@ cdef class RandomState: # not zero. We continue to use the SVD rather than Cholesky in # order to preserve current outputs. + # GH10839, ensure double to make tol meaningful + cov = cov.astype(np.double) (u, s, v) = svd(cov) if check_valid != 'ignore': @@ -4552,7 +4590,7 @@ cdef class RandomState: Draw samples from a multinomial distribution. - The multinomial distribution is a multivariate generalisation of the + The multinomial distribution is a multivariate generalization of the binomial distribution. Take an experiment with one of ``p`` possible outcomes. An example of such an experiment is throwing a dice, where the outcome can be 1 through 6. Each sample drawn from the @@ -4668,7 +4706,7 @@ cdef class RandomState: Draw `size` samples of dimension k from a Dirichlet distribution. A Dirichlet-distributed random variable can be seen as a multivariate generalization of a Beta distribution. The Dirichlet distribution - is a conjugate prior of a multinomial distribution in Bayesian + is a conjugate prior of a multinomial distribution in Bayesian inference. Parameters @@ -4693,23 +4731,22 @@ cdef class RandomState: Notes ----- - - The Dirichlet distribution is a distribution over vectors - :math:`x` that fulfil the conditions :math:`x_i>0` and + The Dirichlet distribution is a distribution over vectors + :math:`x` that fulfil the conditions :math:`x_i>0` and :math:`\\sum_{i=1}^k x_i = 1`. - The probability density function :math:`p` of a - Dirichlet-distributed random vector :math:`X` is + The probability density function :math:`p` of a + Dirichlet-distributed random vector :math:`X` is proportional to .. math:: p(x) \\propto \\prod_{i=1}^{k}{x^{\\alpha_i-1}_i}, - where :math:`\\alpha` is a vector containing the positive + where :math:`\\alpha` is a vector containing the positive concentration parameters. The method uses the following property for computation: let :math:`Y` - be a random vector which has components that follow a standard gamma - distribution, then :math:`X = \\frac{1}{\\sum_{i=1}^k{Y_i}} Y` + be a random vector which has components that follow a standard gamma + distribution, then :math:`X = \\frac{1}{\\sum_{i=1}^k{Y_i}} Y` is Dirichlet-distributed References @@ -4924,7 +4961,7 @@ cdef class RandomState: return arr arr = np.asarray(x) - + # shuffle has fast-path for 1-d if arr.ndim == 1: # Return a copy if same memory @@ -4937,7 +4974,7 @@ cdef class RandomState: idx = np.arange(arr.shape[0], dtype=np.intp) self.shuffle(idx) return arr[idx] - + _rand = RandomState() seed = _rand.seed |