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)[source]

Bases: FixedFisherView

Fixed Fisher view whose statistics are the binary feature indicators.

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')[source]

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()[source]: Declare generic table-kernel capabilities for finite IBP rows.

classmethod compute_declaration()[source]: Return the structured declaration for finite IBP parameters and statistics.

density(x)[source]

Return the probability density or mass at a single observation.

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

density_semantics()[source]: Return that plug-in densities use posterior mean feature probabilities.

log_density(x)[source]

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

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

expected_log_density(x)[source]

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

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

seq_log_density(x)[source]

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

Parameters:: x (ndarray)
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Return vectorized expected log-density values for encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

seq_local_elbo(x)[source]

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

Parameters:: x (ndarray)
Return type:: ndarray

enumerator()[source]

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)[source]: Return this distribution’s own Fisher view.

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:: seed (int | None)
Return type:: IndianBuffetProcessSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:: pseudo_count (float | None)
Return type:: IndianBuffetProcessEstimator

dist_to_encoder()[source]

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

Return type:: IndianBuffetProcessDataEncoder

class IndianBuffetProcessEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate finite IBP feature rows in descending plug-in probability order.

Parameters:: dist (IndianBuffetProcessDistribution)

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

Bases: DistributionSampler

Sampler for finite-truncated IBP feature rows.

Parameters:

dist (IndianBuffetProcessDistribution)
seed (int | None)

sample(size=None)[source]

Draw one feature row or size iid feature rows.

Parameters:: size (int | None)
Return type:: list[int] | list[list[int]]

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

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)[source]

Update weighted feature-use counts from one row.

Parameters:

x (Any)
weight (float)
estimate (IndianBuffetProcessDistribution | None)

Return type:

None

initialize(x, weight, rng)[source]

Initialize feature-use counts from one row.

Parameters:

x (Any)
weight (float)
rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)[source]

Update weighted feature-use counts from encoded rows.

Parameters:

x (ndarray)
weights (ndarray)
estimate (IndianBuffetProcessDistribution | None)

Return type:

None

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

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)[source]

Initialize feature-use counts from encoded rows.

Parameters:

x (ndarray)
weights (ndarray)
rng (RandomState | None)

Return type:

None

combine(suff_stat)[source]

Merge feature-use counts, total count, and alpha metadata.

Parameters:: suff_stat (tuple[ndarray, float, float | None])
Return type:: IndianBuffetProcessAccumulator

value()[source]

Return feature-use counts, total count, and alpha metadata.

Return type:: tuple[ndarray, float, float | None]

from_value(x)[source]

Restore feature-use counts, total count, and alpha metadata.

Parameters:: x (tuple[ndarray, float, float | None])
Return type:: IndianBuffetProcessAccumulator

scale(c)[source]

Scale additive counts while preserving the IBP concentration metadata.

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

key_merge(stats_dict)[source]

Merge this accumulator into stats_dict under its configured key.

Parameters:: stats_dict (dict[str, Any])
Return type:: None

key_replace(stats_dict)[source]

Replace this accumulator’s state from keyed statistics when present.

Parameters:: stats_dict (dict[str, Any])
Return type:: None

acc_to_encoder()[source]

Return the encoder compatible with finite IBP sufficient statistics.

Return type:: IndianBuffetProcessDataEncoder

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

Bases: StatisticAccumulatorFactory

Factory for IBP accumulators.

Parameters:

num_features (int)
alpha (float)
keys (str | None)
data_format (str)

make()[source]

Create an empty finite IBP accumulator.

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')[source]

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()[source]

Return a factory for finite IBP sufficient-statistic accumulators.

Return type:: IndianBuffetProcessAccumulatorFactory

estimate(nobs, suff_stat)[source]

Update the variational Beta posterior and optional concentration parameter.

Parameters:

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

Return type:

IndianBuffetProcessDistribution

model_log_density(model)[source]

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')[source]

Bases: DataSequenceEncoder

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

Parameters:

num_features (int)
data_format (str)

seq_encode(x)[source]

Validate and encode dense or sparse feature rows as a boolean matrix.

Parameters:: x (Sequence[Any] | ndarray)
Return type:: ndarray