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 exact algorithms within explicit resource caps:

footrule  Z = perm(phi^{|i-j|})    exact log-domain subset permanent
spearman  Z = perm(phi^{(i-j)^2})  exact log-domain subset permanent
ulam      Z = sum over the exact LIS-distance histogram

Construction fails closed above a cap; a Monte-Carlo estimate is never installed as a probability normalizer. The retained n_mc and seed arguments are compatibility metadata only and are reported as such in computation diagnostics.

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, fit_diagnostics=None)

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)

• fit_diagnostics (GeneralizedMallowsFitDiagnostics | None)

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.

Raises:

ValueError – If x is not a permutation of 0,…,n-1 (wrong length, a repeated element, a non-integer entry, or an element outside that range). A malformed x is not merely an unlikely ordering – it isn’t an ordering at all, so it is rejected here rather than silently scored (e.g. a repeated index would otherwise still produce a finite, meaningless distance, an out-of-range index can alias a valid rank via numpy’s negative-index wraparound instead of failing loudly, and a fractional entry like 0.5 would otherwise be silently truncated to 0 by the int cast before this check ever saw it).

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)

Bases: DistributionSampler

Draw exact iid orderings using metric-specific finite-law samplers.

Parameters:

• dist (GeneralizedMallowsDistribution)

• seed (int | None)

sample(size=None, *, batched=True)

Draw one ordering or size iid orderings.

Parameters:

• size (int | None)

• batched (bool)

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

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, pseudo_count=None, prior_center=None, center_exact_cap=7, allow_approximate_center=False)

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)

• pseudo_count (float | None)

• prior_center (Sequence[int] | np.ndarray | None)

• center_exact_cap (int)

• allow_approximate_center (bool)

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

class GeneralizedMallowsFitDiagnostics(center_algorithm, center_exact, centers_evaluated, distance_objective, regularized, pseudo_count)

Bases: object

Center-search and regularization evidence attached to a fitted model.

Parameters:

• center_algorithm (str)

• center_exact (bool)

• centers_evaluated (int)

• distance_objective (float)

• regularized (bool)

• pseudo_count (float)

class GeneralizedMallowsComputationDiagnostics(normalizer_algorithm, normalizer_exact, sampler_algorithm, sampler_exact, legacy_n_mc_ignored, legacy_seed_ignored)

Bases: object

Exactness and algorithm provenance for scoring and sampling.

Parameters:

• normalizer_algorithm (str)

• normalizer_exact (bool)

• sampler_algorithm (str)

• sampler_exact (bool)

• legacy_n_mc_ignored (int)

• legacy_seed_ignored (int)