mixle.stats.latent.hierarchical module

Hierarchical (partial-pooling) normal model – the plate / random-effects structure.

Grouped data (many drill sites, survey lines, lab batches, taxa) is best modelled with a plate: each group has its own parameter drawn from a shared population distribution. Fitting each group alone (no pooling) overfits small groups; pooling everything (complete pooling) ignores real between-group variation. Partial pooling – the hierarchical model – learns the population spread and shrinks each group’s estimate toward the population mean by an amount set by its sample size.

HierarchicalNormalDistribution is a first-class mixle leaf whose observation is a whole group (a sequence of values): y[g,i] ~ N(theta[g], sigma^2) with theta[g] ~ N(mu, tau^2). Marginalizing the latent group mean gives a closed-form group likelihood y_g ~ N(mu*1, sigma^2 I + tau^2 11^T), so it follows the Distribution / Sampler / Estimator / Accumulator / DataEncoder contract: it fits through estimate(groups, dist.estimator()) (empirical-Bayes EM over the latent means), scores groups with log_density / seq_log_density, and exposes the per-group shrinkage posteriors.

class HierarchicalNormalDistribution(mu, tau, sigma, name=None, keys=None, fit_diagnostics=None)

Bases: SequenceEncodableProbabilityDistribution

Two-level normal hierarchy over groups: y[g,i] ~ N(theta[g], sigma^2), theta[g] ~ N(mu, tau^2).

Each observation is one group (a sequence of values). mu is the population mean, tau the between-group sd and sigma the within-group sd. The latent group mean is marginalized out, so a group’s likelihood is the multivariate normal N(mu*1, sigma^2 I + tau^2 11^T) (computed in closed form). group_posterior / shrinkage give the partial-pooling estimates.

Parameters:

• mu (float)

• tau (float)

• sigma (float)

• name (str | None)

• keys (str | None)

• fit_diagnostics (HierarchicalNormalFitDiagnostics | None)

density(group)

Return the marginal density of one observed group.

Return type:

float

log_density(group)

Marginal log-likelihood of one group (latent group mean integrated out).

Return type:

float

seq_log_density(x)

Return vectorized marginal log likelihoods for encoded groups.

Return type:

ndarray

group_posterior(ybar, n)

Posterior (mean, sd) of a group’s true mean given its sample mean ybar and size n.

The shrinkage estimate mu + shrink*(ybar - mu) with shrink = tau^2/(tau^2 + sigma^2/n).

Parameters:

• ybar (float)

• n (int)

Return type:

tuple[float, float]

shrinkage(n)

The shrinkage weight for a size-n group (0 = full pooling to mu, 1 = its own mean).

Parameters:

n (int)

Return type:

float

sampler(seed=None)

Return a sampler for grouped observations from this hierarchy.

Parameters:

seed (int | None)

Return type:

HierarchicalNormalSampler

estimator(pseudo_count=None)

Return an empirical-Bayes EM estimator for the hierarchy.

Parameters:

pseudo_count (float | None)

Return type:

HierarchicalNormalEstimator

dist_to_encoder()

Return the data encoder used by this distribution.

Return type:

HierarchicalNormalDataEncoder

class HierarchicalNormalEstimator(max_iter=500, tol=1e-9, max_group_sizes=_DEFAULT_MAX_GROUP_SIZES, name=None, keys=None)

Bases: ParameterEstimator

Weighted empirical-Bayes EM over size-bucketed group sufficient statistics.

Parameters:

• max_iter (int)

• tol (float)

• max_group_sizes (int)

• name (str | None)

• keys (str | None)

accumulator_factory()

Return an accumulator factory for bounded size-bucketed statistics.

Return type:

StatisticAccumulatorFactory

estimate(nobs, suff_stat)

Fit mu, tau, and sigma with a weighted EM receipt.

Return type:

HierarchicalNormalDistribution

class HierarchicalNormalFitDiagnostics(converged, identifiable, iterations, termination_reason, objective_trace, final_parameter_delta, n_group_sizes, total_group_weight, total_observation_weight)

Bases: object

Machine-readable receipt for the empirical-Bayes EM fit.

Parameters:

• converged (bool)

• identifiable (bool)

• iterations (int)

• termination_reason (str)

• objective_trace (tuple[float, ...])

• final_parameter_delta (float | None)

• n_group_sizes (int)

• total_group_weight (float)

• total_observation_weight (float)