mixle.stats.rankings.thurstone module

Thurstone ranking model as a normalized Gaussian random-utility approximation.

Each item has latent utility U_i ~ Normal(mu_i, 1) and a ranking is the descending ordering of those utilities. Exact ranking probabilities are Gaussian orthant probabilities and have no general closed form.

This implementation exposes an explicitly labelled, deterministic finite-sample approximation. n_mc common random-utility draws are converted to ranking counts and combined with positive symmetric Dirichlet smoothing. That construction is a proper categorical distribution: probabilities are exactly normalized, a datum’s score cannot depend on its batch neighbors, and the sampler draws from the same represented law. Every distribution records the approximation provenance and conservative binomial error scale.

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

class ThurstoneApproximationDiagnostics(method, draws, seed, smoothing, distinct_rankings, support_size, maximum_binomial_standard_error)[source]

Bases: object

Provenance and uncertainty scale for the approximating categorical law.

Parameters:

  • method (str)

  • draws (int)

  • seed (int)

  • smoothing (float)

  • distinct_rankings (int)

  • support_size (int)

  • maximum_binomial_standard_error (float)

class ThurstoneFitDiagnostics(method, exact_mle, regularized, pseudo_count)[source]

Bases: object

Provenance for an estimated Thurstone utility vector.

Parameters:
class ThurstoneDistribution(mu, name=None, keys=None, n_mc=4000, seed=0, smoothing=0.5, fit_diagnostics=None, *, _mu_already_centered=False)[source]

Bases: SequenceEncodableProbabilityDistribution

Normalized finite-sample approximation to a Case V Thurstone law.

Parameters:

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

  • name (str | None)

  • keys (str | None)

  • n_mc (int)

  • seed (int)

  • smoothing (float)

  • fit_diagnostics (ThurstoneFitDiagnostics | None)

  • _mu_already_centered (bool)

classmethod compute_capabilities()[source]

Declare the NumPy execution path used to build the approximation.

density(x)[source]

Return the normalized approximating probability of a full ordering.

Parameters:

x (Sequence[int])

Return type:

float

log_density(x)[source]

Return the normalized approximating log-probability of one ordering.

Parameters:

x (Sequence[int])

Return type:

float

seq_log_density(x)[source]

Return batch-invariant log-probabilities for encoded full orderings.

Parameters:

x (ndarray)

Return type:

ndarray

sampler(seed=None)[source]

Return a sampler for this exact approximating categorical law.

Parameters:

seed (int | None)

Return type:

ThurstoneSampler

support_size()[source]

Return the number of full rankings in the smoothed support.

Return type:

int

estimator(pseudo_count=None)[source]

Return a labelled Thurstone-Mosteller pairwise-moment estimator.

Parameters:

pseudo_count (float | None)

Return type:

ThurstoneEstimator

dist_to_encoder()[source]

Return the dense full-ranking encoder used by vectorized methods.

Return type:

ThurstoneDataEncoder

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

Bases: DistributionSampler

Draw exactly from a distribution’s empirical-plus-uniform mixture.

Parameters:

  • dist (ThurstoneDistribution)

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

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted pairwise-precedence counts from full rankings.

Parameters:
update(x, weight, estimate)[source]

Update pairwise-precedence counts from one full ordering.

Parameters:
Return type:

None

initialize(x, weight, rng)[source]

Initialize precedence counts from one ordering.

Parameters:
Return type:

None

seq_update(x, weights, estimate)[source]

Update pairwise-precedence counts from encoded orderings.

Parameters:
Return type:

None

seq_initialize(x, weights, rng)[source]

Initialize precedence counts from a batch of encoded orderings.

Parameters:
Return type:

None

combine(suff_stat)[source]

Merge validated count and pairwise-precedence statistics.

Parameters:

suff_stat (tuple[float, ndarray])

Return type:

ThurstoneAccumulator

value()[source]

Return an ownership-safe statistics snapshot.

Return type:

tuple[float, ndarray]

from_value(x)[source]

Restore validated accumulator state.

Parameters:

x (tuple[float, ndarray])

Return type:

ThurstoneAccumulator

acc_to_encoder()[source]

Return the ranking encoder compatible with this accumulator.

Return type:

ThurstoneDataEncoder

class ThurstoneAccumulatorFactory(dim, keys=None)[source]

Bases: StatisticAccumulatorFactory

Create accumulators for Thurstone pairwise-precedence statistics.

Parameters:
make()[source]

Create an empty Thurstone accumulator.

Return type:

ThurstoneAccumulator

class ThurstoneEstimator(dim, n_mc=4000, seed=0, smoothing=0.5, pseudo_count=None, name=None, keys=None)[source]

Bases: ParameterEstimator

Labelled pairwise-moment estimator for Case V Thurstone utilities.

Parameters:
accumulator_factory()[source]

Return a factory for Thurstone sufficient-statistic accumulators.

Return type:

ThurstoneAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate centered utilities from validated pairwise-precedence statistics.

Parameters:
Return type:

ThurstoneDistribution

class ThurstoneDataEncoder(dim=None)[source]

Bases: DataSequenceEncoder

Encode full item orderings into a dense integer matrix.

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

row_count(x)[source]

Return the number of encoded ranking rows.

Parameters:

x (ndarray)

Return type:

int