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.

The two modes, and why only one of them is a law. p is optional, and leaving it out does not mean “p is zero” – it selects a different object:

  • p given – a normalized mixture: mass p on the sentinel, the base family scaled by 1-p everywhere else. It integrates to one, density_semantics() reports EXACT, and it samples.

  • p is None – the missing outcome is MARGINALIZED, i.e. log_density(sentinel) is 0.0 and the base density is passed through unscaled. This is a likelihood FACTOR conditioned on an externally modeled missingness mechanism, not a law: its total mass is 1 (the base) + 1 (the sentinel scored at probability one) = 2, sentinel rows cost exactly zero nats, and density_semantics() reports LIKELIHOOD_FACTOR to say so. It cannot be sampled (NonGenerativeOptionalError).

Two consequences worth knowing before choosing. First, .p reads 0.0 in the marginalized mode – has_p is the attribute that distinguishes “no rate was ever fitted” from “the rate was fitted and came out zero”, and repr prints p=None for the former. Second, the free sentinel rows mean a marginalized model cannot be compared on likelihood against a proper one over the same data: it wins by construction, by -log(p) nats per sentinel row, and the paired comparison helpers in mixle.inference (vuong_test, clarke_test, compare_elpd) take plain score arrays and so cannot see the flag that would have warned them. Auto-inference accordingly fits the rate for every sentinel it introduces (see mixle.utils.automatic.DatumNode.get_estimator()); the marginalized mode is for callers who ask for it deliberately.

exception NonGenerativeOptionalError[source]

Bases: TypeError

Raised when a marginalized optional likelihood factor is used to generate data.

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 child semantics for a proper gate or likelihood-factor semantics for MAR.

property marginalized_core

Return the wrapped law when this is a pure marginalization, else None.

Without a missingness rate this distribution is a likelihood factor: it contributes 1 where the value is absent rather than a normalized density over values-plus-missing. That makes it non-generative, but only because p was not supplied – the wrapped law is untouched, and giving p makes the whole thing generative again. Callers that need to tell “unnormalized because we are marginalizing over missingness” apart from “intrinsically cannot generate” (a scoring-only leaf) read this: the former returns its core, the latter has no such attribute.

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, *, batched=True)[source]

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

Parameters:
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[tuple[float, 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 own + wrapped-child statistics from the pooled stats_dict (see key_merge).

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_merge(stats_dict)[source]

Merge own statistics under self.keys and DELEGATE to the wrapped child.

The delegation is the point of the override: without it, a keyed estimator nested under an Optional never pooled at all (its key pass was unreachable – the dead-keys shape the keyed-protocol sweep hunts). The own-key pooling itself is the base-class canonical protocol.

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]

row_count(x)[source]

Validate the missing/present partition and return its declared observation count.

Parameters:

x (Any)

Return type:

int

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