arkouda.random

Package Contents

Classes

Generator

Generator exposes a number of methods for generating random

Functions

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(, high, seed, ...)

Generate a pdarray with uniformly distributed random float values
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.

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

integers(low, high=None, size=None, dtype=akint64, 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
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

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_normal(size=None)[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.

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)\), use:

(sigma * standard_normal(size)) + mu

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.random.randint(low: arkouda.dtypes.numeric_scalars, high: arkouda.dtypes.numeric_scalars, size: arkouda.dtypes.int_scalars | Tuple[arkouda.dtypes.int_scalars, Ellipsis] = 1, dtype=akint64, seed: arkouda.dtypes.int_scalars | None = None) → arkouda.pdarrayclass.pdarray[source]

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])
arkouda.random.standard_normal(size: arkouda.dtypes.int_scalars, seed: None | arkouda.dtypes.int_scalars = None) → arkouda.pdarrayclass.pdarray[source]

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])
arkouda.random.uniform(size: arkouda.dtypes.int_scalars, low: arkouda.dtypes.numeric_scalars = float(0.0), high: arkouda.dtypes.numeric_scalars = 1.0, seed: None | arkouda.dtypes.int_scalars = None) → arkouda.pdarrayclass.pdarray[source]

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])