class

Binomial

extendsDistribution

Binomial(total_count: Tensor | int = 1, probs: Tensor | float | None = None, logits: Tensor | float | None = None, validate_args: bool | None = None)

source

Binomial distribution over the number of successes in n independent trials.

Binomial(total_count=n, probs=p) models the count of successes when each of $n$ i.i.d. Bernoulli trials has success probability $p$ . Parameterisation is via either probs (in $[0, 1]$ ) or logits (the log-odds $\log(p/(1-p)) \in \mathbb{R}$ ); exactly one must be supplied.

Parameters

total_countTensor | int= 1

Number of trials

n \geq 0

. Default is 1 (reduces to Bernoulli).

probsTensor | float | None= None

Success probability

p \in [0, 1]

. Mutually exclusive with logits.

logitsTensor | float | None= None

Log-odds

l = \log(p / (1-p)) \in \mathbb{R}

. Mutually exclusive with probs.

validate_argsbool | None= None

If True, validate parameter constraints at construction time.

Attributes

total_countTensor

Number of trials

n

probsTensor

Success probability (present when constructed with probs).

logitsTensor

Log-odds (present when constructed with logits).

Notes

PMF:

P(X = k) = \binom{n}{k} p^k (1-p)^{n-k}, \quad k \in \{0, 1, \ldots, n\}

Log-PMF via logits (numerically stable form):

\log P(X = k) = \log\binom{n}{k} + k \, l - n \log(1 + e^l)

where $l = \operatorname{logit}(p)$ and the binomial coefficient is evaluated via $\log \Gamma(n+1) - \log\Gamma(k+1) - \log\Gamma(n-k+1)$ .

Moments:

Mean: $E[X] = np$
Variance: $\operatorname{Var}[X] = np(1-p)$

Sampling strategy: for $n \leq 25$ Bernoulli draws are summed exactly along a dedicated axis. For larger $n$ a Normal approximation is used with the result rounded and clamped to $[0, n]$ .

Examples

>>> import lucid
>>> from lucid.distributions import Binomial
>>> dist = Binomial(total_count=10, probs=0.3)
>>> samples = dist.sample((50,))
>>> samples.shape
(50,)
>>> # PMF at k=3
>>> dist.log_prob(lucid.tensor(3.0)).exp()

Methods (6)

dunder

init

→None

__init__(total_count: Tensor | int = 1, probs: Tensor | float | None = None, logits: Tensor | float | None = None, validate_args: bool | None = None)

source

Initialise a Binomial distribution.

Parameters

total_countTensor | int= 1

Number of trials

n \geq 0

. Default is 1 (reduces to Bernoulli).

probsTensor | float | None= None

Success probability

p \in [0, 1]

. Mutually exclusive with logits.

logitsTensor | float | None= None

Log-odds

l = \log(p / (1-p)) \in \mathbb{R}

. Mutually exclusive with probs.

validate_argsbool | None= None

If True, validate parameter constraints at construction time.

Raises

ValueError

If both or neither of probs and logits are provided.

prop

support

→Constraint

support: Constraint

source

Support of the Binomial distribution: non-negative integers.

Although the strict support is $\{0, 1, \ldots, n\}$ per element, this property returns nonnegative_integer because total_count may differ across the batch.

Returns

Constraint

The nonnegative_integer constraint.

prop

mean

→Tensor

mean: Tensor

source

Mean of the Binomial distribution: $E[X] = np$ .

Returns

Tensor

Mean values of shape batch_shape.

prop

variance

→Tensor

variance: Tensor

source

Variance of the Binomial distribution: $\operatorname{Var}[X] = np(1-p)$ .

Returns

Tensor

Variance values of shape batch_shape.

sample

→Tensor

sample(sample_shape: tuple[int, ...] = ())

source

Draw samples from the Binomial distribution.

Uses an exact strategy for small $n$ (sum of Bernoulli draws) and a Normal approximation with rounding for large $n$ .

Parameters

sample_shapetuple[int, ...]= ()

Leading shape of the output sample batch.

Returns

Tensor

Non-negative integer samples in $\{0, 1, \ldots, n\}$ , shape (*sample_shape, *batch_shape).

log_prob

→Tensor

log_prob(value: Tensor)

source

Log-probability of the given counts under the Binomial distribution.

Computed via logits for numerical stability:

\log P(X = k) = \log\binom{n}{k} + k \, l - n \log(1 + e^l)

where $l = \operatorname{logit}(p)$ and the binomial coefficient is evaluated via $\log\Gamma$ .

Parameters

valueTensor

Count values

k \in \{0, 1, \ldots, n\}

Returns

Tensor

Log-probability values of the same shape as value.