mixle.models.feature_map module

Frozen deterministic feature maps composed with inner densities.

A deterministic, non-invertible feature function (for example mixle.represent.modality.image_features()) reduces a raw item – an image array, a signal, any shape a plain scalar/vector family cannot represent – to a fixed-length vector, and an inner distribution/estimator (any five-piece mixle family, including a neural density) is fit on the induced feature-space distribution.

Stated plainly: this is a genuine, well-defined density over the feature representation, not a claim about the density of the raw item – there is no Jacobian correction because the map is not invertible. Anywhere this leaf is chosen, the reasoning is recorded so that distinction stays visible (see mixle.utils.automatic’s modality routing).

Feature functions are looked up by a registered name, not passed as a raw callable, so the leaf serializes: the same closed-registry pattern mixle.models.neural_density uses for its hoisted nn.Module classes. Register a feature function once (register_feature_fn); the leaf then carries only the name.

register_feature_fn(name, fn)

Register fn (raw item -> fixed-length vector) under name so a leaf can carry just the name.

Parameters:

• name (str)

• fn (Callable[[Any], ndarray])

Return type:

None

feature_fn(name)

Look up a registered feature function by name; raises if it was never registered.

Parameters:

name (str)

Return type:

Callable[[Any], ndarray]

class FeatureMapDensity(feature_name, inner, name=None)

Bases: SequenceEncodableProbabilityDistribution

p(feature_fn(x)) for a registered, deterministic feature_fn and inner distribution.

Parameters:

• feature_name (str)

• inner (Any)

• name (str | None)

density(x)

Return the induced feature-space density at raw item x.

Parameters:

x (Any)

Return type:

float

log_density(x)

Return log p(feature_fn(x)) under the inner distribution.

Parameters:

x (Any)

Return type:

float

seq_log_density(x)

Return inner log densities for an already-featurized batch.

Parameters:

x (ndarray)

Return type:

ndarray

sampler(seed=None)

Return a sampler for the inner feature-space distribution.

Parameters:

seed (int | None)

Return type:

FeatureMapSampler

estimator(pseudo_count=None)

Return an estimator that fits the inner estimator on registered features.

Parameters:

pseudo_count (float | None)

Return type:

FeatureMapEstimator

dist_to_encoder()

Return the encoder that maps raw items to feature vectors.

Return type:

FeatureMapEncoder

class FeatureMapSampler(dist, seed=None)

Bases: DistributionSampler

Sampler for the feature-space distribution induced by a feature-map leaf.

Parameters:

• dist (FeatureMapDensity)

• seed (int | None)

sample(size=None, *, batched=True)

Samples from the INNER (feature-space) distribution – there is no inverse feature map back to raw items.

Parameters:

• size (int | None)

• batched (bool)

Return type:

Any

class FeatureMapEncoder(feature_name)

Bases: DataSequenceEncoder

Encode raw items by applying a registered deterministic feature function.

Parameters:

feature_name (str)

seq_encode(data)

Convert raw items into a stacked feature matrix.

Parameters:

data (list)

Return type:

ndarray

class FeatureMapAccumulator(feature_name, inner_acc)

Bases: SequenceEncodableStatisticAccumulator

Delegate accumulation to the inner estimator after feature extraction.

Parameters:

• feature_name (str)

• inner_acc (Any)

update(x, weight, estimate)

Feature-map one raw item and add it to the inner accumulator.

Parameters:

• x (Any)

• weight (float)

• estimate (Any)

Return type:

None

seq_update(enc, weights, estimate)

Pass an already-featurized batch through to the inner accumulator.

Parameters:

• enc (Any)

• weights (ndarray)

• estimate (Any)

Return type:

None

initialize(x, weight, rng)

Initialize the inner accumulator from one feature-mapped item.

Parameters:

• x (Any)

• weight (float)

• rng (Any)

Return type:

None

seq_initialize(enc, weights, rng)

Initialize the inner accumulator from an encoded feature batch.

Parameters:

• enc (Any)

• weights (ndarray)

• rng (Any)

Return type:

None

combine(other)

Merge sufficient statistics into the inner accumulator.

Parameters:

other (Any)

Return type:

FeatureMapAccumulator

value()

Return the inner accumulator’s sufficient-statistic value.

Return type:

Any

from_value(v)

Restore the inner accumulator from its value representation.

Parameters:

v (Any)

Return type:

FeatureMapAccumulator

acc_to_encoder()

Return the feature-map encoder expected by this accumulator.

Return type:

FeatureMapEncoder

class FeatureMapAccumulatorFactory(feature_name, inner_factory)

Bases: StatisticAccumulatorFactory

Factory for feature-map accumulators wrapping an inner accumulator factory.

Parameters:

• feature_name (str)

• inner_factory (Any)

make()

Create a fresh feature-map accumulator.

Return type:

FeatureMapAccumulator

class FeatureMapEstimator(feature_name, inner, name=None)

Bases: ParameterEstimator

Fits inner on feature_fn(x) for raw items x – the estimator side of FeatureMapDensity.

Parameters:

• feature_name (str)

• inner (ParameterEstimator)

• name (str | None)

accumulator_factory()

Return an accumulator factory that feature-maps raw inputs before inner accumulation.

Return type:

FeatureMapAccumulatorFactory

estimate(nobs, suff_stat)

Estimate the inner distribution and wrap it as a feature-map density.

Parameters:

• nobs (float | None)

• suff_stat (Any)

Return type:

FeatureMapDensity