mixle.stats.combinator.weighted module¶

Weighted observation wrapper around a base distribution.

Data type: WeightedObservation[D] (tuple-compatible): an observation is a pair (value, weight) where value has the base data type and weight is finite, non-negative evidence metadata. The weight is explicitly not a random coordinate and does not enter the likelihood; it scales the observation’s sufficient-statistic contribution. Sampling and enumeration use the canonical neutral metadata value 1.0. Likelihood evaluations validate the metadata and delegate on the value:

P((x, w)) = P_base(x).

class WeightedObservation(value, weight)[source]

Bases: NamedTuple

A child value plus non-random, non-negative estimation-weight metadata.

Parameters:

value (Any)
weight (float)

value: Any: Alias for field number 0

weight: float: Alias for field number 1

class WeightedStatistics(child, effective_weight)[source]

Bases: NamedTuple

Child sufficient statistics plus their effective attached-times-external weight.

Parameters:

child (Any)
effective_weight (float)

child: Any: Alias for field number 0

effective_weight: float: Alias for field number 1

class WeightedDistribution(dist, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Distribution wrapper that attaches observation weights to a base distribution.

Parameters:

dist (SequenceEncodableProbabilityDistribution) – Base distribution for the observed values.
name (Optional[str]) – Optional distribution name.
keys (str | None)

dist

Base distribution for the observed values.

Type:: SequenceEncodableProbabilityDistribution

name

Optional distribution name.

Type:: Optional[str]

compute_capabilities()[source]: Delegate generated-compute support to the wrapped value distribution.

compute_declaration()[source]: Return the generated-compute declaration for the weighted wrapper.

density(x)[source]

Density of the base distribution at a weighted observation’s value.

Parameters:: x (D) – Observation value (weight excluded).
Returns:: Density of the base distribution at x.
Return type:: float

log_density(x)[source]

Log-density of the base distribution at a weighted observation’s value.

The observation weight does not enter the likelihood, so this is simply the base distribution’s log-density evaluated on the value.

Parameters:: x (D) – Observation value (weight excluded).
Returns:: Log-density of the base distribution at x.
Return type:: float

seq_log_density(x)[source]

Vectorized log-density of the base distribution on encoded values.

Parameters:: x (Tuple[E, np.ndarray]) – Sequence encoded values and weights from WeightedDataEncoder.
Returns:: Numpy array of base-distribution log-densities.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density delegated to the value distribution.

Parameters:

x (tuple[E, ndarray])
engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)[source]

Return stacked child parameters for homogeneous weighted-wrapper mixtures.

Parameters:

dists (Sequence[WeightedDistribution])
engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of child log densities, ignoring attached weights.

Parameters:

x (tuple[E, ndarray])
params (dict[str, Any])
engine (Any)

Return type:

Any

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)[source]

Decline resident accumulation until its nested effective-count layout is representable.

Parameters:

x (tuple[E, ndarray])
weights (Any)
params (dict[str, Any])
engine (Any)
estimator (Any)

Return type:

Any

dist_to_encoder()[source]

Returns a WeightedDataEncoder for encoding sequences of (value, weight) observations.

Return type:: WeightedDataEncoder

to_fisher(**kwargs)[source]: Fisher view for the weighted wrapper.

estimator(pseudo_count=None)[source]

Create a WeightedEstimator wrapping the base distribution’s estimator.

Parameters:: pseudo_count (Optional[float]) – Passed through to the base distribution’s estimator.
Returns:: WeightedEstimator object.
Return type:: WeightedEstimator

sampler(seed=None)[source]

Create a WeightedSampler producing (value, weight) pairs.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: WeightedSampler object.
Return type:: WeightedSampler

enumerator()[source]

Enumerate canonical (value, 1.0) observations in child-probability order.

Return type:: DistributionEnumerator

support_size()[source]

Return the child support size; attached weight is metadata, not a support coordinate.

Return type:: int | None

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

Bases: DistributionSampler

Sampler for (value, weight) observations from a weighted distribution.

The likelihood does not model the weight, so samples carry the neutral weight 1.0: accumulating (value, 1.0) is equivalent to accumulating the bare value with the base distribution. Values are drawn from the base distribution’s sampler.

Parameters:

dist (WeightedDistribution) – WeightedDistribution to draw samples from.
seed (Optional[int]) – Seed to set for sampling with RandomState.

dist

WeightedDistribution to draw samples from.

Type:: WeightedDistribution

rng

Seeded RandomState for sampling.

Type:: RandomState

dist_sampler

Sampler for the base distribution.

Type:: DistributionSampler

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

Draw iid (value, weight) samples, each with weight 1.0.

Parameters:

size (Optional[int]) – Number of iid samples to draw.
batched (bool)

Returns:

A single (value, 1.0) tuple if size is None, else a list of size such tuples.

Return type:

tuple[Any, float] | Sequence[tuple[Any, float]]

class WeightedEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate one canonical metadata representation for every child support value.

Parameters:: dist (WeightedDistribution)

class WeightedAccumulator(accumulator, name=None, keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulator that scales each observation’s weight by its attached score.

Parameters:

accumulator (SequenceEncodableStatisticAccumulator) – Accumulator for the base distribution.
name (Optional[str]) – Optional accumulator name.
keys (str | None)

accumulator

Accumulator for the base distribution.

Type:: SequenceEncodableStatisticAccumulator

name

Optional accumulator name.

Type:: Optional[str]

initialize(x, weight, rng)[source]

Initialize the base accumulator with observation x[0] weighted by weight*x[1].

Parameters:

x (Tuple[D, float]) – Observation (value, weight) pair.
weight (float) – External weight on the observation.
rng (RandomState) – Random number generator for initialization.

Return type:

None

update(x, weight, estimate)[source]

Update the base accumulator with observation x[0] weighted by weight*x[1].

Parameters:

x (Tuple[D, float]) – Observation (value, weight) pair.
weight (float) – External weight on the observation.
estimate (WeightedDistribution) – Previous estimate of the weighted distribution.

Return type:

None

seq_update(x, weights, estimate)[source]

Vectorized update of the base accumulator with weights scaled by the observation weights.

Parameters:

x (Tuple[E, np.ndarray]) – Sequence encoded values and weights from WeightedDataEncoder.
weights (np.ndarray) – External weights on the observations.
estimate (WeightedDistribution) – Previous estimate of the weighted distribution.

Return type:

None

seq_update_engine(x, weights, estimate, engine)[source]

Engine-resident E-step: per-observation weights are scaled on the active engine and the base accumulator is routed through the engine. Matches seq_update.

Parameters:

weights (Any)
estimate (WeightedDistribution)
engine (Any)

Return type:

None

seq_initialize(x, weights, rng)[source]

Vectorized initialization of the base accumulator with scaled weights.

Parameters:

x (Tuple[E, np.ndarray]) – Sequence encoded values and weights from WeightedDataEncoder.
weights (np.ndarray) – External weights on the observations.
rng (RandomState) – Random number generator for initialization.

Return type:

None

combine(suff_stat)[source]

Combine the base accumulator’s sufficient statistics with suff_stat.

Parameters:: suff_stat (SS) – Sufficient statistics of the base accumulator.
Returns:: This WeightedAccumulator.
Return type:: WeightedAccumulator

from_value(x)[source]

Set the base accumulator’s sufficient statistics from x.

Parameters:: x (SS) – Sufficient statistics of the base accumulator.
Returns:: This WeightedAccumulator.
Return type:: WeightedAccumulator

value()[source]

Return child statistics and their effective attached-times-external weight.

Return type:: WeightedStatistics

scale(c)[source]

Scale the child accumulator through its family-specific protocol.

Parameters:: c (float)
Return type:: WeightedAccumulator

key_merge(stats_dict)[source]

Pool child statistics and their effective weight under one parameter key.

Parameters:: stats_dict (dict[str, Any])
Return type:: None

key_replace(stats_dict)[source]

Replace child statistics and effective weight from their shared parameter pool.

Parameters:: stats_dict (dict[str, Any])
Return type:: None

acc_to_encoder()[source]

Returns a WeightedDataEncoder for encoding sequences of (value, weight) observations.

Return type:: WeightedDataEncoder

class WeightedAccumulatorFactory(factory, name=None, keys=None)[source]

Bases: StatisticAccumulatorFactory

Factory for weighted accumulators.

Parameters:

factory (StatisticAccumulatorFactory) – Accumulator factory for the base distribution.
name (Optional[str]) – Optional name assigned to created accumulators.
keys (str | None)

factory

Accumulator factory for the base distribution.

Type:: StatisticAccumulatorFactory

name

Optional name assigned to created accumulators.

Type:: Optional[str]

make()[source]

Returns a new WeightedAccumulator wrapping a fresh base accumulator.

Return type:: WeightedAccumulator

class WeightedEstimator(estimator, name=None, keys=None)[source]

Bases: ParameterEstimator

Estimator for a weighted distribution from weighted observations.

Parameters:

estimator (ParameterEstimator) – Estimator for the base distribution.
name (Optional[str]) – Optional name assigned to the estimated distribution.
keys (str | None)

estimator

Estimator for the base distribution.

Type:: ParameterEstimator

name

Optional name assigned to the estimated distribution.

Type:: Optional[str]

accumulator_factory()[source]

Returns a WeightedAccumulatorFactory wrapping the base estimator’s factory.

Return type:: WeightedAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate a WeightedDistribution from the base distribution’s sufficient statistics.

Parameters:

nobs (Optional[float]) – Weighted number of observations.
suff_stat (SS) – Sufficient statistics of the base accumulator.

Returns:

WeightedDistribution wrapping the estimated base distribution.

Return type:

WeightedDistribution

resident_accumulation_supported()[source]

Use the host wrapper accumulator so effective-weight metadata cannot be dropped.

Return type:: bool

class WeightedDataEncoder(encoder)[source]

Bases: DataSequenceEncoder

Data encoder for sequences of iid (value, weight) observations.

Parameters:: encoder (DataSequenceEncoder) – Encoder for the base distribution’s values.

encoder

Encoder for the base distribution’s values.

Type:: DataSequenceEncoder

seq_encode(x)[source]

Encode a sequence of (value, weight) observations for vectorized use.

Parameters:: x (Sequence[Tuple[D, float]]) – Sequence of iid (value, weight) observations.
Returns:: Tuple of base-encoded values and a numpy array of weights.
Return type:: tuple[Any, ndarray]

class WeightedFisherView(dist)[source]

Bases: FixedFisherView

Fisher view that scales child sufficient statistics by observation weights.

Parameters:: dist (Any)

score_center(stats=None, **kwargs)[source]

Return the empirical center used when centering weighted Fisher scores.

Parameters:

stats (ndarray | None)
kwargs (Any)

Return type:

ndarray