openskill.models.weng_lin.plackett_luce
¶
PlackettLuce Model
Specific classes and functions for the PlackettLuce model.
Module Contents¶
Classes¶
Algorithm 4 by Weng and Lin [2011] 

PlackettLuce player rating data. 
 class openskill.models.weng_lin.plackett_luce.PlackettLuce(mu=25.0, sigma=25.0 / 3.0, beta=25.0 / 6.0, kappa=0.0001, gamma=_gamma, tau=25.0 / 300.0, limit_sigma=False)[source]¶
Algorithm 4 by Weng and Lin [2011]
The PlackettLuce model departs from single scalar representations of player performance present in simpler models. There is a vector of abilities for each player that captures their performance across multiple dimensions. The outcome of a match between multiple players depends on their abilities in each dimension. By introducing this multidimensional aspect, the PlackettLuce model provides a richer framework for ranking players based on their abilities in various dimensions.
 Parameters:
Represents the initial belief about the skill of a player before any matches have been played. Known mostly as the mean of the Guassian prior distribution.
Represented by: \(\mu\)
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.
Hyperparameter that determines the level of uncertainty or variability present in the prior distribution of ratings.
Represented by: \(\beta = \frac{\sigma}{2}\)
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\)
gamma (Callable[[Union[int, float], int, Union[int, float], Union[int, float], Sequence[PlackettLuceRating], int], Union[int, float]]) –
Custom function you can pass that must contain 5 parameters. The function must return a float or int.
Represented by: \(\gamma\)
Additive dynamics parameter that prevents sigma from getting too small to increase rating change volatility.
Represented by: \(\tau\)
limit_sigma (bool) – Boolean that determines whether to restrict the value of sigma from increasing.
 static _a(team_ratings)[source]¶
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 (List[PlackettLuceTeamRating]) – The whole rating of a list of teams in a game.
 Returns:
A list of Decimals.
 Return type:
List[int]
 _c(team_ratings)[source]¶
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]
 _calculate_rankings(game, ranks=None)[source]¶
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 (Sequence[Sequence[PlackettLuceRating]]) – A list of teams, where teams are lists of
PlackettLuceRating
objects.ranks (Optional[List[Union[int, float]]]) – A list of ranks for each team in the game.
 Returns:
A list of ranks for each team in the game.
 Return type:
List[int]
 _calculate_team_ratings(game, ranks=None)[source]¶
Get the team ratings of a game.
 Parameters:
game (Sequence[Sequence[PlackettLuceRating]]) – A list of teams, where teams are lists of
PlackettLuceRating
objects.ranks (Optional[List[Union[int, float]]]) – A list of ranks for each team in the game.
 Returns:
A list of
PlackettLuceTeamRating
objects. Return type:
List[PlackettLuceTeamRating]
 static _check_teams(teams)[source]¶
Ensure teams argument is valid. :param teams: List of lists of PlackettLuceRating objects.
 Parameters:
teams (List[List[PlackettLuceRating]]) –
 Return type:
None
 static _sum_q(team_ratings, c)[source]¶
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]
 static create_rating(rating, name=None)[source]¶
Create a
PlackettLuceRating
object from a list of mu and sigma values. Parameters:
 Returns:
A
PlackettLuceRating
object created from the list passed in. Return type:
 predict_draw(teams)[source]¶
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!/(n  2)!)\) where ‘n’ is the number of teams.
 Parameters:
teams (List[List[PlackettLuceRating]]) – A list of two or more teams.
 Returns:
The odds of a draw.
 Return type:
 predict_rank(teams)[source]¶
Predict the shape of a match outcome. This algorithm has a time complexity of \(\mathcal{0}(n!/(n  2)!)\) where ‘n’ is the number of teams.
 Parameters:
teams (List[List[PlackettLuceRating]]) – A list of two or more teams.
 Returns:
A list of team ranks with their probabilities.
 Return type:
 predict_win(teams)[source]¶
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!/(n  2)!)\) where ‘n’ is the number of teams.
This is a generalization of the algorithm in [Ibstedt et al., 2019] to asymmetric nplayer nteams.
 Parameters:
teams (List[List[PlackettLuceRating]]) – A list of two or more teams.
 Returns:
A list of odds of each team winning.
 Return type:
 rate(teams, ranks=None, scores=None, tau=None, limit_sigma=None)[source]¶
Calculate the new ratings based on the given teams and parameters.
 Parameters:
teams (List[List[PlackettLuceRating]]) – A list of teams where each team is a list of
PlackettLuceRating
objects.ranks (Optional[List[Union[int, float]]]) – A list of Decimals where the lower values represent winners.
scores (Optional[List[Union[int, float]]]) – A list of Decimals where higher values represent winners.
tau (Optional[Union[int, float]]) – Additive dynamics parameter that prevents sigma from getting too small to increase rating change volatility.
limit_sigma (Optional[bool]) – 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
PlackettLuceRating
objects. Return type:
List[List[PlackettLuceRating]]
 rating(mu=None, sigma=None, name=None)[source]¶
Returns a new rating object with your default parameters. The given parameters can be overriden from the defaults provided by the main model, but is not recommended unless you know what you are doing.
 Parameters:
mu (Optional[Union[int, float]]) –
Represents the initial belief about the skill of a player before any matches have been played. Known mostly as the mean of the Guassian prior distribution.
Represented by: \(\mu\)
sigma (Optional[Union[int, float]]) –
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[str]) – Optional name for the player.
 Returns:
PlackettLuceRating
object Return type:
 class openskill.models.weng_lin.plackett_luce.PlackettLuceRating(mu, sigma, name=None)[source]¶
PlackettLuce player rating data.
This object is returned by the
PlackettLuce.rating
method. Parameters:
Represents the initial belief about the skill of a player before any matches have been played. Known mostly as the mean of the Guassian prior distribution.
Represented by: \(\mu\)
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[str]) – Optional name for the player.