mixle.stats.latent.indian_buffet_process module

Indian buffet process finite truncation with variational Bayes estimation.

This module implements the finite Beta-Bernoulli truncation of the Indian buffet process (IBP). With K features and concentration alpha,

pi_k ~ Beta(alpha / K, 1) z_nk | pi_k ~ Bernoulli(pi_k)

Rows z_n may be supplied either as dense binary vectors of length K or as sparse lists/sets of active feature indices. Estimation is variational Bayes with a factorized posterior q(pi_k) = Beta(a_k, b_k). The local variational factor for an observed feature row is deterministic, so the accumulator gathers weighted feature-use counts and the estimator performs the conjugate Beta update.

class IndianBuffetProcessFisherView(dist)

Bases: FixedFisherView

Parameters:

dist (Any)

class IndianBuffetProcessDistribution(num_features, alpha=1.0, beta_params=None, feature_probs=None, min_prob=1.0e-128, name=None, keys=None, data_format='auto')

Bases: SequenceEncodableProbabilityDistribution

Finite-truncated Indian buffet process over binary feature rows.

Parameters:

• num_features (int) – Truncation level K.

• alpha (float) – IBP concentration parameter.

• beta_params (Sequence[Sequence[float]] | ndarray | None) – Optional (K, 2) variational Beta parameters for q(pi_k). If omitted, the prior Beta(alpha / K, 1) is used.

• feature_probs (Sequence[float] | ndarray | None) – Optional plug-in feature probabilities. When supplied without beta_params, a lightweight Beta posterior with matching mean is created for expected-log-density calls.

• min_prob (float) – Minimum plug-in probability used when feature_probs are given.

• name (str | None) – Optional distribution name.

• keys (str | None) – Optional key for tying sufficient statistics.

• data_format (str) – ‘dense’, ‘sparse’, or ‘auto’ input interpretation.

classmethod compute_capabilities()

classmethod compute_declaration()

density(x)

Return the probability density or mass at a single observation.

Parameters:

x (Any)

Return type:

float

density_semantics()

What log_density returns relative to the true log-density (default: exact).

Override to declare that this distribution’s log_density is a variational lower bound (ELBO), an upper bound, or an approximation rather than the exact log p(x). This is surfaced as the ExactDensity capability and noted in mixle.describe(), so code that needs an exact likelihood can require(x, ExactDensity) instead of silently trusting a bound.

log_density(x)

Plug-in log-density of one feature row using E_q[pi_k].

Parameters:

x (Any)

Return type:

float

expected_log_density(x)

VB expected log-density E_q[log p(z | pi)] for one observed row.

Parameters:

x (Any)

Return type:

float

seq_log_density(x)

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

Parameters:

x (ndarray)

Return type:

ndarray

backend_seq_log_density(x, engine)

Engine-neutral vectorized plug-in log-density for encoded feature rows.

Parameters:

• x (ndarray)

• engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)

Return stacked finite-IBP parameters for equal-feature mixtures.

Parameters:

• dists (Sequence[IndianBuffetProcessDistribution])

• engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)

Return an (n, k) matrix of finite-IBP component log densities.

Parameters:

• x (ndarray)

• params (dict[str, Any])

• engine (Any)

Return type:

Any

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)

Return component-stacked legacy (feature_counts, total_count, alpha) statistics.

Parameters:

• x (ndarray)

• weights (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, Any, Any]

seq_expected_log_density(x)

Return vectorized expected log-density values for encoded observations.

Parameters:

x (ndarray)

Return type:

ndarray

seq_local_elbo(x)

Per-row VB contribution; rows are observed, so there is no local entropy.

Parameters:

x (ndarray)

Return type:

ndarray

enumerator()

Enumerate feature rows in descending probability order.

The plug-in row density factorizes over features – log p(z) = sum_k [z_k log pi_k + (1-z_k) log(1-pi_k)] with pi_k = E_q[feature_probs] – so the truncated IBP row is a product of independent Bernoulli features and enumerates by best-first over the per-feature supports (the same structure as the Erdos-Renyi graph). Rows are emitted in the configured data_format (a dense 0/1 list, or a sorted list of active feature indices when sparse), each carrying its exact log_density.

Return type:

DistributionEnumerator

to_fisher(**kwargs)

Return this distribution’s own Fisher view.

sampler(seed=None)

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

IndianBuffetProcessSampler

estimator(pseudo_count=None)

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

IndianBuffetProcessEstimator

dist_to_encoder()

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

Return type:

IndianBuffetProcessDataEncoder

class IndianBuffetProcessEnumerator(dist)

Bases: DistributionEnumerator

Parameters:

dist (IndianBuffetProcessDistribution)

class IndianBuffetProcessSampler(dist, seed=None)

Bases: DistributionSampler

Sampler for finite-truncated IBP feature rows.

Parameters:

• dist (IndianBuffetProcessDistribution)

• seed (int | None)

sample(size=None)

Draw observations.

Combinator samplers (mixture/sequence/…) accept batched. With batched=True (the default) each child stream is drawn in one vectorized call instead of a per-draw Python loop – far faster. Because every child sampler owns an independent RandomState, batching consumes each stream in the same order as the loop, so the draws are identical to the legacy path. batched=False forces that legacy per-draw loop as a guaranteed- stable reference. Leaf samplers are already vectorized and ignore the flag.

Parameters:

size (int | None)

Return type:

list[int] | list[list[int]]

class IndianBuffetProcessAccumulator(num_features, alpha=1.0, keys=None, data_format='auto')

Bases: SequenceEncodableStatisticAccumulator

Accumulates weighted feature-use counts for the IBP VB update.

Parameters:

• num_features (int)

• alpha (float)

• keys (str | None)

• data_format (str)

update(x, weight, estimate)

Parameters:

• x (Any)

• weight (float)

• estimate (IndianBuffetProcessDistribution | None)

Return type:

None

initialize(x, weight, rng)

Parameters:

• x (Any)

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Parameters:

• x (ndarray)

• weights (ndarray)

• estimate (IndianBuffetProcessDistribution | None)

Return type:

None

seq_update_engine(x, weights, estimate, engine)

Engine-resident accumulation of weighted feature-use counts (numpy or torch).

The weighted feature counts are reduced via a weight-vector / binary-matrix product on the active engine; the alpha metadata is host bookkeeping. Matches seq_update.

Parameters:

• x (ndarray)

• weights (Any)

• estimate (IndianBuffetProcessDistribution | None)

• engine (Any)

Return type:

None

seq_initialize(x, weights, rng)

Parameters:

• x (ndarray)

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Parameters:

suff_stat (tuple[ndarray, float, float | None])

Return type:

IndianBuffetProcessAccumulator

value()

Return type:

tuple[ndarray, float, float | None]

from_value(x)

Parameters:

x (tuple[ndarray, float, float | None])

Return type:

IndianBuffetProcessAccumulator

scale(c)

Scale additive counts while preserving the IBP concentration metadata.

Parameters:

c (float)

Return type:

IndianBuffetProcessAccumulator

key_merge(stats_dict)

Pool this accumulator’s statistics into stats_dict under its merge key.

The structural default implements the common single-key pattern: store the accumulator under self.keys the first time the key is seen, else combine into the one already there. Accumulators with several named keys (e.g. an HMM’s init/trans/state keys) or a non-accumulator stats payload override this. A keys of None (the default) is a no-op.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)

Replace this accumulator’s statistics from the pooled stats_dict entry (see key_merge).

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()

Return type:

IndianBuffetProcessDataEncoder

class IndianBuffetProcessAccumulatorFactory(num_features, alpha=1.0, keys=None, data_format='auto')

Bases: StatisticAccumulatorFactory

Factory for IBP accumulators.

Parameters:

• num_features (int)

• alpha (float)

• keys (str | None)

• data_format (str)

make()

Return type:

IndianBuffetProcessAccumulator

class IndianBuffetProcessEstimator(num_features, alpha=1.0, pseudo_count=None, suff_stat=None, estimate_alpha=True, min_alpha=1.0e-12, max_alpha=1.0e12, min_prob=1.0e-128, name=None, keys=None, data_format='auto')

Bases: ParameterEstimator

Variational Bayes estimator for the finite-truncated IBP.

pseudo_count follows the convention used by other mixle.stats Bernoulli estimators: if suff_stat is supplied, it is treated as a prior probability vector and re-weighted by pseudo_count; otherwise pseudo_count is centered at the IBP prior mean alpha / (alpha + K).

Parameters:

• num_features (int)

• alpha (float)

• pseudo_count (float | None)

• suff_stat (Sequence[float] | ndarray | None)

• estimate_alpha (bool)

• min_alpha (float)

• max_alpha (float)

• min_prob (float)

• name (str | None)

• keys (str | None)

• data_format (str)

accumulator_factory()

Return type:

IndianBuffetProcessAccumulatorFactory

estimate(nobs, suff_stat)

Parameters:

• nobs (float | None)

• suff_stat (tuple[ndarray, float, float | None])

Return type:

IndianBuffetProcessDistribution

model_log_density(model)

Global VB term E_q[log p(pi | alpha)] + H[q(pi)].

Parameters:

model (IndianBuffetProcessDistribution)

Return type:

float

class IndianBuffetProcessDataEncoder(num_features, data_format='auto')

Bases: DataSequenceEncoder

Encode dense or sparse IBP rows as a dense boolean matrix.

Parameters:

• num_features (int)

• data_format (str)

seq_encode(x)

Encode the iid observation sequence x for vectorized evaluation.

Parameters:

x (Sequence[Any] | ndarray)

Return type:

ndarray