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()

Declare the NumPy and numba execution path used by Mallows kernels.

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 of one ordering under the Mallows model.

Parameters:

x (Sequence[int])

Return type:

float

log_density(x)

Return the log-probability of one ordering.

Parameters:

x (Sequence[int])

Return type:

float

seq_log_density(x)

Return vectorized log-probabilities for encoded orderings.

Parameters:

x (ndarray)

Return type:

ndarray

sampler(seed=None)

Return a sampler for this Mallows distribution.

Parameters:

seed (int | None)

Return type:

GeneralizedMallowsSampler

estimator(pseudo_count=None)

Return a Mallows estimator with this metric and item count.

Parameters:

pseudo_count (float | None)

Return type:

GeneralizedMallowsEstimator

dist_to_encoder()

Return the full-ranking encoder used by 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 one ordering or size iid orderings.

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)

Update rank, precedence, and reservoir statistics from one ordering.

Parameters:

• x (Sequence[int])

• weight (float)

• estimate (Any)

Return type:

None

initialize(x, weight, rng)

Initialize statistics from one weighted ordering.

Parameters:

• x (Sequence[int])

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Update rank, precedence, and reservoir statistics from encoded orderings.

Parameters:

• x (ndarray)

• weights (ndarray)

• estimate (Any)

Return type:

None

seq_initialize(x, weights, rng)

Initialize statistics from encoded orderings.

Parameters:

• x (ndarray)

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Merge consensus statistics and reservoir samples from another accumulator.

Return type:

GeneralizedMallowsAccumulator

value()

Return count, consensus matrices, and bounded reservoir contents.

from_value(x)

Restore accumulator state from value output.

Return type:

GeneralizedMallowsAccumulator

key_merge(stats_dict)

Merge this accumulator into stats_dict under its configured key.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)

Replace this accumulator’s state from keyed statistics when present.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()

Return the ranking encoder compatible with these sufficient statistics.

Return type:

GeneralizedMallowsDataEncoder

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

Bases: StatisticAccumulatorFactory

Create accumulators for generalized Mallows consensus statistics.

Parameters:

• dim (int)

• reservoir (int)

• keys (str | None)

make()

Create an empty generalized Mallows accumulator.

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 a factory for Mallows sufficient-statistic accumulators.

Return type:

GeneralizedMallowsAccumulatorFactory

estimate(nobs, suff_stat)

Estimate the central ordering and dispersion from accumulated rankings.

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)

Validate and encode full orderings as a dense integer matrix.

Parameters:

x (Sequence[Sequence[int]])

Return type:

ndarray