mixle.stats.combinator.record module

Named-record distributions for dict/DataFrame observations.

RecordDistribution is a product distribution like CompositeDistribution, but its children are addressed by field name instead of tuple position. It is small on purpose: named observations reuse the same distribution, estimator, accumulator, encoder, kernel, and engine protocols as the rest of mixle.stats.

DictRecordAccumulator

alias of RecordAccumulator

DictRecordAccumulatorFactory

alias of RecordAccumulatorFactory

DictRecordDataEncoder

alias of RecordDataEncoder

DictRecordDistribution

alias of RecordDistribution

DictRecordEstimator

alias of RecordEstimator

DictRecordSampler

alias of RecordSampler

class RecordAccumulator(fields, accumulators)

Bases: SequenceEncodableStatisticAccumulator

Accumulate field-wise sufficient statistics for record data.

Parameters:

• fields (Sequence[Any])

• accumulators (Sequence[SequenceEncodableStatisticAccumulator])

update(x, weight, estimate)

Accumulate one weighted mapping record.

Parameters:

• x (Mapping[Any, Any])

• weight (float)

• estimate (RecordDistribution | None)

Return type:

None

initialize(x, weight, rng)

Randomly initialize child accumulators from one mapping record.

Parameters:

• x (Mapping[Any, Any])

• weight (float)

• rng (RandomState)

Return type:

None

seq_update(x, weights, estimate)

Accumulate encoded records with per-row weights.

Parameters:

• x (tuple[Any, ...])

• weights (ndarray)

• estimate (RecordDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)

Randomly initialize child accumulators from encoded records.

Parameters:

• x (tuple[Any, ...])

• weights (ndarray)

• rng (RandomState)

Return type:

None

get_seq_lambda()

Return child sequence update callables for legacy orchestration.

Return type:

list[Any]

combine(suff_stat)

Merge field-wise sufficient statistics into this accumulator.

Parameters:

suff_stat (tuple[Any, ...])

Return type:

RecordAccumulator

value()

Return field-wise sufficient-statistic payloads in estimator order.

Return type:

tuple[Any, …]

from_value(x)

Restore child accumulators from a field-wise payload.

Parameters:

x (tuple[Any, ...])

Return type:

RecordAccumulator

scale(c)

Scale each field accumulator using its family-specific protocol.

Parameters:

c (float)

Return type:

RecordAccumulator

key_merge(stats_dict)

Merge keyed child statistics into the shared stats dictionary.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)

Replace keyed child statistics from the shared stats dictionary.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()

Return a record encoder composed from child accumulator encoders.

Return type:

RecordDataEncoder

class RecordAccumulatorFactory(fields, factories)

Bases: StatisticAccumulatorFactory

Factory that creates record accumulators with matching child factories.

Parameters:

• fields (Sequence[Any])

• factories (Sequence[StatisticAccumulatorFactory])

make()

Create a fresh record accumulator.

Return type:

RecordAccumulator

class RecordDataEncoder(fields, encoders)

Bases: DataSequenceEncoder

Encode a sequence of mapping records field-by-field.

Parameters:

• fields (Sequence[Any])

• encoders (Sequence[DataSequenceEncoder])

seq_encode(x)

Encode a sequence of mapping records field-by-field.

Parameters:

x (Sequence[Mapping[Any, Any]])

Return type:

tuple[Any, …]

class RecordDistribution(fields, dists=None)

Bases: SequenceEncodableProbabilityDistribution

Product distribution over mapping records with a fixed field set.

Parameters:

• fields (Any)

• dists (Sequence[SequenceEncodableProbabilityDistribution] | None)

compute_capabilities()

Return engine support inherited from all child distributions.

compute_declaration()

Return a child-role declaration for generated metadata consumers.

density(x)

Return probability density/mass for one mapping record.

Parameters:

x (Mapping[Any, Any])

Return type:

float

log_density(x)

Return summed child log densities for one mapping record.

Parameters:

x (Mapping[Any, Any])

Return type:

float

seq_log_density(x)

Return per-row log densities for encoded record fields.

Parameters:

x (tuple[Any, ...])

Return type:

ndarray

backend_seq_log_density(x, engine)

Return per-row log densities using backend-aware child scorers.

Parameters:

• x (tuple[Any, ...])

• engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)

Return stacked child parameters for homogeneous named-record mixtures.

Parameters:

• dists (Sequence[RecordDistribution])

• engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)

Return an (n, k) matrix of record log densities.

Parameters:

• x (tuple[Any, ...])

• params (dict[str, Any])

• engine (Any)

Return type:

Any

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)

Return per-component legacy named-record sufficient statistics.

Parameters:

• x (tuple[Any, ...])

• weights (Any)

• params (dict[str, Any])

• engine (Any)

• estimator (Any)

Return type:

tuple[Any, …]

gradient_fit_state(engine, torch, leaves, recurse, tensor_param)

Return distribution-owned state for autograd fitting.

Parameters:

• engine (Any)

• torch (Any)

• leaves (list[Any])

• recurse (Any)

• tensor_param (Any)

Return type:

Any

seq_ld_lambda()

Return legacy sequence log-density callables for this distribution.

Return type:

list[Any]

support_size()

Product of field support sizes (None if any field is infinite).

Return type:

int | None

sampler(seed=None)

Return a sampler that draws mapping records field-by-field.

Parameters:

seed (int | None)

Return type:

RecordSampler

estimator(pseudo_count=None)

Return a record estimator with child estimators from each field.

Parameters:

pseudo_count (float | None)

Return type:

RecordEstimator

decomposition()

Record fields are independent: split along the field (factor) axis, sufficient stats SUM-reduce.

dist_to_encoder()

Return a data encoder for this record field/source layout.

Return type:

RecordDataEncoder

enumerator()

Creates RecordEnumerator iterating mapping records in descending joint probability order.

Return type:

RecordEnumerator

conditional_enumerator(given)

Enumerate complete records consistent with the fixed fields in given.

given is a mapping {source: value} pinning a subset of fields (the canonical most-probable-completion / imputation query: complete missing fields, best first). Because the fields are independent, P(record | given) is proportional to the joint P(record), so descending order over the free fields is also descending conditional order. Each yielded value is a complete record with the fixed fields merged back in, and its log_prob is the full joint log_density (the enumerator contract: lp == dist.log_density(value)) – the fixed fields enter as a constant offset, which only shifts every score by the same amount.

Raises ValueError if given names a field this record does not have.

Parameters:

given (Mapping[Any, Any])

Return type:

RecordConditionalEnumerator

structural_fine_bucket(value, quantizer)

Sum of child structural buckets – mirrors the count index’s child convolution.

Like CompositeDistribution.structural_fine_bucket(), but fields are addressed by source name rather than tuple position.

Return type:

int

quantized_count_index(quantizer, max_fine_bucket)

Structural count index: the additive law – the carrier’s n-ary product over fields.

Identical reduction to CompositeDistribution.quantized_count_index() (the joint histogram is the convolution of the per-field histograms in the witness-retaining count semiring); the only difference is that the unranked structural tuple is relabelled into a mapping record keyed by source, so witnesses match what the model actually scores.

Parameters:

max_fine_bucket (int)

class RecordEstimator(fields, estimators=None)

Bases: ParameterEstimator

Estimator for independent named fields.

Parameters:

• fields (Any)

• estimators (Sequence[ParameterEstimator] | None)

accumulator_factory()

Return a factory for record sufficient-statistic accumulators.

Return type:

RecordAccumulatorFactory

estimate(nobs, suff_stat)

Estimate each child field and return a fitted record distribution.

Parameters:

• nobs (float | None)

• suff_stat (tuple[Any, ...])

Return type:

RecordDistribution

class RecordSampler(dist, seed=None)

Bases: DistributionSampler

Draw mapping records from a RecordDistribution.

Parameters:

• dist (RecordDistribution)

• seed (int | None)

sample(size=None)

Draw one record or a list of records from the child samplers.

Parameters:

size (int | None)

field(name, source=None)

Declare a named model field and the input key/column it reads.

field('x') reads input key 'x' and names the model field 'x'. field('x_copy', source='x') names a second model variable that reads the same input key, useful for dependence features and repeated views.

Parameters:

• name (Any)

• source (Any)

Return type:

tuple[Any, Any]

record(fields)

Create a RecordDistribution from a field-to-distribution mapping.

Parameters:

fields (Mapping[Any, SequenceEncodableProbabilityDistribution])

Return type:

RecordDistribution

record_estimator(fields)

Create a RecordEstimator from a field-to-estimator mapping.

Parameters:

fields (Mapping[Any, ParameterEstimator])

Return type:

RecordEstimator