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)

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)

classmethod compute_capabilities()

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

density(x)

Return the probability of one ordering.

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 an exact repeated-insertion sampler for this model.

Parameters:

seed (int | None)

Return type:

GeneralizedMallowsModelSampler

estimator(pseudo_count=None)

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

Parameters:

pseudo_count (float | None)

Return type:

GeneralizedMallowsModelEstimator

dist_to_encoder()

Return the full-ranking encoder used by vectorized methods.

Return type:

GeneralizedMallowsModelDataEncoder

class GeneralizedMallowsModelSampler(dist, seed=None)

Bases: DistributionSampler

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

Parameters:

• dist (GeneralizedMallowsModelDistribution)

• seed (int | None)

sample(size=None)

Draw one ordering or size iid orderings.

Parameters:

size (int | None)

Return type:

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

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

Bases: SequenceEncodableStatisticAccumulator

Precede matrix (Copeland consensus) + count + a bounded reservoir for the per-stage means.

Parameters:

• dim (int)

• reservoir (int)

• keys (str | None)

update(x, weight, estimate)

Update consensus and reservoir statistics from one weighted ordering.

Parameters:

• x (Sequence[int])

• weight (float)

• estimate (Any)

Return type:

None

initialize(x, weight, rng)

Initialize consensus and reservoir statistics from one ordering.

Parameters:

• x (Sequence[int])

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Update consensus 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 observation weight, precedence counts, and reservoir samples.

Return type:

GeneralizedMallowsModelAccumulator

value()

Return count, precedence matrix, and bounded reservoir contents.

from_value(x)

Restore accumulator state from value output.

Return type:

GeneralizedMallowsModelAccumulator

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 encoder compatible with these sufficient statistics.

Return type:

GeneralizedMallowsModelDataEncoder

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

Bases: StatisticAccumulatorFactory

Create accumulators for stage-wise Generalized Mallows statistics.

Parameters:

• dim (int)

• reservoir (int)

• keys (str | None)

make()

Create an empty stage-wise Generalized Mallows accumulator.

Return type:

GeneralizedMallowsModelAccumulator

class GeneralizedMallowsModelEstimator(dim, reservoir=10000, name=None, keys=None)

Bases: ParameterEstimator

Copeland consensus for sigma0 and a per-stage moment match for each theta_i.

Parameters:

• dim (int)

• reservoir (int)

• name (str | None)

• keys (str | None)

accumulator_factory()

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

Return type:

GeneralizedMallowsModelAccumulatorFactory

estimate(nobs, suff_stat)

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

Parameters:

nobs (float | None)

Return type:

GeneralizedMallowsModelDistribution

class GeneralizedMallowsModelDataEncoder(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