openskill.models.weng_lin.thurstone_mosteller_full module

Thurstone-Mosteller Full Pairing Model

Specific classes and functions for the Thurstone-Mosteller Full Pairing model.

class openskill.models.weng_lin.thurstone_mosteller_full.ThurstoneMostellerFull(mu: float = 25.0, sigma: float = 25.0 / 3.0, beta: float = 25.0 / 6.0, kappa: float = 0.0001, epsilon: float = 0.1, gamma: Callable[[float, int, float, float, Sequence[ThurstoneMostellerFullRating], int, List[float] | None], float] = _gamma, tau: float = 25.0 / 300.0, limit_sigma: bool = False, balance: bool = False)

Bases: object

Algorithm 3 by Weng and Lin [2011]

The Thurstone-Mosteller with Full Pairing model assumes a single scalar value to represent player performance and enables rating updates based on match outcomes. Additionally, it employs a maximum likelihood estimation approach to estimate the ratings of players as per the observed outcomes. These assumptions contribute to the model’s ability to estimate ratings accurately and provide a well-founded ranking of players.

Parameters:

• mu –

  Represents the initial belief about the skill of a player before any matches have been played. Known mostly as the mean of the Gaussian prior distribution.

  Represented by: \(\mu\)

• sigma –

  Standard deviation of the prior distribution of player.

  Represented by: \(\sigma = \frac{\mu}{z}\) where \(z\) is an integer that represents the variance of the skill of a player.

• beta –

  Hyperparameter that determines the level of uncertainty or variability present in the prior distribution of ratings.

  Represented by: \(\beta = \frac{\sigma}{2}\)

• kappa –

  Arbitrary small positive real number that is used to prevent the variance of the posterior distribution from becoming too small or negative. It can also be thought of as a regularization parameter.

  Represented by: \(\kappa\)

• epsilon –

  The draw margin for Thurstone-Mosteller models.

  Represented by: \(\epsilon\)

• gamma –

  Custom function you can pass that must contain 5 parameters. The function must return a float or int.

  Represented by: \(\gamma\)

• tau –

  Additive dynamics parameter that prevents sigma from getting too small to increase rating change volatility.

  Represented by: \(\tau\)

• limit_sigma – Boolean that determines whether to restrict the value of sigma from increasing.

• balance – Boolean that determines whether to emphasize rating outliers.

static _a(team_ratings: List[ThurstoneMostellerFullTeamRating]) → List[int]

Count the number of times a rank appears in the list of team ratings.

Represented by:

\[A_q = |\{s: r(s) = r(q)\}|, q = 1,...,k\]

Parameters:

team_ratings – The whole rating of a list of teams in a game.

Returns:

A list of floats.

_c(team_ratings: List[ThurstoneMostellerFullTeamRating]) → float

Calculate the square root of the collective team sigma.

Represented by:

\[c = \Biggl(\sum_{i=1}^k (\sigma_i^2 + \beta^2) \Biggr)\]

Algorithm 4: Procedure 3 in [Weng and Lin, 2011]

Parameters:

team_ratings – The whole rating of a list of teams in a game.

Returns:

A number.

_calculate_rankings(game: Sequence[Sequence[ThurstoneMostellerFullRating]], ranks: List[float] | None = None) → List[int]

Calculates the rankings based on the scores or ranks of the teams.

It assigns a rank to each team based on their score, with the team with the highest score being ranked first.

Parameters:

• game – A list of teams, where teams are lists of ThurstoneMostellerFullRating objects.

• ranks – A list of ranks for each team in the game.

Returns:

A list of ranks for each team in the game.

_calculate_team_ratings(game: Sequence[Sequence[ThurstoneMostellerFullRating]], ranks: List[float] | None = None, weights: List[List[float]] | None = None) → List[ThurstoneMostellerFullTeamRating]

Get the team ratings of a game.

Parameters:

• game – A list of teams, where teams are lists of ThurstoneMostellerFullRating objects.

• ranks – A list of ranks for each team in the game.

• weights – A list of lists of floats, where each inner list represents the contribution of each player to the team’s performance. The values should be normalized from 0 to 1.

Returns:

A list of ThurstoneMostellerFullTeamRating objects.

static _check_teams(teams: List[List[ThurstoneMostellerFullRating]]) → None

Ensure teams argument is valid.

Parameters:

teams – List of lists of ThurstoneMostellerFullRating objects.

_compute(teams: Sequence[Sequence[ThurstoneMostellerFullRating]], ranks: List[float] | None = None, weights: List[List[float]] | None = None) → List[List[ThurstoneMostellerFullRating]]

static _sum_q(team_ratings: List[ThurstoneMostellerFullTeamRating], c: float) → List[float]

Sum up all the values of mu / c raised to \(e\).

Represented by:

\[\sum_{s \in C_q} e^{\theta_s / c}, q=1, ...,k, \text{where } C_q = \{i: r(i) \geq r(q)\}\]

Algorithm 4: Procedure 3 in [Weng and Lin, 2011]

Parameters:

• team_ratings – The whole rating of a list of teams in a game.

• c – The square root of the collective team sigma.

Returns:

A list of floats.

static create_rating(rating: List[float], name: str | None = None) → ThurstoneMostellerFullRating

Create a ThurstoneMostellerFullRating object from a list of mu and sigma values.

Parameters:

• rating – A list of two values where the first value is the mu and the second value is the sigma.

• name – An optional name for the player.

Returns:

A ThurstoneMostellerFullRating object created from the list passed in.

predict_draw(teams: List[List[ThurstoneMostellerFullRating]]) → float

Predict how likely a match up against teams of one or more players will draw. This algorithm has a time complexity of \(\mathcal{0}(n^2)\) where ‘n’ is the number of teams.

Parameters:

teams – A list of two or more teams.

Returns:

The odds of a draw.

predict_rank(teams: List[List[ThurstoneMostellerFullRating]]) → List[Tuple[int, float]]

Predict the shape of a match outcome. This algorithm has a time complexity of \(\mathcal{0}(n^2)\) where ‘n’ is the number of teams.

Parameters:

teams – A list of two or more teams.

Returns:

A list of team ranks with their probabilities.

predict_win(teams: List[List[ThurstoneMostellerFullRating]]) → List[float]

Predict how likely a match up against teams of one or more players will go. This algorithm has a time complexity of \(\mathcal{0}(n^2)\) where ‘n’ is the number of teams.

This is a generalization of the algorithm in [Ibstedt et al., 2019] to asymmetric n-player n-teams.

Parameters:

teams – A list of two or more teams.

Returns:

A list of odds of each team winning.

rate(teams: List[List[ThurstoneMostellerFullRating]], ranks: List[float] | None = None, scores: List[float] | None = None, weights: List[List[float]] | None = None, tau: float | None = None, limit_sigma: bool | None = None) → List[List[ThurstoneMostellerFullRating]]

Calculate the new ratings based on the given teams and parameters.

Parameters:

• teams – A list of teams where each team is a list of ThurstoneMostellerFullRating objects.

• ranks – A list of floats where the lower values represent winners.

• scores – A list of floats where higher values represent winners.

• weights – A list of lists of floats, where each inner list represents the contribution of each player to the team’s performance.

• tau – Additive dynamics parameter that prevents sigma from getting too small to increase rating change volatility.

• limit_sigma – Boolean that determines whether to restrict the value of sigma from increasing.

Returns:

A list of teams where each team is a list of updated ThurstoneMostellerFullRating objects.

rating(mu: float | None = None, sigma: float | None = None, name: str | None = None) → ThurstoneMostellerFullRating

Returns a new rating object with your default parameters. The given parameters can be overridden from the defaults provided by the main model, but is not recommended unless you know what you are doing.

Parameters:

• mu –

  Represents the initial belief about the skill of a player before any matches have been played. Known mostly as the mean of the Gaussian prior distribution.

  Represented by: \(\mu\)

• sigma –

  Standard deviation of the prior distribution of player.

  Represented by: \(\sigma = \frac{\mu}{z}\) where \(z\) is an integer that represents the variance of the skill of a player.

• name – Optional name for the player.

Returns:

ThurstoneMostellerFullRating object

class openskill.models.weng_lin.thurstone_mosteller_full.ThurstoneMostellerFullRating(mu: float, sigma: float, name: str | None = None)

Bases: object

Thurstone-Mosteller Full Pairing player rating data.

This object is returned by the ThurstoneMostellerFull.rating method.

Parameters:

• mu –

  Represents the initial belief about the skill of a player before any matches have been played. Known mostly as the mean of the Gaussian prior distribution.

  Represented by: \(\mu\)

• sigma –

  Standard deviation of the prior distribution of player.

  Represented by: \(\sigma = \frac{\mu}{z}\) where \(z\) is an integer that represents the variance of the skill of a player.

• name – Optional name for the player.

ordinal(z: float = 3.0, alpha: float = 1, target: float = 0) → float

A single scalar value that represents the player’s skill where their true skill is 99.7% likely to be higher.

Parameters:

• z – Float that represents the number of standard deviations to subtract from the mean. By default, set to 3.0, which corresponds to a 99.7% confidence interval in a normal distribution.

• alpha – Float scaling factor applied to the entire calculation. Adjusts the overall scale of the ordinal value. Defaults to 1.

• target – Float value used to shift the ordinal value towards a specific target. The shift is adjusted by the alpha scaling factor. Defaults to 0.

Returns:

\(\alpha \cdot ((\mu - z * \sigma) + \frac{\text{target}}{\alpha})\)