DOC/ENH: Update docstring and enhance logistic

Update docstring in _legacy.pyx for match generator.pyx Fix docstring in the constaint checker which had ineq rather than eq. Enhance logistic to accept 0 scale Reorder functions in _legacy to match generator to simplify keeping doc strings synchronized. Synchronize the docstring in _legacy
numpy · seberg · May 28, 2019 · Feb 20, 2018 · Feb 22, 2018 · Feb 23, 2018
commit 6e386c05c292da49224fcab372013a6d4247ae3b
diff --git a/_randomgen/README-git.md b/_randomgen/README-git.md
@@ -0,0 +1,26 @@
+These are the bash commands used to get the bashtage/randomgen repo into numpy/numpy
+
+```bash
+# from a directory just above a numpy git checkout
+git clone https://github.com/bashtage/randomgen.git
+cd randomgen
+# rewrite the checkout, pushing the content into '_randomgen'
+git filter-branch --index-filter '
+    git ls-files -s |
+    sed "s-\t-\t_randomgen/-" |
+    GIT_INDEX_FILE=$GIT_INDEX_FILE.new git update-index --index-info &&
+    mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE
+' HEAD
+# write this file, commit it
+git add _randomgen/README-git.md
+git commit -m"Add README-git.md"
+git checkout -b randomgen
+cd ../numpy
+git checkout -b randomgen
+git remote add randomgen ../randomgen
+git fetch randomgen randomgen
+git merge --allow-unrelated-histories randomgen/randomgen
+git remote remove randomgen
+# Now all the randomgen commits are on the randomgen branch in numpy,
+# and there is a subdirectory _randomgen with the content
+```
diff --git a/_randomgen/README.md b/_randomgen/README.md
@@ -12,8 +12,8 @@ generators in Python and NumPy.
 
 ## Python 2.7 Support
 
-Release 1.16.0 is the final version that supports Python 2.7. Any bugs
-in v1.16.0 will be patched until the end of 2019. All future releases
+v1.16 is the final major version that supports Python 2.7. Any bugs
+in v1.16 will be patched until the end of 2019. All future releases
 are Python 3, with an initial minimum version of 3.5.
 
 ## Compatibility Warning
@@ -164,7 +164,7 @@ need to be smoothed.
 Building requires:
 
 * Python (2.7, 3.5, 3.6, 3.7)
-* NumPy (1.13, 1.14, 1.15)
+* NumPy (1.13, 1.14, 1.15, 1.16)
 * Cython (0.26+)
 * tempita (0.5+), if not provided by Cython
67E6

diff --git a/_randomgen/README.rst b/_randomgen/README.rst
@@ -12,9 +12,9 @@ generators in Python and NumPy.
 Python 2.7 Support
 ------------------
 
-Release 1.16.0 is the final version that supports Python 2.7. Any bugs
-in v1.16.0 will be patched until the end of 2019. All future releases
-are Python 3, with an initial minimum version of 3.5.
+v1.16 is the final major version that supports Python 2.7. Any bugs in
+v1.16 will be patched until the end of 2019. All future releases are
+Python 3, with an initial minimum version of 3.5.
 
 Compatibility Warning
 ---------------------
@@ -181,7 +181,7 @@ Requirements
 Building requires:
 
 -  Python (2.7, 3.5, 3.6, 3.7)
--  NumPy (1.13, 1.14, 1.15)
+-  NumPy (1.13, 1.14, 1.15, 1.16)
 -  Cython (0.26+)
 -  tempita (0.5+), if not provided by Cython
 

diff --git a/_randomgen/doc/source/change-log.rst b/_randomgen/doc/source/change-log.rst
@@ -1,5 +1,10 @@
 Change Log
 ----------
+v1.16.1
+=======
+- Synchronized with upstream changes.
+- Fixed a bug in gamma generation if the shape parameters is 0.0.
+
 v1.16.0
 =======
 - Fixed a bug that affected :class:`~randomgen.dsfmt.DSFMT` when calling

diff --git a/_randomgen/randomgen/common.pyx b/_randomgen/randomgen/common.pyx
@@ -187,7 +187,7 @@ cdef int check_constraint(double val, object name, constraint_type cons) except
             raise ValueError(name + " <= 0")
     elif cons == CONS_BOUNDED_0_1 or cons == CONS_BOUNDED_0_1_NOTNAN:
         if val < 0 or val > 1:
-            raise ValueError(name + " <= 0 or " + name + " >= 1")
+            raise ValueError(name + " < 0 or " + name + " > 1")
         if cons == CONS_BOUNDED_0_1_NOTNAN:
             if np.isnan(val):
                 raise ValueError(name + ' contains NaNs')

diff --git a/_randomgen/randomgen/generator.pyx b/_randomgen/randomgen/generator.pyx
@@ -429,7 +429,8 @@ cdef class RandomGenerator:
         Parameters
         ----------
         scale : float or array_like of floats
-            The scale parameter, :math:`\\beta = 1/\\lambda`.
+            The scale parameter, :math:`\\beta = 1/\\lambda`. 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),
@@ -855,6 +856,8 @@ cdef class RandomGenerator:
             if size > pop_size:
                 raise ValueError("Cannot take a larger sample than "
                                  "population when 'replace=False'")
+            elif size < 0:
+                raise ValueError("negative dimensions are not allowed")
 
             if p is not None:
                 if np.count_nonzero(p > 0) < size:
@@ -1017,6 +1020,12 @@ cdef class RandomGenerator:
 
         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)``.
@@ -1065,16 +1074,20 @@ cdef class RandomGenerator:
 
         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
+        .. 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 (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 `standard_normal` instead.
+        tuple as the first argument, use `numpy.random.standard_normal` instead.
 
         Parameters
         ----------
@@ -1096,6 +1109,7 @@ cdef class RandomGenerator:
         See Also
         --------
         standard_normal : Similar, but takes a tuple as its argument.
+        normal : Also accepts mu and sigma arguments
 
         Notes
         -----
@@ -1106,13 +1120,13 @@ cdef class RandomGenerator:
         Examples
         --------
         >>> randomgen.generator.randn()
-        2.1923875335537315 #random
+        2.1923875335537315  # random
 
         Two-by-four array of samples from N(3, 6.25):
 
-        >>> 2.5 * randomgen.generator.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:
@@ -1237,20 +1251,43 @@ cdef class RandomGenerator:
         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
         --------
-        >>> s = randomgen.generator.standard_normal(8000)
+        >>> 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 = randomgen.generator.standard_normal(size=(3, 4, 2))
+        >>> 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
+
         """
         key = np.dtype(dtype).name
         if key == 'float64':
@@ -1283,7 +1320,8 @@ cdef class RandomGenerator:
         loc : float or array_like of floats
             Mean ("centre") of the distribution.
         scale : float or array_like of floats
-            Standard deviation (spread or "width") of the distribution.
+            Standard deviation (spread or "width") 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),
@@ -1334,11 +1372,11 @@ cdef class RandomGenerator:
 
         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:
@@ -1350,6 +1388,12 @@ cdef class RandomGenerator:
         ...          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
+
         """
         return cont(&random_normal_zig, self._brng, size, self.lock, 2,
                     loc, '', CONS_NONE,
@@ -1530,7 +1574,7 @@ cdef class RandomGenerator:
         Parameters
         ----------
         shape : float or array_like of floats
-            Parameter, should be > 0.
+            Parameter, 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),
@@ -1622,9 +1666,9 @@ cdef class RandomGenerator:
         Parameters
         ----------
         shape : float or array_like of floats
-            The shape of the gamma distribution. Should be greater than zero.
+            The shape of the gamma distribution. Must be non-negative.
         scale : float or array_like of floats, optional
-            The scale of the gamma distribution. Should be greater than zero.
+            The scale of the gamma distribution. Must be non-negative.
             Default is equal to 1.
         size : int or tuple of ints, optional
             Output shape.  If the given shape is, e.g., ``(m, n, k)``, then
@@ -1706,9 +1750,9 @@ cdef class RandomGenerator:
         Parameters
         ----------
         dfnum : int or array_like of ints
-            Degrees of freedom in numerator. Should be greater than zero.
+            Degrees of freedom in numerator. Must be non-negative.
         dfden : int or array_like of ints
-            Degrees of freedom in denominator. Should be greater than zero.
+            Degrees of freedom in denominator. 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),
@@ -2262,7 +2306,7 @@ cdef class RandomGenerator:
         Parameters
         ----------
         a : float or array_like of floats
-            Shape of the distribution. Should be greater than zero.
+            Shape of the distribution. All values must be positive.
         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),
@@ -2443,7 +2487,7 @@ cdef class RandomGenerator:
         Parameters
         ----------
         a : float or array_like of floats
-            Parameter of the distribution. Should be greater than zero.
+            Parameter of the distribution. Must be positive.
         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),
@@ -2513,12 +2557,12 @@ cdef class RandomGenerator:
         >>> plt.figure()
         >>> plt.hist(rvs, bins=50, density=True)
         >>> plt.plot(xx,powpdf,'r-')
-        >>> plt.title('randomgen.power(5)')
+        >>> plt.title('randomgen.generator.power(5)')
 
         >>> plt.figure()
         >>> plt.hist(1./(1.+rvsp), bins=50, density=True)
         >>> plt.plot(xx,powpdf,'r-')
-        >>> plt.title('inverse of 1 + randomgen.pareto(5)')
+        >>> plt.title('inverse of 1 + randomgen.generator.pareto(5)')
 
         >>> plt.figure()
         >>> plt.hist(1./(1.+rvsp), bins=50, density=True)
@@ -2548,7 +2592,8 @@ cdef class RandomGenerator:
         loc : float or array_like of floats, optional
             The position, :math:`\\mu`, of the distribution peak. Default is 0.
         scale : float or array_like of floats, optional
-            :math:`\\lambda`, the exponential decay. Default is 1.
+            :math:`\\lambda`, the exponential decay. Default is 1. 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),
@@ -2630,7 +2675,8 @@ cdef class RandomGenerator:
         loc : float or array_like of floats, optional
             The location of the mode of the distribution. Default is 0.
         scale : float or array_like of floats, optional
-            The scale parameter of the distribution. Default is 1.
+            The scale parameter of the distribution. Default is 1. 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),
@@ -2746,7 +2792,7 @@ cdef class RandomGenerator:
         loc : float or array_like of floats, optional
             Parameter of the distribution. Default is 0.
         scale : float or array_like of floats, optional
-            Parameter of the distribution. Should be greater than zero.
+            Parameter of the distribution. Must be >= 0.
             Default is 1.
         size : int or tuple of ints, optional
             Output shape.  If the given shape is, e.g., ``(m, n, k)``, then
@@ -2809,7 +2855,7 @@ cdef class RandomGenerator:
         """
         return cont(&random_logistic, self._brng, size, self.lock, 2,
                     loc, 'loc', CONS_NONE,
-                    scale, 'scale', CONS_POSITIVE,
+                    scale, 'scale', CONS_NON_NEGATIVE,
                     0.0, '', CONS_NONE, None)
 
     def lognormal(self, mean=0.0, sigma=1.0, size=None):
@@ -2828,8 +2874,8 @@ cdef class RandomGenerator:
         mean : float or array_like of floats, optional
             Mean value of the underlying normal distribution. Default is 0.
         sigma : float or array_like of floats, optional
-            Standard deviation of the underlying normal distribution. Should
-            be greater than zero. Default is 1.
+            Standard deviation of the underlying normal distribution. Must be
+            non-negative. Default is 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),
@@ -2934,7 +2980,7 @@ cdef class RandomGenerator:
         Parameters
         ----------
         scale : float or array_like of floats, optional
-            Scale, also equals the mode. Should be >= 0. Default is 1.
+            Scale, also equals the mode. Must be non-negative. Default is 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),
@@ -3463,7 +3509,7 @@ cdef class RandomGenerator:
         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),