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 ThurstoneMostellerFitDiagnostics(method, exact_mle, graph_connected, clipped_pair_probabilities, regularized, pseudo_count, strongly_connected)[source]

Bases: object

Provenance and identifiability evidence for the pairwise-moment fit.

Parameters:

  • method (str)

  • exact_mle (bool)

  • graph_connected (bool)

  • clipped_pair_probabilities (int)

  • regularized (bool)

  • pseudo_count (float)

  • strongly_connected (bool)

class TieModelFitDiagnostics(model, converged, status, message, iterations, objective, gradient_norm, worth_boundary_hit, tie_parameter_boundary_hit, graph_connected, regularized, pseudo_count, strongly_connected)[source]

Bases: object

Optimizer, identifiability, and boundary evidence for a tie-model fit.

Parameters:

  • model (str)

  • converged (bool)

  • status (int)

  • message (str)

  • iterations (int)

  • objective (float)

  • gradient_norm (float)

  • worth_boundary_hit (bool)

  • tie_parameter_boundary_hit (bool)

  • graph_connected (bool)

  • regularized (bool)

  • pseudo_count (float)

  • strongly_connected (bool)

class ThurstoneMostellerDistribution(mu, name=None, keys=None, fit_diagnostics=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)

  • fit_diagnostics (ThurstoneMostellerFitDiagnostics | 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 JOINT log probability of one winner-loser pair.

The pair is drawn uniformly from all K(K-1)/2 unordered pairs and the winner follows the probit rule, so exp(log_density((i, j))) + exp(log_density((j, i))) is 1/C(K, 2), not one. P(i beats j | compared) is win_probability().

Parameters:

x (tuple[int, int])

Return type:

float

win_probability(i, j)[source]

Return P(i beats j | i and j are compared) = Phi((mu[i] - mu[j]) / sqrt(2)).

Parameters:
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, *, batched=True)[source]

Draw one comparison or a list of comparisons.

Parameters:
Return type:

tuple[int, int] | list[tuple[int, int]]

class ThurstoneMostellerEstimator(dim, pseudo_count=None, 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).

pseudo_count adds that many fractional wins to every ordered pair before the moment step; see BradleyTerryEstimator for how to choose it and what it does to margins. Here it also keeps a never-lost pair away from the Phi^{-1} clip (clipped_pair_probabilities counts the pairs that hit it).

Parameters:

  • dim (int)

  • pseudo_count (float | None)

  • 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:
update(x, weight, estimate)[source]

Accumulate one weighted winner-loser observation.

Parameters:
Return type:

None

initialize(x, weight, rng)[source]

Initialize sufficient statistics from one weighted pair.

Parameters:
Return type:

None

seq_update(x, weights, estimate)[source]

Accumulate weighted winner-loser pairs from an encoded batch.

Parameters:
Return type:

None

seq_initialize(x, weights, rng)[source]

Initialize sufficient statistics from an encoded weighted batch.

Parameters:
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

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:
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, fit_diagnostics=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)

  • fit_diagnostics (TieModelFitDiagnostics | None)

estimator(pseudo_count=None)[source]

Return the maximum-likelihood Davidson estimator.

Parameters:

pseudo_count (float | None)

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

Bases: ParameterEstimator

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

pseudo_count adds that many fractional wins to every ordered pair and that many ties to every unordered pair; see BradleyTerryEstimator for how to choose it. Without it, data in which some competitor never lost (or never won) has no finite fit and the estimator raises ValueError rather than return a boundary worth.

Parameters:

  • dim (int)

  • pseudo_count (float | None)

  • 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, fit_diagnostics=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)

  • fit_diagnostics (TieModelFitDiagnostics | None)

estimator(pseudo_count=None)[source]

Return the maximum-likelihood Rao-Kupper estimator.

Parameters:

pseudo_count (float | None)

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

Bases: ParameterEstimator

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

pseudo_count adds that many fractional wins to every ordered pair and that many ties to every unordered pair; see BradleyTerryEstimator for how to choose it. Without it, data in which some competitor never lost (or never won) has no finite fit and the estimator raises ValueError rather than return a boundary worth.

Parameters:

  • dim (int)

  • pseudo_count (float | None)

  • 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