arkouda.numpy.random¶

Classes¶

Generator

Generator exposes a number of methods for generating random

Functions¶

`default_rng`([seed])	Construct a new Generator.
`randint`(→ arkouda.pdarrayclass.pdarray)	Generate a pdarray of randomized int, float, or bool values in a
`standard_normal`(→ arkouda.pdarrayclass.pdarray)	Draw real numbers from the standard normal distribution.
`uniform`(→ arkouda.pdarrayclass.pdarray)	Generate a pdarray with uniformly distributed random float values

Module Contents¶

class arkouda.numpy.random.Generator[source]¶

Generator exposes a number of methods for generating random numbers drawn from a variety of probability distributions. In addition to the distribution-specific arguments, each method takes a keyword argument size that defaults to None. If size is None, then a single value is generated and returned. If size is an integer, then a 1-D array filled with generated values is returned.

Parameters:

seed (int) – Seed to allow for reproducible random number generation.
name_dict (dict) – Dictionary mapping the server side names associated with the generators for each dtype.
state (int) – The current state we are in the random number generation stream. This information makes it so calls to any dtype generator function affects the stream of random numbers for the other generators. This mimics the behavior we see in numpy

See also

default_rng: Recommended constructor for Generator.

choice(a, size=None, replace=True, p=None)[source]¶

Generates a randomly sample from a.

Parameters:

a (int or pdarray) – If a is an integer, randomly sample from ak.arange(a). If a is a pdarray, randomly sample from a.
size (int, optional) – Number of elements to be sampled
replace (bool, optional) – If True, sample with replacement. Otherwise sample without replacement. Defaults to True
p (pdarray, optional) – p is the probabilities or weights associated with each element of a

Returns:

A pdarray containing the sampled values or a single random value if size not provided.

Return type:

pdarray, numeric_scalar

exponential(scale=1.0, size=None, method='zig')[source]¶

Draw samples from an exponential distribution.

Its probability density function is

\[f(x; \frac{1}{\beta}) = \frac{1}{\beta} \exp(-\frac{x}{\beta}),\]

for x > 0 and 0 elsewhere. \(\beta\) is the scale parameter, which is the inverse of the rate parameter \(\lambda = 1/\beta\). The rate parameter is an alternative, widely used parameterization of the exponential distribution.

Parameters:

scale (float or pdarray) – The scale parameter, \(\beta = 1/\lambda\). Must be non-negative. An array must have the same size as the size argument.
size (numeric_scalars, optional) – Output shape. Default is None, in which case a single value is returned.
method (str, optional) – Either ‘inv’ or ‘zig’. ‘inv’ uses the default inverse CDF method. ‘zig’ uses the Ziggurat method.

Returns:

Drawn samples from the parameterized exponential distribution.

Return type:

pdarray

integers(low, high=None, size=None, dtype=numpy.int64, endpoint=False)[source]¶

Return random integers from low (inclusive) to high (exclusive), or if endpoint=True, low (inclusive) to high (inclusive).

Return random integers from the “discrete uniform” distribution of the specified dtype. If high is None (the default), then results are from 0 to low.

Parameters:

low (numeric_scalars) – Lowest (signed) integers to be drawn from the distribution (unless high=None, in which case this parameter is 0 and this value is used for high).
high (numeric_scalars) – If provided, one above the largest (signed) integer to be drawn from the distribution (see above for behavior if high=None)
size (numeric_scalars) – Output shape. Default is None, in which case a single value is returned.
dtype (dtype, optional) – Desired dtype of the result. The default value is ak.int64.
endpoint (bool, optional) – If true, sample from the interval [low, high] instead of the default [low, high). Defaults to False

Returns:

Values drawn uniformly from the specified range having the desired dtype, or a single such random int if size not provided.

Return type:

pdarray, numeric_scalar

Examples

>>> rng = ak.random.default_rng()
>>> rng.integers(5, 20, 10)
array([15, 13, 10, 8, 5, 18, 16, 14, 7, 13])  # random
>>> rng.integers(5, size=10)
array([2, 4, 0, 0, 0, 3, 1, 5, 5, 3])  # random

logistic(loc=0.0, scale=1.0, size=None)[source]¶

Draw samples from a logistic distribution.

Samples are drawn from a logistic distribution with specified parameters, loc (location or mean, also median), and scale (>0).

Parameters:

loc (float or pdarray of floats, optional) – Parameter of the distribution. Default of 0.
scale (float or pdarray of floats, optional) – Parameter of the distribution. Must be non-negative. Default is 1.
size (numeric_scalars, optional) – Output shape. Default is None, in which case a single value is returned.

Notes

The probability density for the Logistic distribution is

\[P(x) = \frac{e^{-(x - \mu)/s}}{s( 1 + e^{-(x - \mu)/s})^2}\]

where \(\mu\) is the location and \(s\) is the scale.

The Logistic distribution is used in Extreme Value problems where it can act as a mixture of Gumbel distributions, in Epidemiology, and by the World Chess Federation (FIDE) where it is used in the Elo ranking system, assuming the performance of each player is a logistically distributed random variable.

Returns:: Pdarray of floats (unless size=None, in which case a single float is returned).
Return type:: pdarray

See also

normal

Examples

>>> ak.random.default_rng(17).logistic(3, 2.5, 3)
array([1.1319566682702642 -7.1665150633720014 7.7208667145173608])

lognormal(mean=0.0, sigma=1.0, size=None, method='zig')[source]¶

Draw samples from a log-normal distribution with specified mean, standard deviation, and array shape.

Note that the mean and standard deviation are not the values for the distribution itself, but of the underlying normal distribution it is derived from.

Parameters:

mean (float or pdarray of floats, optional) – Mean of the distribution. Default of 0.
sigma (float or pdarray of floats, optional) – Standard deviation of the distribution. Must be non-negative. Default of 1.
size (numeric_scalars, optional) – Output shape. Default is None, in which case a single value is returned.
method (str, optional) – Either ‘box’ or ‘zig’. ‘box’ uses the Box–Muller transform ‘zig’ uses the Ziggurat method.

Notes

A variable x has a log-normal distribution if log(x) is normally distributed. The probability density for the log-normal distribution is:

\[p(x) = \frac{1}{\sigma x \sqrt{2\pi}} e^{-\frac{(\ln(x)-\mu)^2}{2\sigma^2}}\]

where \(\mu\) is the mean and \(\sigma\) the standard deviation of the normally distributed logarithm of the variable. A log-normal distribution results if a random variable is the product of a large number of independent, identically-distributed variables in the same way that a normal distribution results if the variable is the sum of a large number of independent, identically-distributed variables.

Returns:: Pdarray of floats (unless size=None, in which case a single float is returned).
Return type:: pdarray

See also

normal

Examples

>>> ak.random.default_rng(17).lognormal(3, 2.5, 3)
array([7.3866978126031091 106.20159494048757 4.5424399190667666])

normal(loc=0.0, scale=1.0, size=None, method='zig')[source]¶

Draw samples from a normal (Gaussian) distribution

Parameters:

loc (float or pdarray of floats, optional) – Mean of the distribution. Default of 0.
scale (float or pdarray of floats, optional) – Standard deviation of the distribution. Must be non-negative. Default of 1.
size (numeric_scalars, optional) – Output shape. Default is None, in which case a single value is returned.
method (str, optional) – Either ‘box’ or ‘zig’. ‘box’ uses the Box–Muller transform ‘zig’ uses the Ziggurat method.

Notes

The probability density for the Gaussian distribution is:

\[p(x) = \frac{1}{\sqrt{2\pi \sigma^2}} e^{-\frac{(x-\mu)^2}{2\sigma^2}}\]

where \(\mu\) is the mean and \(\sigma\) the standard deviation. The square of the standard deviation, \(\sigma^2\), is called the variance.

Returns:: Pdarray of floats (unless size=None, in which case a single float is returned).
Return type:: pdarray

See also

standard_normal, uniform

Examples

>>> ak.random.default_rng(17).normal(3, 2.5, 3)
array([2.3673425816523577 4.0532529435624589 2.0598322696795694])

permutation(x)[source]¶

Randomly permute a sequence, or return a permuted range.

Parameters:: x (int or pdarray) – If x is an integer, randomly permute ak.arange(x). If x is an array, make a copy and shuffle the elements randomly.
Returns:: pdarray of permuted elements
Return type:: pdarray

poisson(lam=1.0, size=None)[source]¶

Draw samples from a Poisson distribution.

The Poisson distribution is the limit of the binomial distribution for large N.

Parameters:

lam (float or pdarray) – Expected number of events occurring in a fixed-time interval, must be >= 0. An array must have the same size as the size argument.
size (numeric_scalars, optional) – Output shape. Default is None, in which case a single value is returned.

Notes

The probability mass function for the Poisson distribution is:

\[f(k; \lambda) = \frac{\lambda^k e^{-\lambda}}{k!}\]

For events with an expected separation \(\lambda\), the Poisson distribution \(f(k; \lambda)\) describes the probability of \(k\) events occurring within the observed interval \(\lambda\)

Returns:: Pdarray of ints (unless size=None, in which case a single int is returned).
Return type:: pdarray

Examples

>>> rng = ak.random.default_rng()
>>> rng.poisson(lam=3, size=5)
array([5 3 2 2 3])  # random

random(size=None)[source]¶

Return random floats in the half-open interval [0.0, 1.0).

Results are from the uniform distribution over the stated interval.

Parameters:: size (numeric_scalars, optional) – Output shape. Default is None, in which case a single value is returned.
Returns:: Pdarray of random floats (unless size=None, in which case a single float is returned).
Return type:: pdarray

Notes

To sample over [a,b), use uniform or multiply the output of random by (b - a) and add a:

(b - a) * random() + a

See also

uniform

Examples

>>> rng = ak.random.default_rng()
>>> rng.random()
0.47108547995356098 # random
>>> rng.random(3)
array([0.055256829926011691, 0.62511314008006458, 0.16400145561571539]) # random

shuffle(x)[source]¶

Randomly shuffle a pdarray in place.

Parameters:: x (pdarray) – shuffle the elements of x randomly in place
Return type:: None

standard_exponential(size=None, method='zig')[source]¶

Draw samples from the standard exponential distribution.

standard_exponential is identical to the exponential distribution with a scale parameter of 1.

Parameters:

size (numeric_scalars, optional) – Output shape. Default is None, in which case a single value is returned.
method (str, optional) – Either ‘inv’ or ‘zig’. ‘inv’ uses the default inverse CDF method. ‘zig’ uses the Ziggurat method.

Returns:

Drawn samples from the standard exponential distribution.

Return type:

pdarray

standard_normal(size=None, method='zig')[source]¶

Draw samples from a standard Normal distribution (mean=0, stdev=1).

Parameters:

size (numeric_scalars, optional) – Output shape. Default is None, in which case a single value is returned.
method (str, optional) – Either ‘box’ or ‘zig’. ‘box’ uses the Box–Muller transform ‘zig’ uses the Ziggurat method.

Returns:

Pdarray of floats (unless size=None, in which case a single float is returned).

Return type:

pdarray

Notes

For random samples from \(N(\mu, \sigma^2)\), either call normal or do:

\[(\sigma \cdot \texttt{standard_normal}(size)) + \mu\]

See also

normal

Examples

>>> rng = ak.random.default_rng()
>>> rng.standard_normal()
2.1923875335537315 # random
>>> rng.standard_normal(3)
array([0.8797352989638163, -0.7085325853376141, 0.021728052940979934])  # random

uniform(low=0.0, high=1.0, size=None)[source]¶

Draw samples from a uniform distribution.

Samples are uniformly distributed over the half-open interval [low, high). In other words, any value within the given interval is equally likely to be drawn by uniform.

Parameters:

low (float, optional) – Lower boundary of the output interval. All values generated will be greater than or equal to low. The default value is 0.
high (float, optional) – Upper boundary of the output interval. All values generated will be less than high. high must be greater than or equal to low. The default value is 1.0.
size (numeric_scalars, optional) – Output shape. Default is None, in which case a single value is returned.

Returns:

Pdarray of floats (unless size=None, in which case a single float is returned).

Return type:

pdarray

See also

integers, random

Examples

>>> rng = ak.random.default_rng()
>>> rng.uniform(-1, 1, 3)
array([0.030785499755523249, 0.08505865366367038, -0.38552048588998722])  # random

arkouda.numpy.random.default_rng(seed=None)[source]¶

Construct a new Generator.

Right now we only support PCG64, since this is what is available in chapel.

Parameters:: seed ({None, int, Generator}, optional) – A seed to initialize the Generator. If None, then the seed will be generated by chapel in an implementation specific manner based on the current time. This behavior is currently unstable and may change in the future. If an int, then the value must be non-negative. If passed a Generator, it will be returned unaltered.
Returns:: The initialized generator object.
Return type:: Generator

Generate a pdarray of randomized int, float, or bool values in a specified range bounded by the low and high parameters.

Parameters:

low (numeric_scalars) – The low value (inclusive) of the range
high (numeric_scalars) – The high value (exclusive for int, inclusive for float) of the range
size (int_scalars) – The length of the returned array
dtype (Union[int64, float64, bool]) – The dtype of the array
seed (int_scalars, optional) – Seed to allow for reproducible random number generation

Returns:

Values drawn uniformly from the specified range having the desired dtype

Return type:

pdarray

Raises:

TypeError – Raised if dtype.name not in DTypes, size is not an int, low or high is not an int or float, or seed is not an int
ValueError – Raised if size < 0 or if high < low

Notes

Calling randint with dtype=float64 will result in uniform non-integral floating point values.

Ranges >= 2**64 in size is undefined behavior because it exceeds the maximum value that can be stored on the server (uint64)

Examples

>>> ak.randint(0, 10, 5)
array([5, 7, 4, 8, 3])

>>> ak.randint(0, 1, 3, dtype=ak.float64)
array([0.92176432277231968, 0.083130710959903542, 0.68894208386667544])

>>> ak.randint(0, 1, 5, dtype=ak.bool_)
array([True, False, True, True, True])

>>> ak.randint(1, 5, 10, seed=2)
array([4, 3, 1, 3, 4, 4, 2, 4, 3, 2])

>>> ak.randint(1, 5, 3, dtype=ak.float64, seed=2)
array([2.9160772326374946, 4.353429832157099, 4.5392023718621486])

>>> ak.randint(1, 5, 10, dtype=ak.bool, seed=2)
array([False, True, True, True, True, False, True, True, True, True])

Draw real numbers from the standard normal distribution.

Parameters:

size (int_scalars) – The number of samples to draw (size of the returned array)
seed (int_scalars) – Value used to initialize the random number generator

Returns:

The array of random numbers

Return type:

pdarray, float64

Raises:

TypeError – Raised if size is not an int
ValueError – Raised if size < 0

See also

randint

Notes

For random samples from \(N(\mu, \sigma^2)\), use:

(sigma * standard_normal(size)) + mu

Examples

>>> ak.standard_normal(3,1)
array([-0.68586185091150265, 1.1723810583573375, 0.567584107142031])

Generate a pdarray with uniformly distributed random float values in a specified range.

Parameters:

low (float_scalars) – The low value (inclusive) of the range, defaults to 0.0
high (float_scalars) – The high value (inclusive) of the range, defaults to 1.0
size (int_scalars) – The length of the returned array
seed (int_scalars, optional) – Value used to initialize the random number generator

Returns:

Values drawn uniformly from the specified range

Return type:

pdarray, float64

Raises:

TypeError – Raised if dtype.name not in DTypes, size is not an int, or if either low or high is not an int or float
ValueError – Raised if size < 0 or if high < low

Notes

The logic for uniform is delegated to the ak.randint method which is invoked with a dtype of float64

Examples

>>> ak.uniform(3)
array([0.92176432277231968, 0.083130710959903542, 0.68894208386667544])

>>> ak.uniform(size=3,low=0,high=5,seed=0)
array([0.30013431967121934, 0.47383036230759112, 1.0441791878997098])