mixle.stats.combinator.optional module

Optional distributions for explicit missing-value mass.

This distribution assigns a probability (p) to data being missing. With probability (1-p) the data is assumed to come from a base distribution set by the user.

The OptionalDistribution allows for potentially missing data. The value p (the probability of being missing) must be specified to sample from the distribution.

class OptionalDistribution(dist, p=None, missing_value=None, name=None, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Mixture-style wrapper that models missing observations explicitly.

Parameters:

  • dist (SequenceEncodableProbabilityDistribution)

  • p (float | None)

  • missing_value (Any)

  • name (str | None)

  • prior (tuple[Any, Any] | None)

compute_capabilities()[source]

Return compute capabilities inherited from the observed-data distribution.

get_prior()[source]

Return the joint prior as (p_prior, dist_prior).

Return type:

tuple[Any, Any]

set_prior(prior)[source]

Distribute the joint prior (p_prior, dist_prior) to the missing probability and base dist.

prior=None is a no-op (point model, existing behavior byte-identical). Otherwise the first element is a conjugate Beta prior on p (caching the digamma expectations used by expected_log_density) and the second is pushed to the base distribution’s set_prior.

Parameters:

prior (tuple[Any, Any] | None)

Return type:

None

expected_log_density(x)[source]

Posterior-expected log-density E_q[log p(x)] at x.

With a conjugate Beta prior on p the expectation over p is available in closed form via digamma terms (missing => da - dab; observed => db - dab + dist.expected_log_density(x)); otherwise this falls back to the plug-in log_density.

Parameters:

x (T)

Return type:

float

seq_expected_log_density(x)[source]

Vectorized posterior-expected log-density; falls back to seq_log_density without a prior.

Parameters:

x (tuple[int, ndarray, ndarray, E])

Return type:

ndarray

compute_declaration()[source]

Return a structured declaration for the optional missingness wrapper.

density(x)[source]

Evaluate the density of the Optional distribution at x.

See log_density() for details.

Parameters:

x (T) – Observation from base dist or missing value.

Returns:

Density at x.

Return type:

float

density_semantics()[source]

Return density semantics for the observed branch of the wrapper.

log_density(x)[source]

Evalute the log density of the Optional distribution at x.

If x is a missing value: return log(p) if p is not None, else return 0.0 If x is not the missing_value: if p is not None, return the log_denisty(x) at base dist + log(1-p) else: return

log_density(x).

Parameters:

x (T) – Observation from base dist or missing value.

Returns:

Log-density at x.

Return type:

float

seq_log_density(x)[source]

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

Parameters:

x (tuple[int, ndarray, ndarray, E])

Return type:

ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for optional encoded data.

Parameters:
Return type:

Any

gradient_fit_state(engine, torch, leaves, recurse, tensor_param)[source]

Return distribution-owned state for autograd fitting.

Parameters:
Return type:

Any

classmethod backend_stacked_params(dists, engine)[source]

Return stacked optional-wrapper parameters for homogeneous mixture kernels.

Parameters:
Return type:

dict[str, Any]

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

Return an (n, k) matrix of optional-wrapper log densities.

Parameters:
Return type:

Any

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

Return per-component legacy optional-wrapper sufficient statistics.

Parameters:
Return type:

tuple[Any, …]

to_fisher(**kwargs)[source]

Fisher view for the optional/missing-gate.

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

OptionalSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

OptionalEstimator

dist_to_encoder()[source]

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

Return type:

OptionalDataEncoder

enumerator()[source]

Returns an OptionalEnumerator iterating the support (including the missing value) in descending probability order.

Return type:

OptionalEnumerator

class OptionalEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate the optional support by merging missing mass with observed support.

Parameters:

dist (OptionalDistribution)

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

Bases: DistributionSampler

Sample from an optional distribution by first drawing the missingness gate.

Parameters:

  • dist (OptionalDistribution)

  • seed (int | None)

sample(size=None)[source]

Draw one observation or a list of observations from the optional mixture.

Parameters:

size (int | None)

class OptionalEstimatorAccumulator(accumulator, missing_value=None, name=None, keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulate missing/observed gate weights plus observed-branch statistics.

Parameters:

  • accumulator (SequenceEncodableStatisticAccumulator)

  • missing_value (Any)

  • name (str | None)

  • keys (str | None)

update(x, weight, estimate)[source]

Update from a single observation, routing observed values to the child accumulator.

Parameters:

  • x (T)

  • weight (float)

  • estimate (OptionalDistribution)

Return type:

None

initialize(x, weight, rng)[source]

Initialize from a single observation using the child initializer when observed.

Parameters:
Return type:

None

seq_update(x, weights, estimate)[source]

Update from encoded optional data and observation weights.

Parameters:
Return type:

None

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

Engine-resident E-step: missing/observed mass is summed on the active engine and the observed child accumulator is routed through the engine. Matches seq_update.

Parameters:
Return type:

None

seq_initialize(x, weights, rng)[source]

Initialize from encoded optional data and weights.

Parameters:
Return type:

None

combine(suff_stat)[source]

Merge missing/observed weights and child sufficient statistics.

Parameters:

suff_stat (tuple[list[float], SS])

Return type:

OptionalEstimatorAccumulator

value()[source]

Return gate weights together with observed-branch sufficient statistics.

Return type:

tuple[list[float], Any]

from_value(x)[source]

Restore gate weights and observed-branch sufficient statistics.

Parameters:

x (tuple[list[float], SS])

Return type:

OptionalEstimatorAccumulator

scale(c)[source]

Scale missing/observed weights and delegate observed statistics.

Parameters:

c (float)

Return type:

OptionalEstimatorAccumulator

key_replace(stats_dict)[source]

Replace keyed statistics in stats_dict with this accumulator state.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_merge(stats_dict)[source]

Merge this accumulator into stats_dict under the configured key.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()[source]

Return the optional encoder matching the wrapped child accumulator.

Return type:

OptionalDataEncoder

class OptionalEstimatorAccumulatorFactory(estimator, missing_value=None, keys=None, name=None)[source]

Bases: StatisticAccumulatorFactory

Create accumulators for optional missingness estimators.

Parameters:

  • estimator (ParameterEstimator)

  • missing_value (Any)

  • keys (str | None)

  • name (str | None)

make()[source]

Create an empty optional estimator accumulator.

Return type:

OptionalEstimatorAccumulator

class OptionalEstimator(estimator, missing_value=None, est_prob=False, pseudo_count=None, name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

Estimate optional missingness probability and observed-data distribution parameters.

Parameters:

  • estimator (ParameterEstimator)

  • missing_value (Any)

  • est_prob (bool)

  • pseudo_count (float | None)

  • name (str | None)

  • keys (str | None)

  • prior (tuple[Any, Any] | None)

accumulator_factory()[source]

Return an accumulator factory for optional sufficient statistics.

Return type:

OptionalEstimatorAccumulatorFactory

get_prior()[source]

Return the joint prior as (p_prior, dist_prior) from this estimator and the base estimator.

Return type:

tuple[Any, Any]

set_prior(prior)[source]

Distribute (p_prior, dist_prior) to this estimator’s p prior and the base estimator.

prior=None is a no-op (empirical/pseudo-count path stays byte-identical). The first element is a conjugate Beta prior on p; the second is pushed to the base estimator via set_prior.

Parameters:

prior (tuple[Any, Any] | None)

Return type:

None

model_log_density(model)[source]

Sum the Beta-prior log-density at p and the base estimator’s term (ELBO global term).

Parameters:

model (OptionalDistribution)

Return type:

float

estimate(nobs, suff_stat)[source]

Estimate an OptionalDistribution from missing/observed sufficient statistics.

Parameters:
Return type:

OptionalDistribution

class OptionalDataEncoder(encoder, missing_value=None)[source]

Bases: DataSequenceEncoder

Encode optional data as missing indices, observed indices, and child-encoded data.

Parameters:

  • encoder (DataSequenceEncoder)

  • missing_value (Any)

seq_encode(x)[source]

Split a sequence into missing positions and encoded observed values.

Parameters:

x (Sequence[T])

Return type:

tuple[int, ndarray, ndarray, Any]

OptionalAccumulator

alias of OptionalEstimatorAccumulator

OptionalAccumulatorFactory

alias of OptionalEstimatorAccumulatorFactory

class OptionalFisherView(dist)[source]

Bases: EmpiricalMetricFixedFisherView

Fisher view for optional distributions with gate and observed-branch statistics.

Parameters:

dist (Any)

mean_statistics(stats=None, model=True, **kwargs)[source]

Return model or empirical mean statistics for the optional Fisher view.

Parameters:
Return type:

ndarray

fisher_information(stats=None, diagonal=False, ridge=1.0e-8, **kwargs)[source]

Return Fisher information, falling back to empirical statistics when needed.

Parameters:
Return type:

ndarray

fisher_vectors(stats=None, metric='diagonal', center=None, fisher=None, ridge=1.0e-8, **kwargs)[source]

Return Fisher-whitened statistic vectors for optional observations.

Parameters:
Return type:

ndarray