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

Declare the NumPy and numba execution path used by Thurstone kernels.

density(x)

Return the probability of a full ordering.

Parameters:

x (Sequence[int])

Return type:

float

log_density(x)

Return the log-probability of one full ordering.

Parameters:

x (Sequence[int])

Return type:

float

seq_log_density(x)

Return vectorized log-probabilities for encoded full orderings.

Parameters:

x (ndarray)

Return type:

ndarray

sampler(seed=None)

Return an exact random-utility sampler for this distribution.

Parameters:

seed (int | None)

Return type:

ThurstoneSampler

estimator(pseudo_count=None)

Return a Thurstone-Mosteller estimator with this distribution’s dimension.

Parameters:

pseudo_count (float | None)

Return type:

ThurstoneEstimator

dist_to_encoder()

Return the dense full-ranking encoder used by 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 one ordering or size iid orderings.

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)

Update pairwise-precedence counts from one full ordering.

Parameters:

• x (Sequence[int])

• weight (float)

• estimate (Any)

Return type:

None

initialize(x, weight, rng)

Initialize precedence counts from one ordering.

Parameters:

• x (Sequence[int])

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Update pairwise-precedence counts from encoded orderings.

Parameters:

• x (ndarray)

• weights (ndarray)

• estimate (Any)

Return type:

None

seq_initialize(x, weights, rng)

Initialize precedence counts from a batch of encoded orderings.

Parameters:

• x (ndarray)

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Merge count and pairwise-precedence statistics.

Return type:

ThurstoneAccumulator

value()

Return accumulated observation weight and pairwise-precedence matrix.

from_value(x)

Restore accumulator state from value output.

Return type:

ThurstoneAccumulator

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 ranking encoder compatible with this accumulator.

Return type:

ThurstoneDataEncoder

class ThurstoneAccumulatorFactory(dim, keys=None)

Bases: StatisticAccumulatorFactory

Create accumulators for Thurstone pairwise-precedence statistics.

Parameters:

• dim (int)

• keys (str | None)

make()

Create an empty Thurstone accumulator.

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 a factory for Thurstone sufficient-statistic accumulators.

Return type:

ThurstoneAccumulatorFactory

estimate(nobs, suff_stat)

Estimate centered latent utilities from pairwise-precedence statistics.

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)

Validate and encode full orderings as a dense integer matrix.

Parameters:

x (Sequence[Sequence[int]])

Return type:

ndarray