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

classmethod compute_capabilities()[source]
density(x)[source]

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

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

Parameters:

x (Sequence[int])

Return type:

float

seq_log_density(x)[source]

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

Parameters:

x (ndarray)

Return type:

ndarray

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

GeneralizedMallowsModelSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

GeneralizedMallowsModelEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for 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)[source]

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 GeneralizedMallowsModelAccumulator(dim, reservoir=10000, keys=None)[source]

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)[source]
Parameters:
Return type:

None

initialize(x, weight, rng)[source]
Parameters:
Return type:

None

seq_update(x, weights, estimate)[source]
Parameters:
Return type:

None

seq_initialize(x, weights, rng)[source]
Parameters:
Return type:

None

combine(suff_stat)[source]
Return type:

GeneralizedMallowsModelAccumulator

value()[source]
from_value(x)[source]
Return type:

GeneralizedMallowsModelAccumulator

key_merge(stats_dict)[source]

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

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()[source]
Return type:

GeneralizedMallowsModelDataEncoder

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

Bases: StatisticAccumulatorFactory

Parameters:

  • dim (int)

  • reservoir (int)

  • keys (str | None)

make()[source]
Return type:

GeneralizedMallowsModelAccumulator

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

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()[source]
Return type:

GeneralizedMallowsModelAccumulatorFactory

estimate(nobs, suff_stat)[source]
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]

Encode the iid observation sequence x for vectorized evaluation.

Parameters:

x (Sequence[Sequence[int]])

Return type:

ndarray