From c63f8119afb65e30f837ab7198776854bb92b9b2 Mon Sep 17 00:00:00 2001 From: mattip Date: Wed, 20 Nov 2019 22:10:15 -0800 Subject: [PATCH 1/4] DOC, API: add numpy.random.__index__.pxd and document numpy.random.* funcs --- doc/source/reference/random/index.rst | 81 +++-- doc/source/reference/random/legacy.rst | 60 ++++ numpy/random/__init__.pxd | 14 + numpy/random/_bounded_integers.pxd.in | 2 +- numpy/random/_common.pxd | 2 +- numpy/random/_examples/cython/extending.pyx | 2 +- .../cython/extending_distributions.pyx | 4 +- numpy/random/_generator.pyx | 14 +- numpy/random/_mt19937.pyx | 2 +- numpy/random/_pcg64.pyx | 2 +- numpy/random/_philox.pyx | 2 +- numpy/random/_sfc64.pyx | 2 +- numpy/random/mtrand.pyx | 293 +++++++++++++++++- numpy/random/setup.py | 1 + 14 files changed, 415 insertions(+), 66 deletions(-) create mode 100644 numpy/random/__init__.pxd diff --git a/doc/source/reference/random/index.rst b/doc/source/reference/random/index.rst index d28646df945c..48d7a48199e1 100644 --- a/doc/source/reference/random/index.rst +++ b/doc/source/reference/random/index.rst @@ -22,34 +22,41 @@ Since Numpy version 1.17.0 the Generator can be initialized with a number of different BitGenerators. It exposes many different probability distributions. See `NEP 19 `_ for context on the updated random Numpy number -routines. The legacy `.RandomState` random number routines are still +routines. The legacy `RandomState` random number routines are still available, but limited to a single BitGenerator. -For convenience and backward compatibility, a single `~.RandomState` +For convenience and backward compatibility, a single `RandomState` instance's methods are imported into the numpy.random namespace, see :ref:`legacy` for the complete list. +.. _random-quick-start: + Quick Start ----------- -By default, `~Generator` uses bits provided by `PCG64` which -has better statistical properties than the legacy mt19937 random -number generator in `~.RandomState`. +Call `default_rng` to get a new instance of a `Generator`, then call its +methods to obtain samples from different distributions. By default, +`Generator` uses bits provided by `PCG64` which has better statistical +properties than the legacy `MT19937` used in `RandomState`. .. code-block:: python - # Uses the old numpy.random.RandomState + #Do this + from numpy.random import default_rng + val = default_rng().standard_normal() + + # instead of this from numpy import random - random.standard_normal() + val = random.standard_normal() -`~Generator` can be used as a replacement for `~.RandomState`. Both class -instances now hold a internal `BitGenerator` instance to provide the bit +`Generator` can be used as a replacement for `RandomState`. Both class +instances hold a internal `BitGenerator` instance to provide the bit stream, it is accessible as ``gen.bit_generator``. Some long-overdue API cleanup means that legacy and compatibility methods have been removed from -`~.Generator` +`Generator` =================== ============== ============ -`~.RandomState` `~.Generator` Notes +`RandomState` `Generator` Notes ------------------- -------------- ------------ ``random_sample``, ``random`` Compatible with `random.random` ``rand`` @@ -58,21 +65,12 @@ cleanup means that legacy and compatibility methods have been removed from ``random_integers`` ------------------- -------------- ------------ ``tomaxint`` removed Use ``integers(0, np.iinfo(np.int_).max,`` - ``endpoint=False)`` + ``endpoint=False)`` ------------------- -------------- ------------ -``seed`` removed Use `~.SeedSequence.spawn` +``seed`` removed Use `SeedSequence.spawn` =================== ============== ============ -See `new-or-different` for more information - -.. code-block:: python - - # As replacement for RandomState(); default_rng() instantiates Generator with - # the default PCG64 BitGenerator. - from numpy.random import default_rng - rg = default_rng() - rg.standard_normal() - rg.bit_generator +See :ref:`new-or-different` for more information Something like the following code can be used to support both ``RandomState`` and ``Generator``, with the understanding that the interfaces are slightly @@ -87,9 +85,9 @@ different a = rg_integers(1000) Seeds can be passed to any of the BitGenerators. The provided value is mixed -via `~.SeedSequence` to spread a possible sequence of seeds across a wider -range of initialization states for the BitGenerator. Here `~.PCG64` is used and -is wrapped with a `~.Generator`. +via `SeedSequence` to spread a possible sequence of seeds across a wider +range of initialization states for the BitGenerator. Here `PCG64` is used and +is wrapped with a `Generator`. .. code-block:: python @@ -100,7 +98,7 @@ is wrapped with a `~.Generator`. Introduction ------------ The new infrastructure takes a different approach to producing random numbers -from the `~.RandomState` object. Random number generation is separated into +from the `RandomState` object. Random number generation is separated into two components, a bit generator and a random generator. The `BitGenerator` has a limited set of responsibilities. It manages state @@ -113,8 +111,8 @@ distributions, e.g., simulated normal random values. This structure allows alternative bit generators to be used with little code duplication. The `Generator` is the user-facing object that is nearly identical to -`.RandomState`. The canonical method to initialize a generator passes a -`~.PCG64` bit generator as the sole argument. +`RandomState`. The canonical method to initialize a generator passes a +`PCG64` bit generator as the sole argument. .. code-block:: python @@ -139,9 +137,9 @@ What's New or Different The Box-Muller method used to produce NumPy's normals is no longer available in `Generator`. It is not possible to reproduce the exact random values using Generator for the normal distribution or any other - distribution that relies on the normal such as the `.RandomState.gamma` or - `.RandomState.standard_t`. If you require bitwise backward compatible - streams, use `.RandomState`. + distribution that relies on the normal such as the `RandomState.gamma` or + `RandomState.standard_t`. If you require bitwise backward compatible + streams, use `RandomState`. * The Generator's normal, exponential and gamma functions use 256-step Ziggurat methods which are 2-10 times faster than NumPy's Box-Muller or inverse CDF @@ -152,20 +150,20 @@ What's New or Different * Optional ``out`` argument that allows existing arrays to be filled for select distributions * All BitGenerators can produce doubles, uint64s and uint32s via CTypes - (`~.PCG64.ctypes`) and CFFI (`~.PCG64.cffi`). This allows the bit generators + (`PCG64.ctypes`) and CFFI (`PCG64.cffi`). This allows the bit generators to be used in numba. * The bit generators can be used in downstream projects via :ref:`Cython `. -* `~.Generator.integers` is now the canonical way to generate integer +* `Generator.integers` is now the canonical way to generate integer random numbers from a discrete uniform distribution. The ``rand`` and - ``randn`` methods are only available through the legacy `~.RandomState`. + ``randn`` methods are only available through the legacy `RandomState`. The ``endpoint`` keyword can be used to specify open or closed intervals. This replaces both ``randint`` and the deprecated ``random_integers``. -* `~.Generator.random` is now the canonical way to generate floating-point - random numbers, which replaces `.RandomState.random_sample`, - `.RandomState.sample`, and `.RandomState.ranf`. This is consistent with +* `Generator.random` is now the canonical way to generate floating-point + random numbers, which replaces `RandomState.random_sample`, + `RandomState.sample`, and `RandomState.ranf`. This is consistent with Python's `random.random`. -* All BitGenerators in numpy use `~SeedSequence` to convert seeds into +* All BitGenerators in numpy use `SeedSequence` to convert seeds into initialized states. See :ref:`new-or-different` for a complete list of improvements and @@ -202,8 +200,9 @@ Features c-api Examples of using Numba, Cython, CFFI -Original Source -~~~~~~~~~~~~~~~ +Original Source of the Generator and BitGenerators +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This package was developed independently of NumPy and was integrated in version 1.17.0. The original repo is at https://github.com/bashtage/randomgen. + diff --git a/doc/source/reference/random/legacy.rst b/doc/source/reference/random/legacy.rst index 413a42727317..9118fc052476 100644 --- a/doc/source/reference/random/legacy.rst +++ b/doc/source/reference/random/legacy.rst @@ -121,3 +121,63 @@ Distributions ~RandomState.wald ~RandomState.weibull ~RandomState.zipf + +Toplevel `numpy.random` functions +================================= +Many of the RandomState methods above are exported as top-level `numpy.random` +functions. These are: + +.. autosummary:: + :toctree: generated/ + + beta + binomial + bytes + chisquare + choice + dirichlet + exponential + f + gamma + geometric + get_state + gumbel + hypergeometric + laplace + logistic + lognormal + logseries + multinomial + multivariate_normal + negative_binomial + noncentral_chisquare + noncentral_f + normal + pareto + permutation + poisson + power + rand + randint + randn + random + random_integers + random_sample + ranf + rayleigh + sample + seed + set_state + shuffle + standard_cauchy + standard_exponential + standard_gamma + standard_normal + standard_t + triangular + uniform + vonmises + wald + weibull + zipf + diff --git a/numpy/random/__init__.pxd b/numpy/random/__init__.pxd new file mode 100644 index 000000000000..05e073876673 --- /dev/null +++ b/numpy/random/__init__.pxd @@ -0,0 +1,14 @@ +cimport numpy as np +from libc.stdint cimport uint32_t, uint64_t + +cdef extern from "numpy/random/bitgen.h": + struct bitgen: + void *state + uint64_t (*next_uint64)(void *st) nogil + uint32_t (*next_uint32)(void *st) nogil + double (*next_double)(void *st) nogil + uint64_t (*next_raw)(void *st) nogil + + ctypedef bitgen bitgen_t + +from numpy.random._bit_generator cimport BitGenerator, SeedSequence diff --git a/numpy/random/_bounded_integers.pxd.in b/numpy/random/_bounded_integers.pxd.in index 320d357740c4..5ae5a806715c 100644 --- a/numpy/random/_bounded_integers.pxd.in +++ b/numpy/random/_bounded_integers.pxd.in @@ -4,7 +4,7 @@ import numpy as np cimport numpy as np ctypedef np.npy_bool bool_t -from ._bit_generator cimport bitgen_t +from numpy.random cimport bitgen_t cdef inline uint64_t _gen_mask(uint64_t max_val) nogil: """Mask generator for use in bounded random numbers""" diff --git a/numpy/random/_common.pxd b/numpy/random/_common.pxd index 74bebca839f5..588f613ae687 100644 --- a/numpy/random/_common.pxd +++ b/numpy/random/_common.pxd @@ -5,7 +5,7 @@ from libc.stdint cimport uint32_t, uint64_t, int32_t, int64_t import numpy as np cimport numpy as np -from ._bit_generator cimport bitgen_t +from numpy.random cimport bitgen_t cdef double POISSON_LAM_MAX cdef double LEGACY_POISSON_LAM_MAX diff --git a/numpy/random/_examples/cython/extending.pyx b/numpy/random/_examples/cython/extending.pyx index d12c0b9196b0..7a0dfe078fbb 100644 --- a/numpy/random/_examples/cython/extending.pyx +++ b/numpy/random/_examples/cython/extending.pyx @@ -8,7 +8,7 @@ import numpy as np cimport numpy as np cimport cython -from numpy.random._bit_generator cimport bitgen_t +from numpy.random cimport bitgen_t from numpy.random import PCG64 np.import_array() diff --git a/numpy/random/_examples/cython/extending_distributions.pyx b/numpy/random/_examples/cython/extending_distributions.pyx index 3f342c475da5..1bef506ef4fa 100644 --- a/numpy/random/_examples/cython/extending_distributions.pyx +++ b/numpy/random/_examples/cython/extending_distributions.pyx @@ -8,8 +8,7 @@ cimport numpy as np cimport cython from cpython.pycapsule cimport PyCapsule_IsValid, PyCapsule_GetPointer from libc.stdint cimport uint16_t, uint64_t -from numpy.random._bit_generator cimport bitgen_t - +from numpy.random cimport bitgen_t from numpy.random import PCG64 @@ -72,3 +71,4 @@ def uint10_uniforms(Py_ssize_t n): randoms = np.asarray(random_values) return randoms + diff --git a/numpy/random/_generator.pyx b/numpy/random/_generator.pyx index 2d8455982fbb..64ec7398690b 100644 --- a/numpy/random/_generator.pyx +++ b/numpy/random/_generator.pyx @@ -19,7 +19,7 @@ from ._bounded_integers cimport (_rand_bool, _rand_int32, _rand_int64, _rand_uint8, _gen_mask) from ._bounded_integers import _integers_types from ._pcg64 import PCG64 -from ._bit_generator cimport bitgen_t +from numpy.random cimport bitgen_t from ._common cimport (POISSON_LAM_MAX, CONS_POSITIVE, CONS_NONE, CONS_NON_NEGATIVE, CONS_BOUNDED_0_1, CONS_BOUNDED_GT_0_1, CONS_GT_1, CONS_POSITIVE_NOT_NAN, CONS_POISSON, @@ -1004,6 +1004,12 @@ cdef class Generator: A floating-point array of shape ``size`` of drawn samples, or a single sample if ``size`` was not specified. + See Also + -------- + normal : + Equivalent function with additional ``loc`` and ``scale`` arguments + for setting the mean and standard deviation. + Notes ----- For random samples from :math:`N(\\mu, \\sigma^2)`, use one of:: @@ -1011,12 +1017,6 @@ cdef class Generator: mu + sigma * gen.standard_normal(size=...) gen.normal(mu, sigma, size=...) - See Also - -------- - normal : - Equivalent function with additional ``loc`` and ``scale`` arguments - for setting the mean and standard deviation. - Examples -------- >>> rng = np.random.default_rng() diff --git a/numpy/random/_mt19937.pyx b/numpy/random/_mt19937.pyx index e99652b73cd0..919a96a4c43e 100644 --- a/numpy/random/_mt19937.pyx +++ b/numpy/random/_mt19937.pyx @@ -4,7 +4,7 @@ import numpy as np cimport numpy as np from libc.stdint cimport uint32_t, uint64_t -from ._bit_generator cimport BitGenerator, SeedSequence +from numpy.random cimport BitGenerator, SeedSequence __all__ = ['MT19937'] diff --git a/numpy/random/_pcg64.pyx b/numpy/random/_pcg64.pyx index 1a5d852a2803..05d27db5c87b 100644 --- a/numpy/random/_pcg64.pyx +++ b/numpy/random/_pcg64.pyx @@ -3,7 +3,7 @@ cimport numpy as np from libc.stdint cimport uint32_t, uint64_t from ._common cimport uint64_to_double, wrap_int -from ._bit_generator cimport BitGenerator +from numpy.random cimport BitGenerator __all__ = ['PCG64'] diff --git a/numpy/random/_philox.pyx b/numpy/random/_philox.pyx index 9f136c32f743..7e88804904a6 100644 --- a/numpy/random/_philox.pyx +++ b/numpy/random/_philox.pyx @@ -10,7 +10,7 @@ cimport numpy as np from libc.stdint cimport uint32_t, uint64_t from ._common cimport uint64_to_double, int_to_array, wrap_int -from ._bit_generator cimport BitGenerator +from numpy.random cimport BitGenerator __all__ = ['Philox'] diff --git a/numpy/random/_sfc64.pyx b/numpy/random/_sfc64.pyx index 1633669d5e5c..1daee34f8635 100644 --- a/numpy/random/_sfc64.pyx +++ b/numpy/random/_sfc64.pyx @@ -3,7 +3,7 @@ cimport numpy as np from libc.stdint cimport uint32_t, uint64_t from ._common cimport uint64_to_double -from ._bit_generator cimport BitGenerator +from numpy.random cimport BitGenerator __all__ = ['SFC64'] diff --git a/numpy/random/mtrand.pyx b/numpy/random/mtrand.pyx index 691a6e6e700f..e6cd9b87ed30 100644 --- a/numpy/random/mtrand.pyx +++ b/numpy/random/mtrand.pyx @@ -17,7 +17,7 @@ from ._bounded_integers cimport (_rand_bool, _rand_int32, _rand_int64, _rand_uint8,) from ._bounded_integers import _integers_types from ._mt19937 import MT19937 as _MT19937 -from ._bit_generator cimport bitgen_t +from numpy.random cimport bitgen_t from ._common cimport (POISSON_LAM_MAX, CONS_POSITIVE, CONS_NONE, CONS_NON_NEGATIVE, CONS_BOUNDED_0_1, CONS_BOUNDED_GT_0_1, CONS_GTE_1, CONS_GT_1, LEGACY_CONS_POISSON, @@ -379,6 +379,10 @@ cdef class RandomState: (b - a) * random_sample() + a + .. note:: + New code should use ``default_rng().random`` (see + `random-quick-start`) instead. + Parameters ---------- size : int or tuple of ints, optional @@ -392,6 +396,10 @@ cdef class RandomState: Array of random floats of shape `size` (unless ``size=None``, in which case a single float is returned). + See also + -------- + Generator.random: which should be used for new code. + Examples -------- >>> np.random.random_sample() @@ -441,6 +449,10 @@ cdef class RandomState: It is often seen in Bayesian inference and order statistics. + .. note:: + New code should use ``default_rng().beta`` (see + `random-quick-start`) instead. + Parameters ---------- a : float or array_like of floats @@ -458,6 +470,9 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized beta distribution. + See also + -------- + Generator.beta: which should be used for new code. """ return cont(&legacy_beta, &self._aug_state, size, self.lock, 2, a, 'a', CONS_POSITIVE, @@ -484,6 +499,10 @@ cdef class RandomState: the size of raindrops measured over many rainstorms [1]_, or the time between page requests to Wikipedia [2]_. + .. note:: + New code should use ``default_rng().exponential`` (see + `random-quick-start`) instead. + Parameters ---------- scale : float or array_like of floats @@ -500,6 +519,10 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized exponential distribution. + See also + -------- + Generator.exponential: which should be used for new code. + References ---------- .. [1] Peyton Z. Peebles Jr., "Probability, Random Variables and @@ -525,6 +548,10 @@ cdef class RandomState: `standard_exponential` is identical to the exponential distribution with a scale parameter of 1. + .. note:: + New code should use ``default_rng().standard_exponential`` (see + `random-quick-start`) instead. + Parameters ---------- size : int or tuple of ints, optional @@ -537,6 +564,10 @@ cdef class RandomState: out : float or ndarray Drawn samples. + See also + -------- + Generator.standard_exponential: which should be used for new code. + Examples -------- Output a 3x8000 array: @@ -618,6 +649,10 @@ cdef class RandomState: the specified dtype in the "half-open" interval [`low`, `high`). If `high` is None (the default), then results are from [0, `low`). + .. note:: + New code should use ``default_rng().integers`` (see + `random-quick-start`) instead. + Parameters ---------- low : int or array-like of ints @@ -651,6 +686,7 @@ cdef class RandomState: random_integers : similar to `randint`, only for the closed interval [`low`, `high`], and 1 is the lowest value if `high` is omitted. + Generator.integers: which should be used for new code. Examples -------- @@ -735,6 +771,10 @@ cdef class RandomState: Return random bytes. + .. note:: + New code should use ``default_rng().bytes`` (see + `random-quick-start`) instead. + Parameters ---------- length : int @@ -745,11 +785,14 @@ cdef class RandomState: out : str String of length `length`. + See also + -------- + Generator.bytes: which should be used for new code. + Examples -------- >>> np.random.bytes(10) ' eh\\x85\\x022SZ\\xbf\\xa4' #random - """ cdef Py_ssize_t n_uint32 = ((length - 1) // 4 + 1) # Interpret the uint32s as little-endian to convert them to bytes @@ -766,6 +809,10 @@ cdef class RandomState: .. versionadded:: 1.7.0 + .. note:: + New code should use ``default_rng().choice`` (see + `random-quick-start`) instead. + Parameters ---------- a : 1-D array-like or int @@ -799,6 +846,7 @@ cdef class RandomState: See Also -------- randint, shuffle, permutation + Generator.choice: which should be used in new code Examples -------- @@ -958,6 +1006,10 @@ cdef class RandomState: any value within the given interval is equally likely to be drawn by `uniform`. + .. note:: + New code should use ``default_rng().uniform`` (see + `random-quick-start`) instead. + Parameters ---------- low : float or array_like of floats, optional @@ -987,6 +1039,7 @@ cdef class RandomState: rand : Convenience function that accepts dimensions as input, e.g., ``rand(2,2)`` would generate a 2-by-2 array of floats, uniformly distributed over ``[0, 1)``. + Generator.uniform: which should be used for new code. Notes ----- @@ -1114,6 +1167,10 @@ cdef class RandomState: tuple to specify the size of the output, which is consistent with other NumPy functions like `numpy.zeros` and `numpy.ones`. + .. note:: + New code should use ``default_rng().standard_normal`` (see + `random-quick-start`) 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) @@ -1137,6 +1194,7 @@ cdef class RandomState: -------- standard_normal : Similar, but takes a tuple as its argument. normal : Also accepts mu and sigma arguments. + Generator.standard_normal: which should be used for new code. Notes ----- @@ -1263,6 +1321,10 @@ cdef class RandomState: Draw samples from a standard Normal distribution (mean=0, stdev=1). + .. note:: + New code should use ``default_rng().standard_normal`` (see + `random-quick-start`) instead. + Parameters ---------- size : int or tuple of ints, optional @@ -1276,6 +1338,13 @@ cdef class RandomState: A floating-point array of shape ``size`` of drawn samples, or a single sample if ``size`` was not specified. + See Also + -------- + normal : + Equivalent function with additional ``loc`` and ``scale`` arguments + for setting the mean and standard deviation. + Generator.standard_normal: which should be used for new code. + Notes ----- For random samples from :math:`N(\\mu, \\sigma^2)`, use one of:: @@ -1283,12 +1352,6 @@ cdef class RandomState: 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() @@ -1333,6 +1396,10 @@ cdef class RandomState: by a large number of tiny, random disturbances, each with its own unique distribution [2]_. + .. note:: + New code should use ``default_rng().normal`` (see + `random-quick-start`) instead. + Parameters ---------- loc : float or array_like of floats @@ -1355,6 +1422,7 @@ cdef class RandomState: -------- scipy.stats.norm : probability density function, distribution or cumulative density function, etc. + Generator.normal: which should be used for new code. Notes ----- @@ -1428,6 +1496,10 @@ cdef class RandomState: Samples are drawn from a Gamma distribution with specified parameters, shape (sometimes designated "k") and scale=1. + .. note:: + New code should use ``default_rng().standard_gamma`` (see + `random-quick-start`) instead. + Parameters ---------- shape : float or array_like of floats @@ -1447,6 +1519,7 @@ cdef class RandomState: -------- scipy.stats.gamma : probability density function, distribution or cumulative density function, etc. + Generator.standard_gamma: which should be used for new code. Notes ----- @@ -1504,6 +1577,10 @@ cdef class RandomState: `shape` (sometimes designated "k") and `scale` (sometimes designated "theta"), where both parameters are > 0. + .. note:: + New code should use ``default_rng().gamma`` (see + `random-quick-start`) instead. + Parameters ---------- shape : float or array_like of floats @@ -1526,6 +1603,7 @@ cdef class RandomState: -------- scipy.stats.gamma : probability density function, distribution or cumulative density function, etc. + Generator.gamma: which should be used for new code. Notes ----- @@ -1588,6 +1666,10 @@ cdef class RandomState: that arises in ANOVA tests, and is the ratio of two chi-square variates. + .. note:: + New code should use ``default_rng().f`` (see + `random-quick-start`) instead. + Parameters ---------- dfnum : float or array_like of floats @@ -1609,6 +1691,7 @@ cdef class RandomState: -------- scipy.stats.f : probability density function, distribution or cumulative density function, etc. + Generator.f: which should be used for new code. Notes ----- @@ -1671,6 +1754,10 @@ cdef class RandomState: freedom in denominator), where both parameters > 1. `nonc` is the non-centrality parameter. + .. note:: + New code should use ``default_rng().noncentral_f`` (see + `random-quick-start`) instead. + Parameters ---------- dfnum : float or array_like of floats @@ -1695,6 +1782,10 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized noncentral Fisher distribution. + See also + -------- + Generator.noncentral_f: which should be used for new code. + Notes ----- When calculating the power of an experiment (power = probability of @@ -1748,6 +1839,10 @@ cdef class RandomState: resulting distribution is chi-square (see Notes). This distribution is often used in hypothesis testing. + .. note:: + New code should use ``default_rng().chisquare`` (see + `random-quick-start`) instead. + Parameters ---------- df : float or array_like of floats @@ -1769,6 +1864,10 @@ cdef class RandomState: When `df` <= 0 or when an inappropriate `size` (e.g. ``size=-1``) is given. + See also + -------- + Generator.chisquare: which should be used for new code. + Notes ----- The variable obtained by summing the squares of `df` independent, @@ -1798,7 +1897,6 @@ cdef class RandomState: -------- >>> np.random.chisquare(2,4) array([ 1.89920014, 9.00867716, 3.13710533, 5.62318272]) # random - """ return cont(&legacy_chisquare, &self._aug_state, size, self.lock, 1, df, 'df', CONS_POSITIVE, @@ -1814,6 +1912,10 @@ cdef class RandomState: The noncentral :math:`\\chi^2` distribution is a generalization of the :math:`\\chi^2` distribution. + .. note:: + New code should use ``default_rng().noncentral_chisquare`` (see + `random-quick-start`) instead. + Parameters ---------- df : float or array_like of floats @@ -1834,6 +1936,10 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized noncentral chi-square distribution. + See also + -------- + Generator.noncentral_chisquare: which should be used for new code. + Notes ----- The probability density function for the noncentral Chi-square @@ -1892,6 +1998,10 @@ cdef class RandomState: Also known as the Lorentz distribution. + .. note:: + New code should use ``default_rng().standard_cauchy`` (see + `random-quick-start`) instead. + Parameters ---------- size : int or tuple of ints, optional @@ -1904,6 +2014,10 @@ cdef class RandomState: samples : ndarray or scalar The drawn samples. + See also + -------- + Generator.standard_cauchy: which should be used for new code. + Notes ----- The probability density function for the full Cauchy distribution is @@ -1960,6 +2074,10 @@ cdef class RandomState: large, the result resembles that of the standard normal distribution (`standard_normal`). + .. note:: + New code should use ``default_rng().standard_t`` (see + `random-quick-start`) instead. + Parameters ---------- df : float or array_like of floats @@ -1975,6 +2093,10 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized standard Student's t distribution. + See also + -------- + Generator.standard_t: which should be used for new code. + Notes ----- The probability density function for the t distribution is @@ -2057,6 +2179,10 @@ cdef class RandomState: circle. It may be thought of as the circular analogue of the normal distribution. + .. note:: + New code should use ``default_rng().vonmises`` (see + `random-quick-start`) instead. + Parameters ---------- mu : float or array_like of floats @@ -2078,6 +2204,7 @@ cdef class RandomState: -------- scipy.stats.vonmises : probability density function, distribution, or cumulative density function, etc. + Generator.vonmises: which should be used for new code. Notes ----- @@ -2150,6 +2277,10 @@ cdef class RandomState: 20 percent of the range, while the other 20 percent fill the remaining 80 percent of the range. + .. note:: + New code should use ``default_rng().pareto`` (see + `random-quick-start`) instead. + Parameters ---------- a : float or array_like of floats @@ -2171,6 +2302,7 @@ cdef class RandomState: cumulative density function, etc. scipy.stats.genpareto : probability density function, distribution or cumulative density function, etc. + Generator.pareto: which should be used for new code. Notes ----- @@ -2239,6 +2371,10 @@ cdef class RandomState: The more common 2-parameter Weibull, including a scale parameter :math:`\\lambda` is just :math:`X = \\lambda(-ln(U))^{1/a}`. + .. note:: + New code should use ``default_rng().weibull`` (see + `random-quick-start`) instead. + Parameters ---------- a : float or array_like of floats @@ -2260,6 +2396,7 @@ cdef class RandomState: scipy.stats.weibull_min scipy.stats.genextreme gumbel + Generator.weibull: which should be used for new code. Notes ----- @@ -2330,6 +2467,10 @@ cdef class RandomState: Also known as the power function distribution. + .. note:: + New code should use ``default_rng().power`` (see + `random-quick-start`) instead. + Parameters ---------- a : float or array_like of floats @@ -2350,6 +2491,10 @@ cdef class RandomState: ValueError If a < 1. + See also + -------- + Generator.power: which should be used for new code. + Notes ----- The probability density function is @@ -2433,6 +2578,10 @@ cdef class RandomState: difference between two independent, identically distributed exponential random variables. + .. note:: + New code should use ``default_rng().laplace`` (see + `random-quick-start`) instead. + Parameters ---------- loc : float or array_like of floats, optional @@ -2451,6 +2600,10 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized Laplace distribution. + See also + -------- + Generator.laplace: which should be used for new code. + Notes ----- It has the probability density function @@ -2516,6 +2669,10 @@ cdef class RandomState: scale. For more information on the Gumbel distribution, see Notes and References below. + .. note:: + New code should use ``default_rng().gumbel`` (see + `random-quick-start`) instead. + Parameters ---------- loc : float or array_like of floats, optional @@ -2540,6 +2697,7 @@ cdef class RandomState: scipy.stats.gumbel_r scipy.stats.genextreme weibull + Generator.gumbel: which should be used for new code. Notes ----- @@ -2633,6 +2791,10 @@ cdef class RandomState: Samples are drawn from a logistic distribution with specified parameters, loc (location or mean, also median), and scale (>0). + .. note:: + New code should use ``default_rng().logistic`` (see + `random-quick-start`) instead. + Parameters ---------- loc : float or array_like of floats, optional @@ -2655,6 +2817,7 @@ cdef class RandomState: -------- scipy.stats.logistic : probability density function, distribution or cumulative density function, etc. + Generator.logistic: which should be used for new code. Notes ----- @@ -2715,6 +2878,10 @@ cdef class RandomState: deviation are not the values for the distribution itself, but of the underlying normal distribution it is derived from. + .. note:: + New code should use ``default_rng().lognormal`` (see + `random-quick-start`) instead. + Parameters ---------- mean : float or array_like of floats, optional @@ -2737,6 +2904,7 @@ cdef class RandomState: -------- scipy.stats.lognorm : probability density function, distribution, cumulative density function, etc. + Generator.lognormal: which should be used for new code. Notes ----- @@ -2823,6 +2991,10 @@ cdef class RandomState: The :math:`\\chi` and Weibull distributions are generalizations of the Rayleigh. + .. note:: + New code should use ``default_rng().rayleigh`` (see + `random-quick-start`) instead. + Parameters ---------- scale : float or array_like of floats, optional @@ -2838,6 +3010,10 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized Rayleigh distribution. + See also + -------- + Generator.rayleigh: which should be used for new code. + Notes ----- The probability density function for the Rayleigh distribution is @@ -2897,6 +3073,10 @@ cdef class RandomState: because there is an inverse relationship between the time to cover a unit distance and distance covered in unit time. + .. note:: + New code should use ``default_rng().wald`` (see + `random-quick-start`) instead. + Parameters ---------- mean : float or array_like of floats @@ -2914,6 +3094,10 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized Wald distribution. + See also + -------- + Generator.wald: which should be used for new code. + Notes ----- The probability density function for the Wald distribution is @@ -2962,6 +3146,10 @@ cdef class RandomState: limit right. Unlike the other distributions, these parameters directly define the shape of the pdf. + .. note:: + New code should use ``default_rng().triangular`` (see + `random-quick-start`) instead. + Parameters ---------- left : float or array_like of floats @@ -2983,6 +3171,10 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized triangular distribution. + See also + -------- + Generator.triangular: which should be used for new code. + Notes ----- The probability density function for the triangular distribution is @@ -3061,6 +3253,10 @@ cdef class RandomState: n an integer >= 0 and p is in the interval [0,1]. (n may be input as a float, but it is truncated to an integer in use) + .. note:: + New code should use ``default_rng().binomial`` (see + `random-quick-start`) instead. + Parameters ---------- n : int or array_like of ints @@ -3084,6 +3280,7 @@ cdef class RandomState: -------- scipy.stats.binom : probability density function, distribution or cumulative density function, etc. + Generator.binomial: which should be used for new code. Notes ----- @@ -3206,6 +3403,10 @@ cdef class RandomState: parameters, `n` successes and `p` probability of success where `n` is > 0 and `p` is in the interval [0, 1]. + .. note:: + New code should use ``default_rng().negative_binomial`` (see + `random-quick-start`) instead. + Parameters ---------- n : float or array_like of floats @@ -3225,6 +3426,10 @@ cdef class RandomState: where each sample is equal to N, the number of failures that occurred before a total of n successes was reached. + See also + -------- + Generator.negative_binomial: which should be used for new code. + Notes ----- The probability mass function of the negative binomial distribution is @@ -3283,6 +3488,10 @@ cdef class RandomState: The Poisson distribution is the limit of the binomial distribution for large N. + .. note:: + New code should use ``default_rng().poisson`` (see + `random-quick-start`) instead. + Parameters ---------- lam : float or array_like of floats @@ -3299,6 +3508,10 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized Poisson distribution. + See also + -------- + Generator.poisson: which should be used for new code. + Notes ----- The Poisson distribution @@ -3361,6 +3574,10 @@ cdef class RandomState: frequency of an item is inversely proportional to its rank in a frequency table. + .. note:: + New code should use ``default_rng().zipf`` (see + `random-quick-start`) instead. + Parameters ---------- a : float or array_like of floats @@ -3380,6 +3597,7 @@ cdef class RandomState: -------- scipy.stats.zipf : probability density function, distribution, or cumulative density function, etc. + Generator.zipf: which should be used for new code. Notes ----- @@ -3446,6 +3664,10 @@ cdef class RandomState: where `p` is the probability of success of an individual trial. + .. note:: + New code should use ``default_rng().geometric`` (see + `random-quick-start`) instead. + Parameters ---------- p : float or array_like of floats @@ -3461,6 +3683,10 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized geometric distribution. + See also + -------- + Generator.geometric: which should be used for new code. + Examples -------- Draw ten thousand values from the geometric distribution, @@ -3492,6 +3718,10 @@ cdef class RandomState: a bad selection), and `nsample` (number of items sampled, which is less than or equal to the sum ``ngood + nbad``). + .. note:: + New code should use ``default_rng().hypergeometric`` (see + `random-quick-start`) instead. + Parameters ---------- ngood : int or array_like of ints @@ -3519,6 +3749,7 @@ cdef class RandomState: -------- scipy.stats.hypergeom : probability density function, distribution or cumulative density function, etc. + Generator.hypergeometric: which should be used for new code. Notes ----- @@ -3618,6 +3849,10 @@ cdef class RandomState: Samples are drawn from a log series distribution with specified shape parameter, 0 < ``p`` < 1. + .. note:: + New code should use ``default_rng().logseries`` (see + `random-quick-start`) instead. + Parameters ---------- p : float or array_like of floats @@ -3637,6 +3872,7 @@ cdef class RandomState: -------- scipy.stats.logser : probability density function, distribution or cumulative density function, etc. + Generator.logseries: which should be used for new code. Notes ----- @@ -3706,6 +3942,10 @@ cdef class RandomState: (average or "center") and variance (standard deviation, or "width," squared) of the one-dimensional normal distribution. + .. note:: + New code should use ``default_rng().multivariate_normal`` (see + `random-quick-start`) instead. + Parameters ---------- mean : 1-D array_like, of length N @@ -3733,6 +3973,10 @@ cdef class RandomState: In other words, each entry ``out[i,j,...,:]`` is an N-dimensional value drawn from the distribution. + See also + -------- + Generator.multivariate_normal: which should be used for new code. + Notes ----- The mean is a coordinate in N-dimensional space, which represents the @@ -3872,6 +4116,10 @@ cdef class RandomState: ``X_i = [X_0, X_1, ..., X_p]``, represent the number of times the outcome was ``i``. + .. note:: + New code should use ``default_rng().multinomial`` (see + `random-quick-start`) instead. + Parameters ---------- n : int @@ -3895,6 +4143,10 @@ cdef class RandomState: In other words, each entry ``out[i,j,...,:]`` is an N-dimensional value drawn from the distribution. + See also + -------- + Generator.multinomial: which should be used for new code. + Examples -------- Throw a dice 20 times: @@ -3982,6 +4234,10 @@ cdef class RandomState: is a conjugate prior of a multinomial distribution in Bayesian inference. + .. note:: + New code should use ``default_rng().dirichlet`` (see + `random-quick-start`) instead. + Parameters ---------- alpha : array @@ -4002,6 +4258,10 @@ cdef class RandomState: ValueError If any value in alpha is less than or equal to zero + See also + -------- + Generator.dirichlet: which should be used for new code. + Notes ----- The Dirichlet distribution is a distribution over vectors @@ -4119,6 +4379,10 @@ cdef class RandomState: multi-dimensional array. The order of sub-arrays is changed but their contents remains the same. + .. note:: + New code should use ``default_rng().shuffle`` (see + `random-quick-start`) instead. + Parameters ---------- x : array_like @@ -4128,6 +4392,10 @@ cdef class RandomState: ------- None + See also + -------- + Generator.shuffle: which should be used for new code. + Examples -------- >>> arr = np.arange(10) @@ -4206,6 +4474,10 @@ cdef class RandomState: If `x` is a multi-dimensional array, it is only shuffled along its first index. + .. note:: + New code should use ``default_rng().permutation`` (see + `random-quick-start`) instead. + Parameters ---------- x : int or array_like @@ -4218,6 +4490,9 @@ cdef class RandomState: out : ndarray Permuted sequence or array range. + See also + -------- + Generator.permutation: which should be used for new code. Examples -------- diff --git a/numpy/random/setup.py b/numpy/random/setup.py index 776a018bcd92..64e1b5b92d70 100644 --- a/numpy/random/setup.py +++ b/numpy/random/setup.py @@ -125,6 +125,7 @@ def generate_libraries(ext, build_dir): depends=['mtrand.pyx'], define_macros=defs + LEGACY_DEFS, ) + config.add_data_files('__init__.pxd') return config From 5a52be5d12773327f950fd67ad9268dd6ff17320 Mon Sep 17 00:00:00 2001 From: mattip Date: Wed, 20 Nov 2019 22:25:59 -0800 Subject: [PATCH 2/4] MAINT: "See also" -> "See Also" --- numpy/random/mtrand.pyx | 46 ++++++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/numpy/random/mtrand.pyx b/numpy/random/mtrand.pyx index e6cd9b87ed30..928969376857 100644 --- a/numpy/random/mtrand.pyx +++ b/numpy/random/mtrand.pyx @@ -396,7 +396,7 @@ cdef class RandomState: Array of random floats of shape `size` (unless ``size=None``, in which case a single float is returned). - See also + See Also -------- Generator.random: which should be used for new code. @@ -470,7 +470,7 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized beta distribution. - See also + See Also -------- Generator.beta: which should be used for new code. """ @@ -519,7 +519,7 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized exponential distribution. - See also + See Also -------- Generator.exponential: which should be used for new code. @@ -564,7 +564,7 @@ cdef class RandomState: out : float or ndarray Drawn samples. - See also + See Also -------- Generator.standard_exponential: which should be used for new code. @@ -785,7 +785,7 @@ cdef class RandomState: out : str String of length `length`. - See also + See Also -------- Generator.bytes: which should be used for new code. @@ -1782,7 +1782,7 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized noncentral Fisher distribution. - See also + See Also -------- Generator.noncentral_f: which should be used for new code. @@ -1864,7 +1864,7 @@ cdef class RandomState: When `df` <= 0 or when an inappropriate `size` (e.g. ``size=-1``) is given. - See also + See Also -------- Generator.chisquare: which should be used for new code. @@ -1936,7 +1936,7 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized noncentral chi-square distribution. - See also + See Also -------- Generator.noncentral_chisquare: which should be used for new code. @@ -2014,7 +2014,7 @@ cdef class RandomState: samples : ndarray or scalar The drawn samples. - See also + See Also -------- Generator.standard_cauchy: which should be used for new code. @@ -2093,7 +2093,7 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized standard Student's t distribution. - See also + See Also -------- Generator.standard_t: which should be used for new code. @@ -2491,7 +2491,7 @@ cdef class RandomState: ValueError If a < 1. - See also + See Also -------- Generator.power: which should be used for new code. @@ -2600,7 +2600,7 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized Laplace distribution. - See also + See Also -------- Generator.laplace: which should be used for new code. @@ -3010,7 +3010,7 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized Rayleigh distribution. - See also + See Also -------- Generator.rayleigh: which should be used for new code. @@ -3094,7 +3094,7 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized Wald distribution. - See also + See Also -------- Generator.wald: which should be used for new code. @@ -3171,7 +3171,7 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized triangular distribution. - See also + See Also -------- Generator.triangular: which should be used for new code. @@ -3426,7 +3426,7 @@ cdef class RandomState: where each sample is equal to N, the number of failures that occurred before a total of n successes was reached. - See also + See Also -------- Generator.negative_binomial: which should be used for new code. @@ -3508,7 +3508,7 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized Poisson distribution. - See also + See Also -------- Generator.poisson: which should be used for new code. @@ -3683,7 +3683,7 @@ cdef class RandomState: out : ndarray or scalar Drawn samples from the parameterized geometric distribution. - See also + See Also -------- Generator.geometric: which should be used for new code. @@ -3973,7 +3973,7 @@ cdef class RandomState: In other words, each entry ``out[i,j,...,:]`` is an N-dimensional value drawn from the distribution. - See also + See Also -------- Generator.multivariate_normal: which should be used for new code. @@ -4143,7 +4143,7 @@ cdef class RandomState: In other words, each entry ``out[i,j,...,:]`` is an N-dimensional value drawn from the distribution. - See also + See Also -------- Generator.multinomial: which should be used for new code. @@ -4258,7 +4258,7 @@ cdef class RandomState: ValueError If any value in alpha is less than or equal to zero - See also + See Also -------- Generator.dirichlet: which should be used for new code. @@ -4392,7 +4392,7 @@ cdef class RandomState: ------- None - See also + See Also -------- Generator.shuffle: which should be used for new code. @@ -4490,7 +4490,7 @@ cdef class RandomState: out : ndarray Permuted sequence or array range. - See also + See Also -------- Generator.permutation: which should be used for new code. From a413620ed8c13efc1f513859e3140ad6922d67d0 Mon Sep 17 00:00:00 2001 From: mattip Date: Thu, 21 Nov 2019 08:31:05 -0800 Subject: [PATCH 3/4] DOC: fixes from review --- doc/source/reference/random/index.rst | 9 ++++++--- doc/source/reference/random/legacy.rst | 16 ++++++++++++---- 2 files changed, 18 insertions(+), 7 deletions(-) diff --git a/doc/source/reference/random/index.rst b/doc/source/reference/random/index.rst index 48d7a48199e1..bda9c4d96112 100644 --- a/doc/source/reference/random/index.rst +++ b/doc/source/reference/random/index.rst @@ -41,13 +41,16 @@ properties than the legacy `MT19937` used in `RandomState`. .. code-block:: python - #Do this + # Do this from numpy.random import default_rng - val = default_rng().standard_normal() + rng = default_rng() + vals = rng.standard_normal(10) + more_vals = rng.standard_normal(10) # instead of this from numpy import random - val = random.standard_normal() + vals = random.standard_normal(10) + more_vals = random.standard_normal(10) `Generator` can be used as a replacement for `RandomState`. Both class instances hold a internal `BitGenerator` instance to provide the bit diff --git a/doc/source/reference/random/legacy.rst b/doc/source/reference/random/legacy.rst index 9118fc052476..922d76a9ae8a 100644 --- a/doc/source/reference/random/legacy.rst +++ b/doc/source/reference/random/legacy.rst @@ -122,10 +122,18 @@ Distributions ~RandomState.weibull ~RandomState.zipf -Toplevel `numpy.random` functions -================================= -Many of the RandomState methods above are exported as top-level `numpy.random` -functions. These are: +Functions in `numpy.random` +=========================== +Many of the RandomState methods above are exported as functions in +`numpy.random` This usage is discouraged, as it is implemented via a gloabl +`RandomState` instance which is not advised on two counts: + +- It uses global state, which means results will change as the code changes + +- It uses a `RandomState` rather than the more modern `Generator`. + +For backward compatible legacy reasons, we cannot change this. See +`random-quick-start`. .. autosummary:: :toctree: generated/ From 0a5e42873095af920a5ba1df59cf156ddb5d03f4 Mon Sep 17 00:00:00 2001 From: mattip Date: Thu, 21 Nov 2019 13:13:16 -0800 Subject: [PATCH 4/4] DOC: update note from review --- numpy/random/mtrand.pyx | 168 ++++++++++++++++++++-------------------- 1 file changed, 84 insertions(+), 84 deletions(-) diff --git a/numpy/random/mtrand.pyx b/numpy/random/mtrand.pyx index 928969376857..a4d409f37ca4 100644 --- a/numpy/random/mtrand.pyx +++ b/numpy/random/mtrand.pyx @@ -380,8 +380,8 @@ cdef class RandomState: (b - a) * random_sample() + a .. note:: - New code should use ``default_rng().random`` (see - `random-quick-start`) instead. + New code should use the ``random`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -450,8 +450,8 @@ cdef class RandomState: It is often seen in Bayesian inference and order statistics. .. note:: - New code should use ``default_rng().beta`` (see - `random-quick-start`) instead. + New code should use the ``beta`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -500,8 +500,8 @@ cdef class RandomState: between page requests to Wikipedia [2]_. .. note:: - New code should use ``default_rng().exponential`` (see - `random-quick-start`) instead. + New code should use the ``exponential`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -549,8 +549,8 @@ cdef class RandomState: with a scale parameter of 1. .. note:: - New code should use ``default_rng().standard_exponential`` (see - `random-quick-start`) instead. + New code should use the ``standard_exponential`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -650,8 +650,8 @@ cdef class RandomState: `high` is None (the default), then results are from [0, `low`). .. note:: - New code should use ``default_rng().integers`` (see - `random-quick-start`) instead. + New code should use the ``integers`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -772,8 +772,8 @@ cdef class RandomState: Return random bytes. .. note:: - New code should use ``default_rng().bytes`` (see - `random-quick-start`) instead. + New code should use the ``bytes`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -810,8 +810,8 @@ cdef class RandomState: .. versionadded:: 1.7.0 .. note:: - New code should use ``default_rng().choice`` (see - `random-quick-start`) instead. + New code should use the ``choice`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -1007,8 +1007,8 @@ cdef class RandomState: by `uniform`. .. note:: - New code should use ``default_rng().uniform`` (see - `random-quick-start`) instead. + New code should use the ``uniform`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -1168,8 +1168,8 @@ cdef class RandomState: other NumPy functions like `numpy.zeros` and `numpy.ones`. .. note:: - New code should use ``default_rng().standard_normal`` (see - `random-quick-start`) instead. + New code should use the ``standard_normal`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. If positive int_like arguments are provided, `randn` generates an array of shape ``(d0, d1, ..., dn)``, filled @@ -1322,8 +1322,8 @@ cdef class RandomState: Draw samples from a standard Normal distribution (mean=0, stdev=1). .. note:: - New code should use ``default_rng().standard_normal`` (see - `random-quick-start`) instead. + New code should use the ``standard_normal`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -1397,8 +1397,8 @@ cdef class RandomState: unique distribution [2]_. .. note:: - New code should use ``default_rng().normal`` (see - `random-quick-start`) instead. + New code should use the ``normal`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -1497,8 +1497,8 @@ cdef class RandomState: shape (sometimes designated "k") and scale=1. .. note:: - New code should use ``default_rng().standard_gamma`` (see - `random-quick-start`) instead. + New code should use the ``standard_gamma`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -1578,8 +1578,8 @@ cdef class RandomState: "theta"), where both parameters are > 0. .. note:: - New code should use ``default_rng().gamma`` (see - `random-quick-start`) instead. + New code should use the ``gamma`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -1667,8 +1667,8 @@ cdef class RandomState: variates. .. note:: - New code should use ``default_rng().f`` (see - `random-quick-start`) instead. + New code should use the ``f`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -1755,8 +1755,8 @@ cdef class RandomState: `nonc` is the non-centrality parameter. .. note:: - New code should use ``default_rng().noncentral_f`` (see - `random-quick-start`) instead. + New code should use the ``noncentral_f`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -1840,8 +1840,8 @@ cdef class RandomState: is often used in hypothesis testing. .. note:: - New code should use ``default_rng().chisquare`` (see - `random-quick-start`) instead. + New code should use the ``chisquare`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -1913,8 +1913,8 @@ cdef class RandomState: the :math:`\\chi^2` distribution. .. note:: - New code should use ``default_rng().noncentral_chisquare`` (see - `random-quick-start`) instead. + New code should use the ``noncentral_chisquare`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -1999,8 +1999,8 @@ cdef class RandomState: Also known as the Lorentz distribution. .. note:: - New code should use ``default_rng().standard_cauchy`` (see - `random-quick-start`) instead. + New code should use the ``standard_cauchy`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -2075,8 +2075,8 @@ cdef class RandomState: distribution (`standard_normal`). .. note:: - New code should use ``default_rng().standard_t`` (see - `random-quick-start`) instead. + New code should use the ``standard_t`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -2180,8 +2180,8 @@ cdef class RandomState: distribution. .. note:: - New code should use ``default_rng().vonmises`` (see - `random-quick-start`) instead. + New code should use the ``vonmises`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -2278,8 +2278,8 @@ cdef class RandomState: remaining 80 percent of the range. .. note:: - New code should use ``default_rng().pareto`` (see - `random-quick-start`) instead. + New code should use the ``pareto`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -2372,8 +2372,8 @@ cdef class RandomState: :math:`\\lambda` is just :math:`X = \\lambda(-ln(U))^{1/a}`. .. note:: - New code should use ``default_rng().weibull`` (see - `random-quick-start`) instead. + New code should use the ``weibull`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -2468,8 +2468,8 @@ cdef class RandomState: Also known as the power function distribution. .. note:: - New code should use ``default_rng().power`` (see - `random-quick-start`) instead. + New code should use the ``power`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -2579,8 +2579,8 @@ cdef class RandomState: random variables. .. note:: - New code should use ``default_rng().laplace`` (see - `random-quick-start`) instead. + New code should use the ``laplace`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -2670,8 +2670,8 @@ cdef class RandomState: Notes and References below. .. note:: - New code should use ``default_rng().gumbel`` (see - `random-quick-start`) instead. + New code should use the ``gumbel`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -2792,8 +2792,8 @@ cdef class RandomState: parameters, loc (location or mean, also median), and scale (>0). .. note:: - New code should use ``default_rng().logistic`` (see - `random-quick-start`) instead. + New code should use the ``logistic`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -2879,8 +2879,8 @@ cdef class RandomState: underlying normal distribution it is derived from. .. note:: - New code should use ``default_rng().lognormal`` (see - `random-quick-start`) instead. + New code should use the ``lognormal`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -2992,8 +2992,8 @@ cdef class RandomState: Rayleigh. .. note:: - New code should use ``default_rng().rayleigh`` (see - `random-quick-start`) instead. + New code should use the ``rayleigh`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -3074,8 +3074,8 @@ cdef class RandomState: unit distance and distance covered in unit time. .. note:: - New code should use ``default_rng().wald`` (see - `random-quick-start`) instead. + New code should use the ``wald`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -3147,8 +3147,8 @@ cdef class RandomState: directly define the shape of the pdf. .. note:: - New code should use ``default_rng().triangular`` (see - `random-quick-start`) instead. + New code should use the ``triangular`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -3254,8 +3254,8 @@ cdef class RandomState: input as a float, but it is truncated to an integer in use) .. note:: - New code should use ``default_rng().binomial`` (see - `random-quick-start`) instead. + New code should use the ``binomial`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -3404,8 +3404,8 @@ cdef class RandomState: is > 0 and `p` is in the interval [0, 1]. .. note:: - New code should use ``default_rng().negative_binomial`` (see - `random-quick-start`) instead. + New code should use the ``negative_binomial`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -3489,8 +3489,8 @@ cdef class RandomState: for large N. .. note:: - New code should use ``default_rng().poisson`` (see - `random-quick-start`) instead. + New code should use the ``poisson`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -3575,8 +3575,8 @@ cdef class RandomState: frequency table. .. note:: - New code should use ``default_rng().zipf`` (see - `random-quick-start`) instead. + New code should use the ``zipf`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -3665,8 +3665,8 @@ cdef class RandomState: where `p` is the probability of success of an individual trial. .. note:: - New code should use ``default_rng().geometric`` (see - `random-quick-start`) instead. + New code should use the ``geometric`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -3719,8 +3719,8 @@ cdef class RandomState: than or equal to the sum ``ngood + nbad``). .. note:: - New code should use ``default_rng().hypergeometric`` (see - `random-quick-start`) instead. + New code should use the ``hypergeometric`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -3850,8 +3850,8 @@ cdef class RandomState: shape parameter, 0 < ``p`` < 1. .. note:: - New code should use ``default_rng().logseries`` (see - `random-quick-start`) instead. + New code should use the ``logseries`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -3943,8 +3943,8 @@ cdef class RandomState: squared) of the one-dimensional normal distribution. .. note:: - New code should use ``default_rng().multivariate_normal`` (see - `random-quick-start`) instead. + New code should use the ``multivariate_normal`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -4117,8 +4117,8 @@ cdef class RandomState: outcome was ``i``. .. note:: - New code should use ``default_rng().multinomial`` (see - `random-quick-start`) instead. + New code should use the ``multinomial`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -4235,8 +4235,8 @@ cdef class RandomState: inference. .. note:: - New code should use ``default_rng().dirichlet`` (see - `random-quick-start`) instead. + New code should use the ``dirichlet`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -4380,8 +4380,8 @@ cdef class RandomState: their contents remains the same. .. note:: - New code should use ``default_rng().shuffle`` (see - `random-quick-start`) instead. + New code should use the ``shuffle`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ---------- @@ -4475,8 +4475,8 @@ cdef class RandomState: first index. .. note:: - New code should use ``default_rng().permutation`` (see - `random-quick-start`) instead. + New code should use the ``permutation`` method of a ``default_rng()`` + instance instead; see `random-quick-start`. Parameters ----------