mixle.inference.fisher module

Generic Fisher-geometry views for mixle distributions.

The classes here expose a common sufficient-statistic and Fisher-vector interface without requiring every distribution to duplicate plumbing. The generic view is accumulator-backed: for ordinary models it returns observed sufficient statistics, while latent models use the existing update/seq_update E-step to return posterior-expected complete-data sufficient statistics.

Specialized distributions can later override to_fisher() with faster or more canonical views, but this default gives every stats/bstats model a useful and vectorizable baseline.

For latent-variable models, fisher_information() may expose a model or complete-data Fisher metric supplied by the view. When comparing observed data, use observed_fisher_information() / observed_fisher_vectors(): these center posterior-expected complete-data statistics into observed score vectors and use their observed covariance as the metric.

class SufficientStatisticVectorizer(labels=None)[source]

Bases: object

Flatten nested sufficient-statistic structures into numeric vectors.

Accumulators in mixle return tuples, arrays, dictionaries, and scalars. This vectorizer learns a stable union schema from a collection of such structures and then maps each structure into the same numeric coordinate system.

Parameters:

labels (Sequence[Path] | None)

fit(values)[source]
Parameters:

values (Sequence[Any])

Return type:

SufficientStatisticVectorizer

partial_fit(values)[source]
Parameters:

values (Sequence[Any])

Return type:

SufficientStatisticVectorizer

transform(values, extend=False)[source]
Parameters:
Return type:

ndarray

fit_transform(values)[source]
Parameters:

values (Sequence[Any])

Return type:

ndarray

label_strings()[source]
Return type:

list[str]

class FisherView(dist, estimator=None)[source]

Bases: object

Accumulator-backed Fisher-geometry view of a distribution.

Parameters:

  • dist (Any) – mixle.stats or mixle.bstats distribution.

  • estimator (Any | None) – Optional estimator. When omitted, dist.estimator() is used.

Notes

The generic encoded-data path obtains per-row statistics by replaying seq_update with one-hot weights. That keeps the interface compatible with existing encoders, but it is a correctness fallback rather than a high-performance implementation. Important families should override to_fisher() with direct seq_expected_statistics kernels.

structured_statistics(x, estimate=None, weight=1.0)[source]

Structured sufficient stats for one observation.

For latent-variable distributions, this is the posterior-expected complete-data sufficient statistic under estimate (or this view’s distribution when estimate is omitted).

Parameters:
Return type:

Any

expected_structured_statistics(x, estimate=None, weight=1.0)[source]
Parameters:
Return type:

Any

sufficient_statistics(x, estimate=None, vectorizer=None)[source]
Parameters:

  • x (Any)

  • estimate (Any | None)

  • vectorizer (SufficientStatisticVectorizer | None)

Return type:

ndarray

expected_sufficient_statistics(x, estimate=None, vectorizer=None)[source]
Parameters:

  • x (Any)

  • estimate (Any | None)

  • vectorizer (SufficientStatisticVectorizer | None)

Return type:

ndarray

seq_structured_statistics(enc_data, estimate=None)[source]

Structured per-row stats from encoded data.

This generic implementation is intentionally conservative and may be slow for large data. It exists so every encoder-compatible model has a correct baseline.

Parameters:

  • enc_data (Any)

  • estimate (Any | None)

Return type:

list[Any]

statistics_matrix(data=None, enc_data=None, estimate=None, vectorizer=None, fit=True)[source]

Return an n x d matrix of per-observation sufficient statistics.

Parameters:

  • data (Sequence[Any] | None)

  • enc_data (Any | None)

  • estimate (Any | None)

  • vectorizer (SufficientStatisticVectorizer | None)

  • fit (bool)

Return type:

ndarray

expected_statistics_matrix(data=None, enc_data=None, estimate=None, vectorizer=None, fit=True)[source]
Parameters:

  • data (Sequence[Any] | None)

  • enc_data (Any | None)

  • estimate (Any | None)

  • vectorizer (SufficientStatisticVectorizer | None)

  • fit (bool)

Return type:

ndarray

seq_expected_statistics(enc_data, estimate=None, vectorizer=None, fit=True)[source]
Parameters:

  • enc_data (Any)

  • estimate (Any | None)

  • vectorizer (SufficientStatisticVectorizer | None)

  • fit (bool)

Return type:

ndarray

mean_statistics(stats=None, **kwargs)[source]
Parameters:
Return type:

ndarray

score_center(stats=None, **kwargs)[source]
Parameters:
Return type:

ndarray

fisher_information(stats=None, diagonal=False, ridge=1.0e-8, **kwargs)[source]

Empirical Fisher approximation from per-observation statistic vectors.

Parameters:
Return type:

ndarray

fisher_vectors(stats=None, metric='diagonal', center=None, fisher=None, ridge=1.0e-8, **kwargs)[source]

Return centered/whitened sufficient-statistic vectors.

metric=’identity’ returns centered statistics, ‘diagonal’ divides by per-coordinate Fisher standard deviations, and ‘full’ applies an empirical full-matrix whitening transform.

Parameters:
Return type:

ndarray

observed_fisher_information(stats=None, diagonal=False, center=None, ridge=1.0e-8, **kwargs)[source]

Observed Fisher estimate from score vectors for observed data.

For latent models the statistic rows are posterior-expected complete-data sufficient statistics, so centering them by their model expectation gives observed score vectors. Their covariance is the observed Fisher metric used by Fisher-vector embeddings. If a model center is unavailable, this falls back to the empirical mean.

Parameters:
Return type:

ndarray

observed_fisher_vectors(stats=None, metric='diagonal', center=None, fisher=None, ridge=1.0e-8, **kwargs)[source]
Parameters:
Return type:

ndarray

fisher_vector(x, estimate=None, metric='diagonal', center=None, fisher=None, vectorizer=None, ridge=1.0e-8)[source]
Parameters:

  • x (Any)

  • estimate (Any | None)

  • metric (str)

  • center (ndarray | None)

  • fisher (ndarray | None)

  • vectorizer (SufficientStatisticVectorizer | None)

  • ridge (float)

Return type:

ndarray

natural_parameters()[source]

Return natural parameters when a specialized view provides them.

Return type:

Any

class FixedFisherView(dist, labels)[source]

Bases: FisherView

Distribution-specific Fisher view with fixed vector coordinates.

Parameters:

  • dist (Any)

  • labels (Sequence[Path])

structured_statistics(x, estimate=None, weight=1.0)[source]

Structured sufficient stats for one observation.

For latent-variable distributions, this is the posterior-expected complete-data sufficient statistic under estimate (or this view’s distribution when estimate is omitted).

Parameters:
Return type:

Any

sufficient_statistics(x, estimate=None, vectorizer=None)[source]
Parameters:

  • x (Any)

  • estimate (Any | None)

  • vectorizer (SufficientStatisticVectorizer | None)

Return type:

ndarray

seq_structured_statistics(enc_data, estimate=None)[source]

Structured per-row stats from encoded data.

This generic implementation is intentionally conservative and may be slow for large data. It exists so every encoder-compatible model has a correct baseline.

Parameters:

  • enc_data (Any)

  • estimate (Any | None)

Return type:

list[Any]

statistics_matrix(data=None, enc_data=None, estimate=None, vectorizer=None, fit=True)[source]

Return an n x d matrix of per-observation sufficient statistics.

Parameters:

  • data (Sequence[Any] | None)

  • enc_data (Any | None)

  • estimate (Any | None)

  • vectorizer (SufficientStatisticVectorizer | None)

  • fit (bool)

Return type:

ndarray

mean_statistics(stats=None, model=True, **kwargs)[source]
Parameters:
Return type:

ndarray

fisher_information(stats=None, diagonal=False, ridge=1.0e-8, **kwargs)[source]

Empirical Fisher approximation from per-observation statistic vectors.

Parameters:
Return type:

ndarray

fisher_vectors(stats=None, metric='diagonal', center=None, fisher=None, ridge=1.0e-8, **kwargs)[source]

Return centered/whitened sufficient-statistic vectors.

metric=’identity’ returns centered statistics, ‘diagonal’ divides by per-coordinate Fisher standard deviations, and ‘full’ applies an empirical full-matrix whitening transform.

Parameters:
Return type:

ndarray

class CountFisherView(dist, mean_var_fn, data_fn, enc_fn)[source]

Bases: FixedFisherView

Parameters:

  • dist (Any)

  • mean_var_fn (Callable[[Any], tuple[float, float]])

  • data_fn (Callable[[Any], np.ndarray])

  • enc_fn (Callable[[Any], np.ndarray])

class EmpiricalMetricFixedFisherView(dist, labels)[source]

Bases: FixedFisherView

Fixed-coordinate view whose whitening falls back to empirical Fisher.

Parameters:

  • dist (Any)

  • labels (Sequence[Path])

mean_statistics(stats=None, **kwargs)[source]
Parameters:
Return type:

ndarray

fisher_information(stats=None, diagonal=False, ridge=1.0e-8, **kwargs)[source]

Empirical Fisher approximation from per-observation statistic vectors.

Parameters:
Return type:

ndarray

fisher_vectors(stats=None, metric='diagonal', center=None, fisher=None, ridge=1.0e-8, **kwargs)[source]

Return centered/whitened sufficient-statistic vectors.

metric=’identity’ returns centered statistics, ‘diagonal’ divides by per-coordinate Fisher standard deviations, and ‘full’ applies an empirical full-matrix whitening transform.

Parameters:
Return type:

ndarray

to_fisher(dist, **kwargs)[source]

Return a FisherView for dist via its own to_fisher hook.

Fisher views are co-located with each distribution: a distribution owns its view by overriding ProbabilityDistribution.to_fisher. This module keeps only the shared base machinery (FisherView/FixedFisherView/SufficientStatisticVectorizer and the reusable CountFisherView / EmpiricalMetricFixedFisherView helpers) plus _legacy_to_fisher(), the type-name dispatch for families not yet migrated to a per-file hook (and the generic fallback).

Parameters:
Return type:

FisherView