mixle.stats.rankings.generalized_mallows_model module

Generalized Mallows Model (GMM): Mallows with a separate dispersion per ranking stage.

The Generalized Mallows Model (Fligner & Verducci, 1986) refines the Kendall Mallows model by giving each stage of the ranking its own dispersion. Writing an ordering’s Repeated-Insertion-Model code J = (J_1, ..., J_{n-1}) relative to the central permutation sigma0 (J_i in {0..i} is the back-jump of central item i; sum_i J_i is the Kendall distance), the GMM makes the stages independent truncated-geometrics:

p(sigma) = exp(-sum_i theta_i J_i(sigma)) / Z, Z = prod_i psi_i(theta_i), psi_i(theta_i) = sum_{r=0}^{i} exp(-theta_i r) = (1 - exp(-theta_i (i+1))) / (1 - exp(-theta_i)).

Everything factorizes over stages, so the normalizer, the moments E[J_i], exact RIM sampling, and maximum likelihood are all closed form and the per-datum statistic J is a numba kernel. The model captures rankings that are firm at the top but loose at the bottom (decreasing theta_i) and vice versa – structure a single-dispersion Mallows cannot represent.

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

class GeneralizedMallowsModelDistribution(sigma0, theta=None, name=None, keys=None, fit_diagnostics=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Generalized Mallows Model: a Kendall Mallows model with a per-stage dispersion vector theta.

Parameters:

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

  • theta (Sequence[float] | np.ndarray | None)

  • name (str | None)

  • keys (str | None)

  • fit_diagnostics (GeneralizedMallowsModelFitDiagnostics | None)

classmethod compute_capabilities()[source]

Declare the NumPy execution path used by stage-wise Mallows kernels.

density(x)[source]

Return the probability of one ordering.

Parameters:

x (Sequence[int])

Return type:

float

log_density(x)[source]

Return the log-probability of one ordering.

Parameters:

x (Sequence[int])

Return type:

float

seq_log_density(x)[source]

Return vectorized log-probabilities for encoded orderings.

Raises:

ValueError – If any row of 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 row 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 log-density, an out-of-range or negative index reaches the numba RIM kernel below, which has no bounds checking of its own and does not raise – it silently scores too, rather than 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 (ndarray)

Return type:

ndarray

sampler(seed=None)[source]

Return an exact repeated-insertion sampler for this model.

Parameters:

seed (int | None)

Return type:

GeneralizedMallowsModelSampler

estimator(pseudo_count=None)[source]

Return a stage-wise Mallows estimator with this item count.

Parameters:

pseudo_count (float | None)

Return type:

GeneralizedMallowsModelEstimator

dist_to_encoder()[source]

Return the full-ranking encoder used by vectorized methods.

Return type:

GeneralizedMallowsModelDataEncoder

class GeneralizedMallowsModelSampler(dist, seed=None)[source]

Bases: DistributionSampler

Exact GMM draws via the per-stage Repeated Insertion Model.

Parameters:

  • dist (GeneralizedMallowsModelDistribution)

  • seed (int | None)

sample(size=None, *, batched=True)[source]

Draw one ordering or size iid orderings.

Parameters:
Return type:

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

class GeneralizedMallowsModelAccumulator(dim, reservoir=10000, keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulate precedence counts and an exact bounded weighted empirical support.

Parameters:

  • dim (int)

  • reservoir (int)

  • keys (str | None)

update(x, weight, estimate)[source]

Update consensus and reservoir statistics from one weighted ordering.

Parameters:
Return type:

None

initialize(x, weight, rng)[source]

Initialize consensus and reservoir statistics from one ordering.

Parameters:
Return type:

None

seq_update(x, weights, estimate)[source]

Update consensus and reservoir statistics from encoded orderings.

Parameters:
Return type:

None

seq_initialize(x, weights, rng)[source]

Initialize statistics from encoded orderings.

Parameters:
Return type:

None

combine(suff_stat)[source]

Merge observation weight, precedence counts, and reservoir samples.

Return type:

GeneralizedMallowsModelAccumulator

value()[source]

Return count, precedence matrix, and bounded reservoir contents.

from_value(x)[source]

Restore accumulator state from value output.

Return type:

GeneralizedMallowsModelAccumulator

acc_to_encoder()[source]

Return the encoder compatible with these sufficient statistics.

Return type:

GeneralizedMallowsModelDataEncoder

class GeneralizedMallowsModelAccumulatorFactory(dim, reservoir=10000, keys=None)[source]

Bases: StatisticAccumulatorFactory

Create accumulators for stage-wise Generalized Mallows statistics.

Parameters:

  • dim (int)

  • reservoir (int)

  • keys (str | None)

make()[source]

Create an empty stage-wise Generalized Mallows accumulator.

Return type:

GeneralizedMallowsModelAccumulator

class GeneralizedMallowsModelEstimator(dim, reservoir=10000, pseudo_count=None, prior_center=None, center_exact_cap=7, allow_approximate_center=False, name=None, keys=None)[source]

Bases: ParameterEstimator

Fit a center and per-stage dispersions from exact weighted empirical support.

Parameters:

  • dim (int)

  • reservoir (int)

  • pseudo_count (float | None)

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

  • center_exact_cap (int)

  • allow_approximate_center (bool)

  • name (str | None)

  • keys (str | None)

accumulator_factory()[source]

Return a factory for stage-wise Mallows sufficient-statistic accumulators.

Return type:

GeneralizedMallowsModelAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate central ordering and per-stage dispersions from accumulated rankings.

Parameters:

nobs (float | None)

Return type:

GeneralizedMallowsModelDistribution

class GeneralizedMallowsModelDataEncoder(dim=None)[source]

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)[source]

Validate and encode full orderings as a dense integer matrix.

Parameters:

x (Sequence[Sequence[int]])

Return type:

ndarray

class GeneralizedMallowsModelFitDiagnostics(center_algorithm, center_exact, centers_evaluated, objective, regularized, pseudo_count)[source]

Bases: object

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

Parameters:

  • center_algorithm (str)

  • center_exact (bool)

  • centers_evaluated (int)

  • objective (float)

  • regularized (bool)

  • pseudo_count (float)