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 an immutable registered identity rather than passed as a raw callable. Every identity pins a name, version, output dimension, and code/schema digest in the serialized leaf. Duplicate registration cannot silently replace an artifact’s semantics.

class FeatureIdentity(name, version, feature_dim, digest)[source]

Bases: object

Immutable identity of a deterministic raw-item feature transform.

Parameters:
register_feature_fn(name, fn, *, version, feature_dim)[source]

Register one immutable, versioned raw-item feature transform.

Repeating the exact registration is idempotent. Reusing (name, version) for different code or output schema raises; callers must publish a new version instead.

Parameters:
Return type:

FeatureIdentity

feature_fn(name, *, version=None, digest=None, feature_dim=None)[source]

Resolve a feature function and optionally verify its complete pinned identity.

Parameters:

  • name (str)

  • version (str | None)

  • digest (str | None)

  • feature_dim (int | None)

Return type:

Callable[[Any], ndarray]

class FeatureMapDensity(feature_name, inner, name=None, *, feature_version=None, feature_digest=None, feature_dim=None)[source]

Bases: SequenceEncodableProbabilityDistribution

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

Parameters:

  • feature_name (str)

  • inner (Any)

  • name (str | None)

  • feature_version (str | None)

  • feature_digest (str | None)

  • feature_dim (int | None)

density(x)[source]

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

Parameters:

x (Any)

Return type:

float

log_density(x)[source]

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

Parameters:

x (Any)

Return type:

float

seq_log_density(x)[source]

Return inner log densities for an already-featurized batch.

Parameters:

x (ndarray)

Return type:

ndarray

sampler(seed=None)[source]

Raw-item sampling is undefined because the feature map has no inverse.

Parameters:

seed (int | None)

Return type:

DistributionSampler

feature_sampler(seed=None)[source]

Return the sampler of the explicitly separate inner feature-space distribution.

Parameters:

seed (int | None)

Return type:

DistributionSampler

estimator(pseudo_count=None)[source]

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

Parameters:

pseudo_count (float | None)

Return type:

FeatureMapEstimator

dist_to_encoder()[source]

Return the encoder that maps raw items to feature vectors.

Return type:

FeatureMapEncoder

class FeatureMapEncoder(feature_name, *, feature_version=None, feature_digest=None, feature_dim=None)[source]

Bases: DataSequenceEncoder

Encode raw items by applying a registered deterministic feature function.

Parameters:

  • feature_name (str)

  • feature_version (str | None)

  • feature_digest (str | None)

  • feature_dim (int | None)

seq_encode(data)[source]

Convert raw items into a stacked feature matrix.

Parameters:

data (list)

Return type:

ndarray

class FeatureMapAccumulator(identity, inner_acc)[source]

Bases: SequenceEncodableStatisticAccumulator

Delegate accumulation to the inner estimator after feature extraction.

Parameters:

  • identity (FeatureIdentity)

  • inner_acc (Any)

update(x, weight, estimate)[source]

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

Parameters:
Return type:

None

seq_update(enc, weights, estimate)[source]

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

Parameters:
Return type:

None

initialize(x, weight, rng)[source]

Initialize the inner accumulator from one feature-mapped item.

Parameters:
Return type:

None

seq_initialize(enc, weights, rng)[source]

Initialize the inner accumulator from an encoded feature batch.

Parameters:
Return type:

None

combine(other)[source]

Merge sufficient statistics into the inner accumulator.

Parameters:

other (Any)

Return type:

FeatureMapAccumulator

value()[source]

Return the inner accumulator’s sufficient-statistic value.

Return type:

Any

from_value(v)[source]

Restore the inner accumulator from its value representation.

Parameters:

v (Any)

Return type:

FeatureMapAccumulator

acc_to_encoder()[source]

Return the feature-map encoder expected by this accumulator.

Return type:

FeatureMapEncoder

class FeatureMapAccumulatorFactory(identity, inner_factory)[source]

Bases: StatisticAccumulatorFactory

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

Parameters:

  • identity (FeatureIdentity)

  • inner_factory (Any)

make()[source]

Create a fresh feature-map accumulator.

Return type:

FeatureMapAccumulator

class FeatureMapEstimator(feature_name, inner, name=None, *, feature_version=None, feature_digest=None, feature_dim=None)[source]

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)

  • feature_version (str | None)

  • feature_digest (str | None)

  • feature_dim (int | None)

accumulator_factory()[source]

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

Return type:

FeatureMapAccumulatorFactory

estimate(nobs, suff_stat)[source]

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

Parameters:
Return type:

FeatureMapDensity