mixle.stats.combinator.null_dist module¶

Create, estimate, and sample from a null distribution.

Defines the NullDistribution, NullSampler, NullAccumulatorFactory, NullAccumulator, NullEstimator, and the NullDataEncoder classes for use with mixle.

The NullDistribution object and its related classes are space filling objects meant for consistency in type hints.

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

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

classmethod compute_declaration()[source]

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

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:

x (Any | None)
engine (Any)

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:

x (Any | None)
params (dict[str, Any])
engine (Any)

Return type:

Any

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

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

Create a NullSampler object.

Parameters:: seed (Optional[int]) – Seed for random number generator (unused).
Returns:: NullSampler object.
Return type:: NullSampler

estimator(pseudo_count=None)[source]

Create a NullEstimator object.

Parameters:: pseudo_count (Optional[float]) – Kept for interface consistency (has no effect on estimation).
Returns:: NullEstimator object.
Return type:: NullEstimator

dist_to_encoder()[source]

Returns a NullDataEncoder object for encoding sequences of data.

Return type:: NullDataEncoder

enumerator()[source]

Returns a NullEnumerator object enumerating the support of the NullDistribution.

Return type:: NullEnumerator

quantized_index(max_bits, bin_width_bits=1.0)[source]

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

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

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

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

class NullEnumerator(dist)[source]

Bases: DistributionEnumerator

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

Parameters:: dist (NullDistribution)

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

Bases: DistributionSampler

Sampler for the NullDistribution. Always returns None.

Parameters:

dist (NullDistribution)
seed (int | None)

sample(size=None)[source]

Returns None for any requested size.

Parameters:: size (Optional[int]) – Number of samples requested (ignored).
Returns:: None.
Return type:: 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]

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]

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]

Returns a NullDataEncoder object for encoding sequences of data.

Return type:: NullDataEncoder

class NullAccumulatorFactory(keys=None)[source]

Bases: StatisticAccumulatorFactory

Factory for creating NullAccumulator objects.

Parameters:: keys (str | None)

make()[source]

Returns a new NullAccumulator object.

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]

Returns a NullAccumulatorFactory for creating NullAccumulator objects.

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 object.

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