mixle.stats.univariate.discrete.binomial module¶

Create, estimate, and sample from the binomial distribution.

Defines the BinomialDistribution, BinomialSampler, BinomialAccumulatorFactory, BinomialAccumulator, BinomialEstimator, and the BinomialDataEncoder classes for use with mixle.

Data type: int.

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

class BinomialDistribution(p, n, min_val=None, name=None, keys=None, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Binomial distribution over min_val + {0, ..., n} with success probability p.

Parameters:

p (float)
n (int)
min_val (int | None)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

static exp_family_sufficient_statistics(x, engine)[source]

Return Binomial sufficient statistics from encoded observations.

The parameter-dependent support shift is handled by exp_family_sufficient_statistics_from_params when generated scoring supplies the declaration-stacked parameter bundle.

Parameters:

x (tuple[ndarray, ndarray, ndarray, int, int])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_sufficient_statistics_from_params(x, params, engine)[source]

Return Binomial sufficient statistics for generated scoring.

Parameters:

x (tuple[ndarray, ndarray, ndarray, int, int])
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return Binomial natural parameters for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return Binomial log partition for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

Any

static exp_family_base_measure(x, engine)[source]

Return the observation-only Binomial base measure.

Parameters:

x (tuple[ndarray, ndarray, ndarray, int, int])
engine (Any)

Return type:

Any

static exp_family_base_measure_from_params(x, params, engine)[source]

Return Binomial support/base measure for generated scoring.

Parameters:

x (tuple[ndarray, ndarray, ndarray, int, int])
params (dict[str, Any])
engine (Any)

Return type:

Any

set_prior(prior)[source]

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

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

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

expected_log_density(x)[source]

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

Uses the cached digamma expectations of log p and log(1-p); falls back to the plug-in log_density(x) when no conjugate prior is attached.

Parameters:: x (int)
Return type:: float

seq_expected_log_density(x)[source]

Vectorized expected_log_density over sequence-encoded observations.

Parameters:: x (tuple[ndarray, ndarray, ndarray, int, int])
Return type:: ndarray

density(x)[source]

Returns the probability mass of integer value x.

If x is not an integer between [0,n) or [min_val, n-1-min_val), density is 0.0.

Parameters:: x (int) – Integer value for density evaluation.
Returns:: Probability mass of x for binomial(n,p) with min_val=min_val. 0.0 if x is not in support.
Return type:: float

log_density(x)[source]

Returns the log-probability mass of integer value x.

If x is not an integer between [0,n) or [min_val, n-1-min_val), log-density is -inf.

Parameters:: x (int) – Integer value for density evaluation.
Returns:: Log-probability mass of x for binomial(n,p) with min_val=min_val. -inf if x is not in support.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of log-density for sequence encoded data.

Input value x must be obtained from a call to BinomialDataEncoder.seq_encode(data). Returns numpy array of log-density evaluated at all observations contained in encoded data x.

Parameters:: x (Tuple[np.ndarray, np.ndarray, np.ndarray, int, int]) – containing unique values in x, indices of ux to reconstruct x, numpy array of x, min value of x, and max value of x.
Returns:: Numpy array of log-density evaluated at all observations contained in encoded data x.
Return type:: ndarray

static backend_log_density_from_params(vals, n, p, min_val, engine)[source]

Engine-neutral binomial log-density from explicit parameters.

Parameters:

vals (Any)
n (Any)
p (Any)
min_val (int | None)
engine (Any)

Return type:

Any

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (tuple[ndarray, ndarray, ndarray, int, int])
engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)[source]

Return stacked binomial parameters for a homogeneous mixture kernel.

A stacked binomial mixture requires components to share the same trial count and shifted support. Mixtures with heterogeneous supports fall back to the generic kernel.

Parameters:

dists (Sequence[BinomialDistribution])
engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of binomial log densities.

Parameters:

x (tuple[ndarray, ndarray, ndarray, int, int])
params (dict[str, Any])
engine (Any)

Return type:

Any

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)[source]

Return stacked Binomial sufficient statistics using estimator-owned support bounds.

Parameters:

x (tuple[ndarray, ndarray, ndarray, int, int])
weights (Any)
params (dict[str, Any])
engine (Any)
estimator (Any)

Return type:

tuple[Any, Any, Any, Any]

support_size()[source]

n + 1 outcomes min_val + {0, ..., n}.

Return type:: int

to_fisher(**kwargs)[source]: Return the Binomial’s count-family Fisher view.

mean()[source]

Mean E[X] of the distribution.

Return type:: float

variance()[source]

Variance Var[X] of the distribution.

Return type:: float

cdf(x)[source]

Cumulative distribution function P(X <= x) over min_val + {0..n}.

Parameters:: x (float)
Return type:: float

skewness()[source]

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

Return type:: float

kurtosis()[source]

Excess kurtosis (1-6pq)/(npq).

Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q) over min_val + {0..n} (via scipy binom).

Parameters:: q (float)
Return type:: float

mode()[source]

Mode min_val + floor((n+1)p).

Return type:: float

sampler(seed=None)[source]

Returns BinomialSampler for generating samples from BinomialDistribution(n,p,min_val).

Parameters:

Optional[int] (seed) – Used to set seed on random number generator for sampling.
seed (int | None)

Returns:

BinomialSampler for BinomialDistribution with seed.

Return type:

BinomialSampler

estimator(pseudo_count=None)[source]

Creates a BinomialEstimator for estimating parameters of BinomialDistribution.

Parameters:: pseudo_count (Optional[float]) – If set, inflates counts for currently set sufficient statistic (p).
Returns:: BinomialEstimator object.
Return type:: BinomialEstimator

dist_to_encoder()[source]

Creates a BinomialDataEncoder object for seqeunce encoding data.

Returns:: BinomialDataEncoder object.
Return type:: BinomialDataEncoder

enumerator()[source]

Returns BinomialEnumerator iterating the support in descending probability order.

Return type:: BinomialEnumerator

quantized_index(max_bits, bin_width_bits=1.0)[source]

Build a bounded bit-quantized index by walking the binomial mode outward.

Parameters:

max_bits (float)
bin_width_bits (float)

Return type:

QuantizedEnumerationIndex

quantized_multi_cross_index(others, max_bits, bin_width_bits=1.0)[source]

Build an exact aligned cross-bin view over finite binomial supports.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

quantized_cross_index(other, max_bits, bin_width_bits=1.0)[source]

Build an exact aligned cross-bin view over two binomial supports.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

class BinomialEnumerator(dist)[source]

Bases: DistributionEnumerator

Parameters:: dist (BinomialDistribution)

class BinomialSampler(dist, seed=None)[source]

Bases: DistributionSampler

Parameters:

dist (BinomialDistribution)
seed (int | None)

sample(size=None)[source]

Draw samples from BinomialSampler.

Parameters:: size (Optional[int]) – Number of samples to draw from BinomialSampler (1 if size is None).
Returns:: An integer sample from BinomialDistribution(n,p,min_val), or List[int] of samples with length = size.
Return type:: int | list[int]

class BinomialAccumulator(max_val=None, min_val=None, name=None, keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Parameters:

max_val (int | None)
min_val (int | None)
name (str | None)
keys (str | None)

update(x, weight, estimate)[source]

Accumulates Binomial sufficient statistics for weighted single observation.

Add x*weight to attribute sum, and increase the count by weight.

Parameters:

x (int) – Data observed.
weight (float) – Weight for observation.
estimate (Optional[BinomialDistribution]) – Previous estimate of BinomialDistribution obtained from prior data.

Returns:

None (updates BinomialAccumulator sufficient statistics.)

Return type:

None

initialize(x, weight, rng)[source]

Initialize BinomialAccumulator sufficient statistics for one weighted observation.

Parameters:

x (int) – Data observed.
weight (float) – Weight for observation.
rng (Optional[RandomState]) – RandomState not needed. No randomness in initialization.

Returns:

None (updates BinomialAccumulator sufficient statistics.)

Return type:

None

seq_update(x, weights, estimate)[source]

Accumulates Binomial sufficient statistics for encoded sequence.

Parameters:

x (E) – Encoded sequence of observations.
weights (np.ndarray) – Numpy array of floats for weighting each observation.
estimate (Optional[BinomialDistribution]) – Previous estimate of BinomialDistribution obtained from prior data.:

Returns:

None

Return type:

None

seq_update_engine(x, weights, estimate, engine)[source]

Engine-resident accumulation of count/sum statistics (numpy or torch).

The weighted sum and count reductions run on the active engine; the scalar min/max support bounds remain host bookkeeping. Matches seq_update.

Parameters:

x (tuple[ndarray, ndarray, ndarray, int, int])
weights (Any)
estimate (BinomialDistribution | None)
engine (Any)

Return type:

None

seq_initialize(x, weights, rng)[source]

Vectorized initialization of BinomialAccumulator sufficient statistics with weights.

Calls seq_update().

Parameters:

x (E) – Encoded sequence of observations.
weights (np.ndarray) – Numpy array of floats for weighting each observation.
rng (Optional[RandomState]) – RandomState not needed. No randomness in initialization.

Returns:

None

Return type:

None

combine(suff_stat)[source]

Combine the sufficient statistics of BinomialAccumulator with suff_stat.

Parameters:: suff_stat (Tuple[float, float, Optional[int], Optional[int]]) – Count, sum of observations, optional min_val observed, and optional max_val observed.
Returns:: None
Return type:: BinomialAccumulator

value()[source]

Returns the sufficient statistics, and member variables min_val and max_val.

Returns:

Tuple[float,float, Optional[int], Optional[int]] containing suff stats count, sum and attributes min_val: max_val if they are not None.

Return type:

tuple[float, float, int | None, int | None]

from_value(x)[source]

Set BinomialAccumulator suff stats and member variables from suff_stat tuple defined in value().

Takes tuple of (count, sum, min_val, max_val) for setting values of BinomialAccumulator.

Parameters:: x (Tuple[float,float, Optional[int], Optional[int]]) – containing suff stats count, sum and attributes min_val max_val if they are not None.
Returns:: None, sets sufficient statistics and member variables.
Return type:: BinomialAccumulator

scale(c)[source]

Scale linear count/sum statistics while preserving support bounds.

Parameters:: c (float)
Return type:: BinomialAccumulator

key_merge(stats_dict)[source]

Combines the sufficient statistics of BinomialAccumulators that have the same key value.

Parameters:: stats_dict (Dict[str, Any]) – Dictionary for mapping keys to BinomialAccumulators.
Returns:: None
Return type:: None

key_replace(stats_dict)[source]

Set sufficient statistics of object instance to matching instances with matching keys.

Parameters:: stats_dict (Dict[str, Any]) – Maps member variable key to BinomialAccumualator with same key.
Returns:: None
Return type:: None

acc_to_encoder()[source]

Create BinomialDataEncoder object for encoding data.

Note: Used for seq_initialize.

Returns:: BinomialDataEncoder()
Return type:: BinomialDataEncoder

class BinomialAccumulatorFactory(max_val=None, min_val=0, name=None, keys=None)[source]

Bases: StatisticAccumulatorFactory

Parameters:

max_val (int | None)
min_val (int | None)
name (str | None)
keys (str | None)

make()[source]

Creates a BinomialAccumulator object.

Returns:: BinomialAccumulator.
Return type:: BinomialAccumulator

class BinomialEstimator(max_val=None, min_val=0, pseudo_count=None, suff_stat=None, name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

Parameters:

max_val (int | None)
min_val (int | None)
pseudo_count (float | None)
suff_stat (float | None)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

accumulator_factory()[source]

Creates a BinomialAccumulatorFactory object from member varaibles.

Returns:: BinomialAccumulatorFactory
Return type:: BinomialAccumulatorFactory

model_log_density(model)[source]

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

Parameters:: model (BinomialDistribution)
Return type:: float

estimate(nobs, suff_stat)[source]

Estimate a BinomialDistribution from BinomialEstimator using sufficient statistics in suff_stat.

Note: nobs is not used here. Kept for consistency with other ParameterEstimators.

Memeber variable suff_stat is simply the proportion (p) of the BinomialDistributon passed to BinomalEstimator. The pseudo_count is used to inflate (p) in estimation.

Parameters:

nobs (Optional[float]) – Not used.
suff_stat (Tuple[float, float, Optional[int], Optional[int]]) – Tuple of count, sum, min_val max_val, obtained from aggregation of data.

Returns:

BinomialDistribution estimated from suff_stat input and member variables suff_stat and pseudo_count.

class BinomialDataEncoder[source]

Bases: DataSequenceEncoder

BinomialDataEncoder object used to encode Sequence[int] or ndarray[int].

seq_encode(x)[source]

Encode List[int] for vectorized seq calls in Accumulator and Distribution.

Parameters:

x (List[int]) – List of integers.

Returns:

Tuple[np.ndarray, np.ndarray, np.ndarray, int, int] containing unique values in x, indices of ux to: reconstruct x, numpy array of x, min value of x, and max value of x.

Return type:

tuple[ndarray, ndarray, ndarray, int, int]