mixle.stats.univariate.discrete.bernoulli module

Bernoulli distributions over binary outcomes.

Data type: bool or values in {0, 1}. The distribution has success probability p and log-density log(p) for True/1 and log(1-p) for False/0.

Reference: Johnson, Kemp & Kotz, Univariate Discrete Distributions (3rd ed., Wiley, 2005).

class BernoulliDistribution(p, name=None, keys=None, prior=None)

Bases: SequenceEncodableProbabilityDistribution

Bernoulli distribution over {False, True} with success probability p.

Parameters:

• p (float)

• name (str | None)

• keys (str | None)

• prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()

Describe backend support for generated Bernoulli kernels.

classmethod compute_declaration()

Return the structured compute declaration for Bernoulli distributions.

static exp_family_sufficient_statistics(x, engine)

Return Bernoulli sufficient statistics for generated scoring.

Parameters:

• x (Any)

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_base_measure(x, engine)

Return the Bernoulli base measure: 0 on {0, 1}, -inf for any other count.

The generated engine kernels score x log p + (1 - x) log(1 - p) with no support of their own, so once the encoder admitted a count outside {0, 1} (Q01-F02) the numba-generated kernel scored -1 as a POSITIVE log-probability, and an engine fit reported a finite validation objective the default route refuses (V01-F04). The support lives in the base measure, as the Poisson family’s already does.

Parameters:

• x (Any)

• engine (Any)

Return type:

Any

static exp_family_legacy_sufficient_statistics(x, params, engine)

Return per-row Bernoulli sufficient statistics in accumulator order.

Parameters:

• x (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)

Return Bernoulli natural parameters for generated scoring.

Parameters:

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)

Return Bernoulli log partition for generated scoring.

Parameters:

• params (dict[str, Any])

• engine (Any)

Return type:

Any

set_prior(prior)

Attach a Beta parameter prior and precompute conjugate-prior expectations.

With a Beta(a, b) prior on the success probability p this caches the digamma terms so that expected_log_density evaluates the variational Bayes expectation E_q[log p(x | p)] via E[log p] = digamma(a) - digamma(a+b) and E[log(1-p)] = digamma(b) - digamma(a+b). Any other prior (including None) leaves the distribution a plain point model.

Parameters:

prior (SequenceEncodableProbabilityDistribution | None)

Return type:

None

expected_log_density(x)

Variational expectation E_q[log p(x | p)] under the Beta prior.

Falls back to the plug-in log_density(x) when no conjugate prior is attached.

Parameters:

x (bool | int)

Return type:

float

seq_expected_log_density(x)

Vectorized expected_log_density over sequence-encoded observations.

Parameters:

x (ndarray)

Return type:

ndarray

density(x)

Return the probability density or mass at a single observation.

Parameters:

x (bool | int)

Return type:

float

log_density(x)

Return the log-density or log-mass at a single observation.

Parameters:

x (bool | int)

Return type:

float

seq_log_density(x)

Return vectorized log-density values for sequence-encoded observations.

A boolean encoding holds only valid outcomes. An integer encoding is what the encoder emits when the batch also holds a count outside {0, 1}, which this law gives probability zero: it scores -inf, as the scalar path does (P02-F03, Q01-F02).

Parameters:

x (ndarray)

Return type:

ndarray

static backend_log_density_from_params(x, p, engine)

Engine-neutral Bernoulli log-mass from explicit parameters (-inf outside {0, 1}).

Parameters:

• x (Any)

• p (Any)

• engine (Any)

Return type:

Any

backend_seq_log_density(x, engine)

Engine-neutral vectorized log-density for encoded data.

Parameters:

• x (Any)

• engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)

Return stacked Bernoulli parameters for a homogeneous mixture kernel.

Parameters:

• dists (Sequence[BernoulliDistribution])

• engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)

Return an (n, k) matrix of Bernoulli log masses.

Parameters:

• x (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

Any

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)

Return stacked Bernoulli sufficient statistics using engine-resident arrays.

Parameters:

• x (Any)

• weights (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, Any]

support_size()

The two outcomes {0, 1}.

Return type:

int

to_fisher(**kwargs)

Return the Bernoulli’s count-family Fisher view.

mean()

Mean E[X] of the distribution.

Return type:

float

variance()

Variance Var[X] of the distribution.

Return type:

float

cdf(x)

Cumulative distribution function P(X <= x) over {0, 1}.

Parameters:

x (float)

Return type:

float

skewness()

Skewness (1-2p)/sqrt(p(1-p)).

Return type:

float

kurtosis()

Excess kurtosis (1-6p(1-p))/(p(1-p)).

Return type:

float

quantile(q)

Inverse CDF F^{-1}(q) over {0, 1}.

Parameters:

q (float)

Return type:

float

entropy()

Shannon entropy -p log p - (1-p) log(1-p) (nats).

Return type:

float

mode()

Mode (0 if p<1/2 else 1).

Return type:

float

sampler(seed=None)

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

BernoulliSampler

estimator(pseudo_count=None)

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

BernoulliEstimator

dist_to_encoder()

Return the data encoder used by this distribution for vectorized methods.

Return type:

BernoulliDataEncoder

enumerator()

Return an enumerator over the distribution support when available.

Return type:

BernoulliEnumerator

class BernoulliEnumerator(dist)

Bases: DistributionEnumerator

Enumerate False/True in descending probability order.

Parameters:

dist (BernoulliDistribution)

class BernoulliSampler(dist, seed=None)

Bases: DistributionSampler

Draw iid Bernoulli observations.

Parameters:

• dist (BernoulliDistribution)

• seed (int | None)

sample(size=None, *, batched=True)

Draw one sample or a list of iid samples.

Parameters:

• size (int | None)

• batched (bool)

Return type:

bool | Sequence[bool]

class BernoulliAccumulator(name=None, keys=None)

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted success and observation counts.

Parameters:

• name (str | None)

• keys (str | None)

update(x, weight, estimate)

Accumulate weighted success and count statistics for one observation.

Parameters:

• x (bool | int)

• weight (float)

• estimate (BernoulliDistribution | None)

Return type:

None

initialize(x, weight, rng)

Initialize statistics from one observation.

Parameters:

• x (bool | int)

• weight (float)

• rng (RandomState | None)

Return type:

None

supported_rows(x)

Encoded rows this law can be fitted on: outcomes in {0, 1}.

The encoder admits an integer outside {0, 1} so a mixture can encode one batch against every component (P02-F03); this is the predicate a latent model’s initialization consults before handing this component any responsibility. The encoder used to refuse such a count, so an integer-categorical-plus-Bernoulli mixture could not be encoded at all (Q01-F02).

Parameters:

x (ndarray)

Return type:

ndarray

seq_update(x, weights, estimate)

Accumulate weighted statistics from encoded observations.

A count outside {0, 1} carrying weight is refused; with zero weight it contributes nothing. Before the encoder admitted such counts this summed the raw value, which never mattered because none could arrive.

Parameters:

• x (ndarray)

• weights (ndarray)

• estimate (BernoulliDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)

Initialize statistics from encoded observations.

Parameters:

• x (ndarray)

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Merge another Bernoulli sufficient-statistic tuple.

Parameters:

suff_stat (tuple[float, float])

Return type:

BernoulliAccumulator

value()

Return the accumulated count and success total.

Return type:

tuple[float, float]

from_value(x)

Replace accumulator contents from a sufficient-statistic tuple.

Parameters:

x (tuple[float, float])

Return type:

BernoulliAccumulator

acc_to_encoder()

Return the encoder used by this accumulator.

Return type:

BernoulliDataEncoder

class BernoulliAccumulatorFactory(name=None, keys=None)

Bases: StatisticAccumulatorFactory

Factory for BernoulliAccumulator.

Parameters:

• name (str | None)

• keys (str | None)

make()

Create a fresh Bernoulli accumulator.

Return type:

BernoulliAccumulator

class BernoulliEstimator(pseudo_count=None, suff_stat=None, name=None, keys=None, prior=None)

Bases: ParameterEstimator

Estimate a Bernoulli distribution from weighted success counts.

Parameters:

• pseudo_count (float | None)

• suff_stat (float | None)

• name (str | None)

• keys (str | None)

• prior (SequenceEncodableProbabilityDistribution | None)

accumulator_factory()

Return an accumulator factory for Bernoulli sufficient statistics.

Return type:

BernoulliAccumulatorFactory

model_log_density(model)

Log-density of the model’s success probability under the Beta prior (ELBO global term).

Parameters:

model (BernoulliDistribution)

Return type:

float

estimate(nobs, suff_stat)

Estimate the Bernoulli success probability from weighted counts.

The distribution is defined on the open interval (0, 1), so a sample that is all successes or all failures – whose maximum-likelihood p is exactly 1 or 0 – is clamped _P_BOUNDARY (1e-12) away from the endpoint. When that clamp binds it is reported on the returned model through numerical_repairs() as bernoulli-p-clamped(...), and so through fit_provenance().repairs; an ordinary fit whose p is already interior records nothing.

Parameters:

• nobs (float | None)

• suff_stat (tuple[float, float])

Return type:

BernoulliDistribution

class BernoulliDataEncoder

Bases: DataSequenceEncoder

Encode Bernoulli observations as a boolean numpy array.

seq_encode(x)

Encode Bernoulli observations as a boolean array, or as integers when a count lies off {0, 1}.

An integer outside {0, 1} is an outcome this law gives probability zero – a probability question the scorer answers -inf – so it is admitted, and a mixture whose other component owns it can encode the whole batch (P02-F03, Q01-F02). Such a batch keeps its integers, since a boolean cast would turn 2 into a success. Anything that is not an integer stays refused.

Parameters:

x (Sequence[bool | int])

Return type:

ndarray