Binomial¶

class paddle.distribution. Binomial ( total_count: int | Tensor, probs: float | Tensor ) [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: Tensor ) → Tensor

probs¶

Probability density/mass function.

Note

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

property mean : Tensor

Mean of binomial distribution.

Returns

mean value.

Return type

Tensor

property variance : Tensor

Variance of binomial distribution.

Returns

variance value.

Return type

Tensor

sample ( shape: Sequence[int] = [] ) → Tensor

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 ( ) → Tensor

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

property batch_shape : Sequence[int]

Returns batch shape of distribution

Returns

batch shape

Return type

Sequence[int]

property event_shape : Sequence[int]

Returns event shape of distribution

Returns

event shape

Return type

Sequence[int]

log_prob ( value: Tensor ) → Tensor

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

rsample ( shape: Sequence[int] = [] ) → Tensor

rsample¶

reparameterized sample

prob ( value: Tensor ) → Tensor

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: Binomial ) → Tensor [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