Skip to main content
`Ctrl`+`K`

# 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.

    replace bool, optional

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

    p 1-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`.

    axis int, optional

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

    shuffle bool, optional

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

  Returns:
    samples single 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')