mixle.stats.combinator.truncated module

Truncated-support combinator: restrict a base distribution to an allowed set, renormalized.

TruncatedDistribution wraps a base distribution and conditions it on a support restriction:

p(x) = p_base(x) / Z for x in the allowed support, else 0,

where Z = sum_{y allowed} p_base(y) is the retained mass. The restriction is given either as a finite forbidden set to exclude (Z = 1 - sum_f p_base(f) – works for an infinite base) or a finite allowed set to keep (Z = sum_a p_base(a)). It pairs with the Phase-1c support tools: the renormalizer is exactly the truncated tail/total the enumeration bounds reason about.

class TruncatedDistribution(base, allowed=None, forbidden=None, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A base distribution restricted to an allowed support and renormalized.

Parameters:

  • base (SequenceEncodableProbabilityDistribution)

  • allowed (Sequence[Any] | None)

  • forbidden (Sequence[Any] | None)

  • name (str | None)

  • keys (str | None)

density(x)[source]

Return the renormalized probability/density at x.

Parameters:

x (Any)

Return type:

float

log_density(x)[source]

Return log p_base(x) - log Z for allowed x, else -inf.

Parameters:

x (Any)

Return type:

float

seq_log_density(x)[source]

Return per-row truncated log-densities for an encoded batch.

Parameters:

x (tuple[Any, ndarray])

Return type:

ndarray

sampler(seed=None)[source]

Return a rejection sampler over the allowed support.

Parameters:

seed (int | None)

Return type:

TruncatedSampler

estimator(pseudo_count=None)[source]

Return an estimator that re-fits the base on the (in-support) data, keeping the truncation.

This is the fixed-truncation estimator: it maximizes the base likelihood over the observed (already in-support) data and re-wraps with the same support restriction. It does not solve the full truncated MLE (whose normalizer Z depends on the base parameters); use it when the truncation set is fixed and known, which is the typical censored/restricted-support case.

Parameters:

pseudo_count (float | None)

Return type:

TruncatedEstimator

dist_to_encoder()[source]

Return the data encoder (base encoding + an allowed-membership mask).

Return type:

TruncatedDataEncoder

support_size()[source]

Cardinality of the retained support (None if infinite).

Return type:

int | None

enumerator()[source]

Enumerate the allowed support in descending (renormalized) probability order.

Return type:

TruncatedEnumerator

class TruncatedEnumerator(dist)[source]

Bases: DistributionEnumerator

Filter the base enumeration to the allowed support, renormalized by -log Z.

Parameters:

dist (TruncatedDistribution)

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

Bases: DistributionSampler

Rejection sampler: draw from the base, keep only allowed values.

Parameters:

  • dist (TruncatedDistribution)

  • seed (int | None)

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

Draw one allowed value (or a list of size) by rejection.

With batched=True (default) base draws are taken in blocks sized from the running accept rate, instead of one per draw – far faster when the retained mass is small, with a clear diagnostic (accept rate, attempts) if the budget is exhausted. Set batched=False for the per-draw reference path. Batched draws differ in RNG-call order from the per-draw loop.

Parameters:
class TruncatedAccumulator(base_accumulator, keys=None)[source]

Bases: SingleChildAccumulator

Delegate accumulation to the base accumulator over in-support observations.

Parameters:

  • base_accumulator (SequenceEncodableStatisticAccumulator)

  • keys (str | None)

update(x, weight, estimate)[source]
Parameters:

  • x (Any)

  • weight (float)

  • estimate (TruncatedDistribution | None)

Return type:

None

seq_update(x, weights, estimate)[source]
Parameters:
Return type:

None

initialize(x, weight, rng)[source]
Parameters:
Return type:

None

seq_initialize(x, weights, rng)[source]
Parameters:
Return type:

None

acc_to_encoder()[source]
Return type:

DataSequenceEncoder

class TruncatedAccumulatorFactory(base_factory, keys=None)[source]

Bases: StatisticAccumulatorFactory

Factory for TruncatedAccumulator.

Parameters:

  • base_factory (StatisticAccumulatorFactory)

  • keys (str | None)

make()[source]
Return type:

TruncatedAccumulator

class TruncatedEstimator(base_estimator, allowed=None, forbidden=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Fixed-truncation estimator: fit the base on in-support data, re-wrap with the truncation.

Parameters:
accumulator_factory()[source]
Return type:

TruncatedAccumulatorFactory

estimate(nobs, suff_stat)[source]
Parameters:
Return type:

TruncatedDistribution

class TruncatedDataEncoder(dist)[source]

Bases: MaskedBaseEncoder

Encode observations via the base encoder, plus a boolean allowed-membership mask.

Parameters:

dist (TruncatedDistribution)