Random in Arkouda¶

Pseudo random number generation in Arkouda is modeled after numpy. Just like in numpy the preferred way to access the random functionality in arkouda is via Generator objects. If a Generator is initialized with a seed, the stream of random numbers it produces can be reproduced by a new Generator with the same seed. This reproducibility is not guaranteed across releases.

class arkouda.random.Generator(name_dict=None, seed=None, state=1)[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.

Creation¶

To create a Generator use the default_rng constructor

Features¶

choice¶

arkouda.random.Generator.choice(self, a, size=None, replace=True, p=None)¶

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¶

arkouda.random.Generator.exponential(self, scale=1.0, size=None, method='zig')¶

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¶

arkouda.random.Generator.integers(self, low, high=None, size=None, dtype=<class 'numpy.int64'>, endpoint=False)¶

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¶

arkouda.random.Generator.logistic(self, loc=0.0, scale=1.0, size=None)¶

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¶

arkouda.random.Generator.lognormal(self, mean=0.0, sigma=1.0, size=None, method='zig')¶

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¶

arkouda.random.Generator.normal(self, loc=0.0, scale=1.0, size=None, method='zig')¶

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¶

arkouda.random.Generator.permutation(self, x)¶

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¶

arkouda.random.Generator.poisson(self, lam=1.0, size=None)¶

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

shuffle¶

arkouda.random.Generator.shuffle(self, x)¶

Randomly shuffle a pdarray in place.

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

random¶

arkouda.random.Generator.random(self, size=None)¶

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

standard_exponential¶

arkouda.random.Generator.standard_exponential(self, size=None, method='zig')¶

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¶

arkouda.random.Generator.standard_normal(self, size=None, method='zig')¶

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¶

arkouda.random.Generator.uniform(self, low=0.0, high=1.0, size=None)¶

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