mixle.stats.rankings.paired_comparison module¶

Paired-comparison models beyond plain Bradley-Terry: Gaussian pairwise and ties.

Three canonical models that complete the pairwise-comparison family:

ThurstoneMostellerDistribution – the Gaussian (probit) pairwise model P(i beats j) = Phi((mu_i - mu_j) / sqrt(2)); the pairwise peer of ThurstoneDistribution and the Gaussian counterpart of BradleyTerryDistribution. Observation: (winner, loser).
DavidsonDistribution – Bradley-Terry with ties (Davidson 1970): a draw has probability nu * sqrt(w_i w_j) / (w_i + w_j + nu sqrt(w_i w_j)). Observation: (i, j, outcome) with outcome in {0: i wins, 1: j wins, 2: tie}.
RaoKupperDistribution – Bradley-Terry with ties via a threshold nu >= 1 (Rao-Kupper 1967): P(i beats j) = w_i / (w_i + nu w_j). Same (i, j, outcome) observation.

All three treat the compared pair as a uniform draw over the C(K, 2) unordered pairs, making them proper distributions over (canonicalized) comparison outcomes. Worths/utilities are identified up to a shift and stored mean-zero. Fitting maximizes the comparison log-likelihood from the win/tie count matrices (the sufficient statistic).

class ThurstoneMostellerDistribution(mu, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Gaussian/probit paired-comparison model P(i beats j) = Phi((mu_i - mu_j) / sqrt(2)).

Parameters:

mu (Sequence[float] | np.ndarray)
name (str | None)
keys (str | None)

classmethod compute_capabilities()[source]: Return backend capabilities for the probit pairwise likelihood.

density(x)[source]

Return the probability mass of one winner-loser pair.

Parameters:: x (tuple[int, int])
Return type:: float

log_density(x)[source]

Return the log probability of one winner-loser pair.

Parameters:: x (tuple[int, int])
Return type:: float

seq_log_density(x)[source]

Score encoded winner-loser pairs.

Parameters:: x (ndarray)
Return type:: ndarray

sampler(seed=None)[source]

Return a sampler for winner-loser comparisons.

Parameters:: seed (int | None)
Return type:: ThurstoneMostellerSampler

estimator(pseudo_count=None)[source]

Return the least-squares probit paired-comparison estimator.

Parameters:: pseudo_count (float | None)
Return type:: ThurstoneMostellerEstimator

dist_to_encoder()[source]

Return the encoder for winner-loser pair data.

Return type:: PairDataEncoder

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

Bases: DistributionSampler

Sampler for Thurstone-Mosteller winner-loser comparisons.

Parameters:

dist (ThurstoneMostellerDistribution)
seed (int | None)

sample(size=None)[source]

Draw one comparison or a list of comparisons.

Parameters:: size (int | None)
Return type:: tuple[int, int] | list[tuple[int, int]]

class ThurstoneMostellerEstimator(dim, name=None, keys=None)[source]

Bases: ParameterEstimator

mu_i - mu_j = sqrt(2) Phi^{-1}(P(i beats j)) from the win-count matrix (least squares).

Parameters:

dim (int)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the accumulator factory used by this estimator.

Return type:: PairWinAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate Thurstone-Mosteller utilities from win-count statistics.

Parameters:: nobs (float | None)
Return type:: ThurstoneMostellerDistribution

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

Bases: SequenceEncodableStatisticAccumulator

Win-count matrix wins[i, j] for (winner, loser) pair data.

Parameters:

dim (int)
keys (str | None)

update(x, weight, estimate)[source]

Accumulate one weighted winner-loser observation.

Parameters:

x (tuple[int, int])
weight (float)
estimate (Any)

Return type:

None

initialize(x, weight, rng)[source]

Initialize sufficient statistics from one weighted pair.

Parameters:

x (tuple[int, int])
weight (float)
rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)[source]

Accumulate weighted winner-loser pairs from an encoded batch.

Parameters:

x (ndarray)
weights (ndarray)
estimate (Any)

Return type:

None

seq_initialize(x, weights, rng)[source]

Initialize sufficient statistics from an encoded weighted batch.

Parameters:

x (ndarray)
weights (ndarray)
rng (RandomState | None)

Return type:

None

combine(suff_stat)[source]

Merge serialized win-count sufficient statistics.

Return type:: PairWinAccumulator

value()[source]: Return serialized win-count sufficient statistics.

from_value(x)[source]

Restore accumulator state from serialized win counts.

Return type:: PairWinAccumulator

key_merge(stats_dict)[source]

Merge tied win-count statistics into stats_dict.

Parameters:: stats_dict (dict[str, Any])
Return type:: None

key_replace(stats_dict)[source]

Replace tied win-count statistics from stats_dict.

Parameters:: stats_dict (dict[str, Any])
Return type:: None

acc_to_encoder()[source]

Return the encoder associated with this accumulator.

Return type:: PairDataEncoder

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

Bases: StatisticAccumulatorFactory

Factory for paired win-count accumulators.

Parameters:

dim (int)
keys (str | None)

make()[source]

Create a fresh paired-win accumulator.

Return type:: PairWinAccumulator

class PairDataEncoder(dim=None)[source]

Bases: DataSequenceEncoder

Encode (winner, loser) pairs into an (N, 2) integer array.

Parameters:: dim (int | None)

seq_encode(x)[source]

Encode winner-loser pairs as an integer (N, 2) array.

Parameters:: x (Sequence[tuple[int, int]])
Return type:: ndarray

class DavidsonDistribution(log_w, nu=1.0, name=None, keys=None)[source]

Bases: _BaseTieDistribution

Bradley-Terry with ties (Davidson 1970); tie mass nu sqrt(w_i w_j).

Parameters:

nu (float)
name (str | None)
keys (str | None)

estimator(pseudo_count=None)[source]

Return the maximum-likelihood Davidson estimator.

Parameters:: pseudo_count (float | None)

class DavidsonEstimator(dim, name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood Davidson worths and tie parameter (L-BFGS on the count matrices).

Parameters:

dim (int)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the accumulator factory used by this estimator.

Return type:: _TieAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate Davidson worths and tie parameter from sufficient statistics.

Parameters:: nobs (float | None)
Return type:: DavidsonDistribution

class RaoKupperDistribution(log_w, nu=1.5, name=None, keys=None)[source]

Bases: _BaseTieDistribution

Bradley-Terry with ties via a threshold nu >= 1 (Rao-Kupper 1967).

Parameters:

nu (float)
name (str | None)
keys (str | None)

estimator(pseudo_count=None)[source]

Return the maximum-likelihood Rao-Kupper estimator.

Parameters:: pseudo_count (float | None)

class RaoKupperEstimator(dim, name=None, keys=None)[source]

Bases: ParameterEstimator

Maximum-likelihood Rao-Kupper worths and threshold (L-BFGS on the count matrices).

Parameters:

dim (int)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return the accumulator factory used by this estimator.

Return type:: _TieAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate Rao-Kupper worths and threshold from sufficient statistics.

Parameters:: nobs (float | None)
Return type:: RaoKupperDistribution