mixle.stats.combinator.null_dist module

Neutral null distribution used for optional structural slots.

The null distribution and its related classes fill optional model slots while preserving the standard distribution, sampler, accumulator, estimator, and encoder interfaces.

Notes

The density evaluates to 1.0 for any value (Any data type). The sampler generates None for any size input. Sequence encodings return None for any input.

class NullDistribution(name=None)

Bases: SequenceEncodableProbabilityDistribution

Place-holder distribution assigning density 1.0 (log-density 0.0) to any observation (Any data type).

Parameters:

name (str | None)

classmethod compute_capabilities()

Declare backend support for the zero-cost null distribution.

classmethod compute_declaration()

Return the generated-compute declaration for the null distribution.

density(x)

Density of NullDistribution. Always 1.0.

Parameters:

x (Optional[Any]) – Observation of any type (ignored).

Returns:

1.0 for any input.

Return type:

float

log_density(x)

Log-density of NullDistribution. Always 0.0.

Parameters:

x (Optional[Any]) – Observation of any type (ignored).

Returns:

0.0 for any input.

Return type:

float

seq_log_density(x)

Vectorized log-density evaluated at sequence encoded input x. Always 0.0.

Parameters:

x (Optional[Any]) – Sequence encoded data; NullDataEncoder returns the sequence length.

Returns:

A zero vector with one entry per encoded observation.

Return type:

ndarray

backend_seq_log_density(x, engine)

Engine-neutral vectorized log-density: zero for every encoded row.

Parameters:

• x (Any | None)

• engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)

Return stacked parameters for homogeneous null mixtures.

Parameters:

• dists (tuple[NullDistribution, ...])

• engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)

Return an (n, k) zero matrix for null-component log densities.

Parameters:

• x (Any | None)

• params (dict[str, Any])

• engine (Any)

Return type:

Any

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)

Return empty legacy statistics for each null component.

Parameters:

• x (Any | None)

• weights (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[None, …]

sampler(seed=None)

Create a sampler for the null distribution.

Parameters:

seed (Optional[int]) – Seed for random number generator (unused).

Returns:

NullSampler that always samples None.

Return type:

NullSampler

estimator(pseudo_count=None)

Create an estimator for the null distribution.

Parameters:

pseudo_count (Optional[float]) – Kept for interface consistency (has no effect on estimation).

Returns:

NullEstimator configured with this distribution’s name.

Return type:

NullEstimator

dist_to_encoder()

Return the encoder used for null-distribution observations.

Return type:

NullDataEncoder

enumerator()

Return an enumerator for the singleton null support.

Return type:

NullEnumerator

quantized_index(max_bits, bin_width_bits=1.0)

Build the single-item bounded bit-quantized index for NullDistribution.

Parameters:

• max_bits (float)

• bin_width_bits (float)

Return type:

QuantizedEnumerationIndex

quantized_multi_cross_index(others, max_bits, bin_width_bits=1.0)

Build an exact aligned cross-bin view for null distributions.

Parameters:

bin_width_bits (float)

Return type:

QuantizedCrossIndex

quantized_cross_index(other, max_bits, bin_width_bits=1.0)

Build an exact aligned cross-bin view for two null distributions.

Parameters:

bin_width_bits (float)

Return type:

QuantizedCrossIndex

class NullEnumerator(dist)

Bases: DistributionEnumerator

Yields the single value None with probability one, matching NullSampler.sample().

Parameters:

dist (NullDistribution)

class NullSampler(dist, seed=None)

Bases: DistributionSampler

Sampler for the NullDistribution. Always returns None.

Parameters:

• dist (NullDistribution)

• seed (int | None)

sample(size=None)

Returns None for any requested size.

Parameters:

size (Optional[int]) – Number of samples requested (ignored).

Returns:

None.

Return type:

None

class NullAccumulator(keys=None)

Bases: SequenceEncodableStatisticAccumulator

Accumulator for NullDistribution. Accumulates no sufficient statistics.

Parameters:

keys (str | None)

update(x, weight, estimate)

No-op update. Nothing is accumulated for the NullDistribution.

Parameters:

• x (Optional[Any]) – Observation of any type (ignored).

• weight (float) – Weight for observation (ignored).

• estimate (Optional[NullDistribution]) – Previous estimate (ignored).

Return type:

None

seq_update(x, weights, estimate)

No-op vectorized update. Nothing is accumulated for the NullDistribution.

Parameters:

• x (Optional[Any]) – Sequence encoded data (ignored).

• weights (np.ndarray) – Weights for observations (ignored).

• estimate (Optional[NullDistribution]) – Previous estimate (ignored).

Return type:

None

seq_update_engine(x, weights, estimate, engine)

Engine-neutral no-op accumulation for null statistics.

Return type:

None

initialize(x, weight, rng)

No-op initialization for a single observation.

Parameters:

• x (Optional[Any]) – Observation of any type (ignored).

• weight (float) – Weight for observation (ignored).

• rng (Optional[np.random.RandomState]) – Random number generator (unused).

Return type:

None

seq_initialize(x, weights, rng)

No-op vectorized initialization.

Parameters:

• x (Optional[Any]) – Sequence encoded data (ignored).

• weights (np.ndarray) – Weights for observations (ignored).

• rng (np.random.RandomState) – Random number generator (unused).

Return type:

None

combine(suff_stat)

Combine sufficient statistics (no-op).

Parameters:

suff_stat (Optional[Any]) – Sufficient statistics (ignored).

Returns:

Self, unchanged.

Return type:

NullAccumulator

value()

Returns None (the NullAccumulator has no sufficient statistics).

Return type:

None

from_value(x)

Set accumulator from sufficient statistics (no-op).

Parameters:

x (Optional[Any]) – Sufficient statistics (ignored).

Returns:

Self, unchanged.

Return type:

NullAccumulator

key_merge(stats_dict)

Register the key in stats_dict (the NullAccumulator stores no sufficient statistics).

Parameters:

stats_dict (Dict[str, Any]) – Dict mapping keys to shared sufficient statistics.

Returns:

None.

Return type:

None

key_replace(stats_dict)

No-op kept for interface consistency (the NullAccumulator stores no sufficient statistics).

Parameters:

stats_dict (Dict[str, Any]) – Dict mapping keys to shared sufficient statistics (ignored).

Returns:

None.

Return type:

None

acc_to_encoder()

Return the encoder associated with this accumulator.

Return type:

NullDataEncoder

class NullAccumulatorFactory(keys=None)

Bases: StatisticAccumulatorFactory

Factory for null accumulators.

Parameters:

keys (str | None)

make()

Return a fresh null accumulator.

Return type:

NullAccumulator

class NullEstimator(pseudo_count=None, suff_stat=None, name=None, keys=None)

Bases: ParameterEstimator

Estimator that always produces a NullDistribution regardless of the data.

Parameters:

• pseudo_count (float | None)

• suff_stat (Any | None)

• name (str | None)

• keys (str | None)

accumulator_factory()

Return a factory for null accumulators.

Return type:

NullAccumulatorFactory

estimate(nobs, suff_stat=None)

Returns a NullDistribution; arguments are ignored.

Parameters:

• nobs (Optional[float]) – Number of observations (ignored).

• suff_stat (Optional[Any]) – Sufficient statistics (ignored).

Returns:

NullDistribution carrying this estimator’s name.

Return type:

NullDistribution

class NullDataEncoder

Bases: DataSequenceEncoder

Data encoder for the NullDistribution. Encodes any sequence as its length.

seq_encode(x)

Encode a sequence of observations as its length.

Parameters:

x (Any) – Sequence of observations of any type (ignored).

Returns:

Number of observations in the sequence.

Return type:

int