mixle.stats.rankings.thurstone module

Thurstone (Thurstonian) ranking model – the Gaussian random-utility model over permutations.

Each item has a latent utility U_i ~ Normal(mu_i, 1) (Case V, equal variance) and an ordering is the descending sort of the utilities, so

p(sigma) = P( U_sigma[0] > U_sigma[1] > … > U_sigma[n-1] ).

This is the Gaussian counterpart of PlackettLuceDistribution (which is the same construction with Gumbel noise). The probability is the Gaussian-orthant probability of the consecutive-difference cone D_r = U_sigma[r] - U_sigma[r+1] > 0; D has mean mu_sigma[r] - mu_sigma[r+1] and a fixed tridiagonal covariance (2 on the diagonal, -1 off it), independent of sigma. There is no closed form for n > 3, so the likelihood is a numba Genz separation-of-variables Monte-Carlo estimate of the orthant (low variance, always positive) seeded deterministically. Sampling is exact (draw utilities, sort); mu is fit in closed form from the pairwise-preference marginals (the Thurstone-Mosteller Case V estimator), identified up to an additive constant (stored mean-zero).

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

class ThurstoneDistribution(mu, name=None, keys=None, n_mc=4000, seed=0)

Bases: SequenceEncodableProbabilityDistribution

Thurstone Case V Gaussian random-utility ranking model with mean utilities mu.

Parameters:

• mu (Sequence[float] | np.ndarray)

• name (str | None)

• keys (str | None)

• n_mc (int)

• seed (int)

classmethod compute_capabilities()

density(x)

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)

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

Parameters:

x (Sequence[int])

Return type:

float

seq_log_density(x)

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

Parameters:

x (ndarray)

Return type:

ndarray

sampler(seed=None)

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

ThurstoneSampler

estimator(pseudo_count=None)

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

ThurstoneEstimator

dist_to_encoder()

Return the data encoder used by this distribution for vectorized methods.

Return type:

ThurstoneDataEncoder

class ThurstoneSampler(dist, seed=None)

Bases: DistributionSampler

Exact Thurstone draws: sample utilities U ~ Normal(mu, 1) and sort descending.

Parameters:

• dist (ThurstoneDistribution)

• seed (int | None)

sample(size=None)

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 ThurstoneAccumulator(dim, keys=None)

Bases: SequenceEncodableStatisticAccumulator

Accumulate the pairwise-precedence matrix precede[i, j] = weighted count of i ranked before j.

Parameters:

• dim (int)

• keys (str | None)

update(x, weight, estimate)

Parameters:

• x (Sequence[int])

• weight (float)

• estimate (Any)

Return type:

None

initialize(x, weight, rng)

Parameters:

• x (Sequence[int])

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Parameters:

• x (ndarray)

• weights (ndarray)

• estimate (Any)

Return type:

None

seq_initialize(x, weights, rng)

Parameters:

• x (ndarray)

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Return type:

ThurstoneAccumulator

value()

from_value(x)

Return type:

ThurstoneAccumulator

key_merge(stats_dict)

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)

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

Return type:

ThurstoneDataEncoder

class ThurstoneAccumulatorFactory(dim, keys=None)

Bases: StatisticAccumulatorFactory

Parameters:

• dim (int)

• keys (str | None)

make()

Return type:

ThurstoneAccumulator

class ThurstoneEstimator(dim, n_mc=4000, seed=0, name=None, keys=None)

Bases: ParameterEstimator

Thurstone-Mosteller Case V estimator: mu_i - mu_j = sqrt(2) * Phi^{-1}(P(i before j)).

Parameters:

• dim (int)

• n_mc (int)

• seed (int)

• name (str | None)

• keys (str | None)

accumulator_factory()

Return type:

ThurstoneAccumulatorFactory

estimate(nobs, suff_stat)

Parameters:

nobs (float | None)

Return type:

ThurstoneDistribution

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

Encode the iid observation sequence x for vectorized evaluation.

Parameters:

x (Sequence[Sequence[int]])

Return type:

ndarray