Binomial

class paddle.distribution. Binomial ( total_count, probs ) [source]

The Binomial distribution with size total_count and probs parameters.

In probability theory and statistics, the binomial distribution is the most basic discrete probability distribution defined on \([0, n] \cap \mathbb{N}\), which can be viewed as the number of times a potentially unfair coin is tossed to get heads, and the result of its random variable can be viewed as the sum of a series of independent Bernoulli experiments.

The probability mass function (pmf) is

\[pmf(x; n, p) = \frac{n!}{x!(n-x)!}p^{x}(1-p)^{n-x}\]

In the above equation:

  • \(total\_count = n\): is the size, meaning the total number of Bernoulli experiments.

  • \(probs = p\): is the probability of the event happening in one Bernoulli experiments.

Parameters

  • total_count (int|Tensor) – The size of Binomial distribution which should be greater than 0, meaning the number of independent bernoulli trials with probability parameter \(p\). The data type will be converted to 1-D Tensor with paddle global default dtype if the input probs is not Tensor, otherwise will be converted to the same as probs.

  • probs (float|Tensor) – The probability of Binomial distribution which should reside in [0, 1], meaning the probability of success for each individual bernoulli trial. If the input data type is float, it will be converted to a 1-D Tensor with paddle global default dtype.

Examples

>>> import paddle
>>> from paddle.distribution import Binomial
>>> paddle.set_device('cpu')
>>> paddle.seed(100)
>>> rv = Binomial(100, paddle.to_tensor([0.3, 0.6, 0.9]))

>>> print(rv.sample([2]))
Tensor(shape=[2, 3], dtype=float32, place=Place(cpu), stop_gradient=True,
[[31., 62., 93.],
 [29., 54., 91.]])

>>> print(rv.mean)
Tensor(shape=[3], dtype=float32, place=Place(cpu), stop_gradient=True,
[30.00000191, 60.00000381, 90.        ])

>>> print(rv.entropy())
Tensor(shape=[3], dtype=float32, place=Place(cpu), stop_gradient=True,
[2.94053698, 3.00781751, 2.51124287])
probs ( value )

probs

Probability density/mass function.

Note

This method will be deprecated in the future, please use prob instead.

property mean

Mean of binomial distribution.

Returns

mean value.

Return type

Tensor

property variance

Variance of binomial distribution.

Returns

variance value.

Return type

Tensor

sample ( shape=() )

sample

Generate binomial samples of the specified shape. The final shape would be shape+batch_shape .

Parameters

shape (Sequence[int], optional) – Prepended shape of the generated samples.

Returns

Sampled data with shape sample_shape + batch_shape. The returned data type is the same as probs.

Return type

Tensor

entropy ( )

entropy

Shannon entropy in nats.

The entropy is

\[\mathcal{H}(X) = - \sum_{x \in \Omega} p(x) \log{p(x)}\]

In the above equation:

  • \(\Omega\): is the support of the distribution.

Returns

Shannon entropy of binomial distribution. The data type is the same as probs.

Return type

Tensor

log_prob ( value )

log_prob

Log probability density/mass function.

Parameters

value (Tensor) – The input tensor.

Returns

log probability. The data type is the same as probs.

Return type

Tensor

prob ( value )

prob

Probability density/mass function.

Parameters

value (Tensor) – The input tensor.

Returns

probability. The data type is the same as probs.

Return type

Tensor

kl_divergence ( other ) [source]

kl_divergence

The KL-divergence between two binomial distributions with the same total_count.

The probability density function (pdf) is

\[KL\_divergence(n_1, p_1, n_2, p_2) = \sum_x p_1(x) \log{\frac{p_1(x)}{p_2(x)}}\]
\[p_1(x) = \frac{n_1!}{x!(n_1-x)!}p_1^{x}(1-p_1)^{n_1-x}\]
\[p_2(x) = \frac{n_2!}{x!(n_2-x)!}p_2^{x}(1-p_2)^{n_2-x}\]
Parameters

other (Binomial) – instance of Binomial.

Returns

kl-divergence between two binomial distributions. The data type is the same as probs.

Return type

Tensor

property batch_shape

Returns batch shape of distribution

Returns

batch shape

Return type

Sequence[int]

property event_shape

Returns event shape of distribution

Returns

event shape

Return type

Sequence[int]

rsample ( shape=() )

rsample

reparameterized sample