numpy.random.Generator.choice

method

random.Generator.choice(a, size=None, replace=True, p=None, axis=0, shuffle=True)

Generates a random sample from a given array

Parameters:

a{array_like, int}

If an ndarray, a random sample is generated from its elements. If an int, the random sample is generated from np.arange(a).

size{int, tuple[int]}, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn from the 1-d a. If a has more than one dimension, the size shape will be inserted into the axis dimension, so the output ndim will be a.ndim - 1 + len(size). Default is None, in which case a single value is returned.

replacebool, optional

Whether the sample is with or without replacement. Default is True, meaning that a value of a can be selected multiple times.

p1-D array_like, optional

The probabilities associated with each entry in a. If not given, the sample assumes a uniform distribution over all entries in a.

axisint, optional

The axis along which the selection is performed. The default, 0, selects by row.

shufflebool, optional

Whether the sample is shuffled when sampling without replacement. Default is True, False provides a speedup.

Returns:

samplessingle item or ndarray

The generated random samples

Raises:

ValueError

If a is an int and less than zero, if p is not 1-dimensional, if a is array-like with a size 0, if p is not a vector of probabilities, if a and p have different lengths, or if replace=False and the sample size is greater than the population size.

See also

integers, shuffle, permutation

Notes

Setting user-specified probabilities through p uses a more general but less efficient sampler than the default. The general sampler produces a different sample than the optimized sampler even if each element of p is 1 / len(a).

p must sum to 1 when cast to float64. To ensure this, you may wish to normalize using p = p / np.sum(p, dtype=float).

When passing a as an integer type and size is not specified, the return type is a native Python int.

Examples

Generate a uniform random sample from np.arange(5) of size 3:

>>> rng = np.random.default_rng()
>>> rng.choice(5, 3)
array([0, 3, 4]) # random
>>> #This is equivalent to rng.integers(0,5,3)

Generate a non-uniform random sample from np.arange(5) of size 3:

>>> rng.choice(5, 3, p=[0.1, 0, 0.3, 0.6, 0])
array([3, 3, 0]) # random

Generate a uniform random sample from np.arange(5) of size 3 without replacement:

>>> rng.choice(5, 3, replace=False)
array([3,1,0]) # random
>>> #This is equivalent to rng.permutation(np.arange(5))[:3]

Generate a uniform random sample from a 2-D array along the first axis (the default), without replacement:

>>> rng.choice([[0, 1, 2], [3, 4, 5], [6, 7, 8]], 2, replace=False)
array([[3, 4, 5], # random
       [0, 1, 2]])

Generate a non-uniform random sample from np.arange(5) of size 3 without replacement:

>>> rng.choice(5, 3, replace=False, p=[0.1, 0, 0.3, 0.6, 0])
array([2, 3, 0]) # random

Any of the above can be repeated with an arbitrary array-like instead of just integers. For instance:

>>> aa_milne_arr = ['pooh', 'rabbit', 'piglet', 'Christopher']
>>> rng.choice(aa_milne_arr, 5, p=[0.5, 0.1, 0.1, 0.3])
array(['pooh', 'pooh', 'pooh', 'Christopher', 'piglet'], # random
      dtype='<U11')