multinomial

Contents

multinomial#

class brainstate.random.multinomial(n, pvals, size=None, key=None, dtype=None, check_valid=True)#

Draw samples from a multinomial distribution.

The multinomial distribution is a multivariate generalization of the binomial distribution. Take an experiment with one of p possible outcomes. An example of such an experiment is throwing a dice, where the outcome can be 1 through 6. Each sample drawn from the distribution represents n such experiments. Its values, X_i = [X_0, X_1, ..., X_p], represent the number of times the outcome was i.

Parameters:

  • n (int) – Number of experiments.

  • pvals (sequence of floats, length p) – Probabilities of each of the p different outcomes. These must sum to 1 (however, the last element is always assumed to account for the remaining probability, as long as sum(pvals[:-1]) <= 1).

  • size (int | Sequence[int] | integer | Sequence[integer] | None) – Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

  • key (int | Array | ndarray | None) – The key for the random number generator. If not given, the default random number generator is used.

Returns:

out – The drawn samples, of shape size, if that was provided. If not, the shape is (N,).

In other words, each entry out[i,j,...,:] is an N-dimensional value drawn from the distribution.

Return type:

ndarray

Examples

Throw a dice 20 times:

>>> import brainstate
>>> result = brainstate.random.multinomial(20, [1/6.]*6, size=1)
>>> print(result.shape)  # (1, 6)
>>> print(result.sum())  # 20 (total throws)

Now, throw the dice 20 times, and 20 times again:

>>> result = brainstate.random.multinomial(20, [1/6.]*6, size=2)
>>> print(result.shape)  # (2, 6)
>>> print(result.sum(axis=1))  # [20, 20] (total throws per experiment)

A loaded die is more likely to land on number 6:

>>> result = brainstate.random.multinomial(100, [1/7.]*5 + [2/7.])
>>> print(result.shape)  # (6,)
>>> print(result.sum())  # 100 (total throws)

The probability inputs should be normalized. A biased coin which has twice as much weight on one side as on the other should be sampled like so:

>>> result = brainstate.random.multinomial(100, [1.0 / 3, 2.0 / 3])
>>> print(result.shape)  # (2,)
print(result.sum())  # 100 (total throws)
Contents