mixle.stats.rankings.generalized_mallows module

Generalized Mallows distribution over permutations under a choice of distance metric.

The Mallows family concentrates probability around a central permutation sigma0 with dispersion theta >= 0:

p(sigma) = exp(-theta * d(sigma, sigma0)) / Z(theta, n),

generalizing MallowsDistribution (Kendall-only) to any of the six metrics in mixle.stats.rankings._permutation_kernels. The per-datum distance is the numba kernel; this module supplies the metric-specific normalizer Z. Three metrics have a closed-form (fast-DP) normalizer and moment E_theta[d]:

kendall Z = prod_{i=1}^{n-1} (1 - phi^{i+1}) / (1 - phi) (phi = e^{-theta}) cayley Z = prod_{i=1}^{n-1} (1 + i phi) hamming Z = sum_{m=0}^{n} C(n, m) D_m phi^m (D_m = subfactorial)

The other three are #P-hard and use an exact small-n normalizer with a numba Monte-Carlo fallback beyond a size cap (the fallback is an approximation, controlled by n_mc / seed):

footrule Z = perm(phi^{|i-j|}) exact Ryser permanent for n <= max_exact (16), else MC spearman Z = perm(phi^{(i-j)^2}) exact Ryser permanent for n <= max_exact (16), else MC ulam Z = sum over the LIS-distance histogram, exact for n <= max_enum (9), else MC

Data type: List[int] – a full ordering, a permutation of 0..n-1 with x[r] the item at rank r (best first).

class GeneralizedMallowsDistribution(sigma0, theta=1.0, metric='kendall', name=None, keys=None, n_mc=20000, seed=0, max_exact=16, max_enum=9)

Bases: SequenceEncodableProbabilityDistribution

Mallows distribution under a configurable distance metric (closed-form normalizer metrics).

Parameters:

• sigma0 (Sequence[int] | np.ndarray)

• theta (float)

• metric (str)

• name (str | None)

• keys (str | None)

• n_mc (int)

• seed (int)

• max_exact (int)

• max_enum (int)

classmethod compute_capabilities()

distance(x)

Distance between ordering x and the central permutation under this metric.

Parameters:

x (Sequence[int])

Return type:

int

density(x)

Return the probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

Parameters:

x (Sequence[int])

Return type:

float

log_density(x)

Return the log-density or log-mass at a single observation.

Parameters:

x (Sequence[int])

Return type:

float

seq_log_density(x)

Return vectorized log-density values for sequence-encoded observations.

Parameters:

x (ndarray)

Return type:

ndarray

sampler(seed=None)

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

GeneralizedMallowsSampler

estimator(pseudo_count=None)

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

GeneralizedMallowsEstimator

dist_to_encoder()

Return the data encoder used by this distribution for vectorized methods.

Return type:

GeneralizedMallowsDataEncoder

class GeneralizedMallowsSampler(dist, seed=None, burn=1000, thin=10)

Bases: DistributionSampler

Draw orderings via the exact RIM (Kendall) or a numba Metropolis sampler (other metrics).

Parameters:

• dist (GeneralizedMallowsDistribution)

• seed (int | None)

• burn (int)

• thin (int)

sample(size=None)

Draw observations.

Combinator samplers (mixture/sequence/…) accept batched. With batched=True (the default) each child stream is drawn in one vectorized call instead of a per-draw Python loop – far faster. Because every child sampler owns an independent RandomState, batching consumes each stream in the same order as the loop, so the draws are identical to the legacy path. batched=False forces that legacy per-draw loop as a guaranteed- stable reference. Leaf samplers are already vectorized and ignore the flag.

Parameters:

size (int | None)

Return type:

list[int] | list[list[int]]

class GeneralizedMallowsAccumulator(dim, reservoir=10000, keys=None)

Bases: SequenceEncodableStatisticAccumulator

Accumulate the rank-count matrix, the precede matrix, and a bounded reservoir of orderings.

rank_count[item, rank] and precede[a, b] give the consensus (Borda / Copeland); the reservoir supplies the empirical mean metric-distance to the fitted center (exact when the data fit in it).

Parameters:

• dim (int)

• reservoir (int)

• keys (str | None)

update(x, weight, estimate)

Parameters:

• x (Sequence[int])

• weight (float)

• estimate (Any)

Return type:

None

initialize(x, weight, rng)

Parameters:

• x (Sequence[int])

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Parameters:

• x (ndarray)

• weights (ndarray)

• estimate (Any)

Return type:

None

seq_initialize(x, weights, rng)

Parameters:

• x (ndarray)

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Return type:

GeneralizedMallowsAccumulator

value()

from_value(x)

Return type:

GeneralizedMallowsAccumulator

key_merge(stats_dict)

Pool this accumulator’s statistics into stats_dict under its merge key.

The structural default implements the common single-key pattern: store the accumulator under self.keys the first time the key is seen, else combine into the one already there. Accumulators with several named keys (e.g. an HMM’s init/trans/state keys) or a non-accumulator stats payload override this. A keys of None (the default) is a no-op.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)

Replace this accumulator’s statistics from the pooled stats_dict entry (see key_merge).

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()

Return type:

GeneralizedMallowsDataEncoder

class GeneralizedMallowsAccumulatorFactory(dim, reservoir=10000, keys=None)

Bases: StatisticAccumulatorFactory

Parameters:

• dim (int)

• reservoir (int)

• keys (str | None)

make()

Return type:

GeneralizedMallowsAccumulator

class GeneralizedMallowsEstimator(dim, metric='kendall', theta=None, reservoir=10000, name=None, keys=None, n_mc=20000, seed=0, max_exact=16, max_enum=9)

Bases: ParameterEstimator

Estimate the central permutation (Copeland/Borda) and dispersion theta (moment match).

Parameters:

• dim (int)

• metric (str)

• theta (float | None)

• reservoir (int)

• name (str | None)

• keys (str | None)

• n_mc (int)

• seed (int)

• max_exact (int)

• max_enum (int)

accumulator_factory()

Return type:

GeneralizedMallowsAccumulatorFactory

estimate(nobs, suff_stat)

Parameters:

nobs (float | None)

Return type:

GeneralizedMallowsDistribution

class GeneralizedMallowsDataEncoder(dim=None)

Bases: DataSequenceEncoder

Encode a sequence of orderings (permutations of 0,…,n-1) into an (N, n) integer array.

Parameters:

dim (int | None)

seq_encode(x)

Encode the iid observation sequence x for vectorized evaluation.

Parameters:

x (Sequence[Sequence[int]])

Return type:

ndarray