mixle.stats.combinator.null_dist module

Neutral likelihood factor used for absent structural model slots.

NullDistribution is the multiplicative identity for likelihood composition: it contributes log-score zero for every input and carries no parameters. It is therefore not a normalized generative probability distribution and cannot be sampled or enumerated. Use PointMassDistribution(None) for a proper singleton law whose only possible value is None.

Notes

The density evaluates to 1.0 for any value (Any data type). Sequence encodings retain only the observation count.

exception NeutralFactorError[source]

Bases: TypeError

Raised when a neutral likelihood identity is used as a generative law.

class NullDistribution(name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Non-generative likelihood identity assigning log-score zero to every observation.

Parameters:

name (str | None)

classmethod compute_capabilities()[source]

Declare backend support for the zero-cost null distribution.

classmethod compute_declaration()[source]

Return the generated-compute declaration for the null distribution.

density(x)[source]

Density of NullDistribution. Always 1.0.

Parameters:

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

Returns:

1.0 for any input.

Return type:

float

density_semantics()[source]

Identify this exact score as a non-generative likelihood factor.

log_density(x)[source]

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

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

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

Parameters:
Return type:

Any

classmethod backend_stacked_params(dists, engine)[source]

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

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

Parameters:
Return type:

Any

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return empty legacy statistics for each null component.

Parameters:
Return type:

tuple[None, …]

sampler(seed=None)[source]

Reject generation from a likelihood identity with no normalized sample space.

Parameters:

seed (int | None)

Return type:

NullSampler

estimator(pseudo_count=None)[source]

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

Return the encoder used for null-distribution observations.

Return type:

NullDataEncoder

enumerator()[source]

Reject enumeration because a neutral factor has no probability support.

Return type:

NullEnumerator

quantized_index(max_bits, bin_width_bits=1.0)[source]

Reject indexing because a neutral factor has no probability support.

Parameters:
Return type:

QuantizedEnumerationIndex

quantized_multi_cross_index(others, max_bits, bin_width_bits=1.0)[source]

Reject cross-indexing because neutral factors have no probability support.

Parameters:

bin_width_bits (float)

Return type:

QuantizedCrossIndex

quantized_cross_index(other, max_bits, bin_width_bits=1.0)[source]

Reject pairwise cross-indexing because neutral factors have no probability support.

Parameters:

bin_width_bits (float)

Return type:

QuantizedCrossIndex

class NullEnumerator(dist)[source]

Bases: DistributionEnumerator

Deprecated guard that rejects enumeration of a neutral factor.

Parameters:

dist (NullDistribution)

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

Bases: DistributionSampler

Deprecated guard that rejects sampling from a neutral factor.

Parameters:

  • dist (NullDistribution)

  • seed (int | None)

sample(size=None, *, batched=True)[source]

Reject every draw from this non-generative compatibility guard.

Parameters:

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

  • batched (bool) – Compatibility flag (unused).

Return type:

None | list[None]

class NullAccumulator(keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulator for NullDistribution. Accumulates no sufficient statistics.

Parameters:

keys (str | None)

update(x, weight, estimate)[source]

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

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

Engine-neutral no-op accumulation for null statistics.

Return type:

None

initialize(x, weight, rng)[source]

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

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

Combine sufficient statistics (no-op).

Parameters:

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

Returns:

Self, unchanged.

Return type:

NullAccumulator

value()[source]

Returns None (the NullAccumulator has no sufficient statistics).

Return type:

None

from_value(x)[source]

Set accumulator from sufficient statistics (no-op).

Parameters:

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

Returns:

Self, unchanged.

Return type:

NullAccumulator

key_merge(stats_dict)[source]

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

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

Return the encoder associated with this accumulator.

Return type:

NullDataEncoder

class NullAccumulatorFactory(keys=None)[source]

Bases: StatisticAccumulatorFactory

Factory for null accumulators.

Parameters:

keys (str | None)

make()[source]

Return a fresh null accumulator.

Return type:

NullAccumulator

class NullEstimator(pseudo_count=None, suff_stat=None, name=None, keys=None)[source]

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

Return a factory for null accumulators.

Return type:

NullAccumulatorFactory

estimate(nobs, suff_stat=None)[source]

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

Bases: DataSequenceEncoder

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

seq_encode(x)[source]

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

row_count(x)[source]

Return the exact number of rows stored by the null encoding.

Parameters:

x (Any)

Return type:

int