ratingslib.ratings.elo module

Elo Rating System

class Elo(version=ratings.ELOWIN, K: int = 40, HA=0, ks=400, starting_point: float = 1500)

Bases: RatingSystem

Elo ranking system developed by Arpad Elo 1 in order to rank chess players, this system has been adopted by quite a lot of sports and organizations.

This implementation includes two basic versions of Elo:

  • The first is called EloWin and takes into account total wins of items. In soccer teams the final outcome determines the winner.

  • The second is called EloPoint and takes into account items scores. In soccer the points are the goals scored be each team.

Note that for any kind of items, there are many ways to define the notion of a hypothetical matchup and then to determine scores and winners.

Parameters

  • version (str, default=ratings.ELOWIN) – a string that shows version of rating system

  • K (int, default=40) – K-factor is the maximum possible adjustment per pair of items. For soccer, K–factor plays an important role because it balances the deviation for the goal difference in the game against prior ratings.

  • HA (int, default=0) – The home advantage factor is an adjustment that is used due to the fact that home teams tend to score more goals. Elo system applies the home-field advantage factor, by adding it to the rating of home team. Many implementations of Elo model for soccer, set the home-field advantage to 100. The default value 0 means that method does not take into account home advantage factor.

  • ks (float, default=400) – Parameter ξ (ks) affects the spread of ratings and comes from logistic function. For chess and soccer games usually, ξ is set to 400.

  • starting_point (float, default = 1500) – The value where the initial rating starts

Notes

Soccer application and Elo: According to the type of soccer tournament the following values represents the K-Factor value suggested by several internet sites 2:

  • World Cup Finals = 60

  • Continental Championship Finals and Major Intercontinental tournaments = 50

  • World Cup Qualifiers and Major Tournaments = 40

  • All other tournaments = 30

  • Friendly matches = 20

References

1

Elo, A. E. (1978). The rating of chessplayers, past and present. Arco Pub.

2

http://www.eloratings.net/about

Examples

The following examples demonstrates the EloWin and the EloPoint version, for the 20 first soccer matches that took place during the 2018-2019 season of English Premier League.

>>> from ratingslib.datasets.filenames import dataset_path, FILENAME_EPL_2018_2019_20_GAMES
>>> from ratingslib.ratings.elo import Elo
>>> from ratingslib.utils.enums import ratings
>>> filename = dataset_path(FILENAME_EPL_2018_2019_20_GAMES)
>>> Elo(version=ratings.ELOWIN, starting_point=0).rate_from_file(filename)
              Item     rating  ranking
0          Arsenal -37.707535       12
1      Bournemouth  37.707535        3
2         Brighton   2.292465        5
3          Burnley -18.849977        9
4          Cardiff -20.000000       10
5          Chelsea  37.707535        3
6   Crystal Palace   0.000000        7
7          Everton  20.000000        4
8           Fulham -37.707535       12
9     Huddersfield -37.707535       12
10       Leicester   1.150023        6
11       Liverpool  40.000000        1
12        Man City  37.707535        3
13      Man United  -2.292465        8
14       Newcastle -20.000000       10
15     Southampton -20.000000       10
16       Tottenham  37.707535        3
17         Watford  38.849977        2
18        West Ham -37.707535       12
19          Wolves -21.150023       11
>>> Elo(version=ratings.ELOPOINT, starting_point=0).rate_from_file(filename)
              Item     rating  ranking
0          Arsenal -11.592411       17
1      Bournemouth  12.658841        5
2         Brighton  -6.337388       14
3          Burnley  -6.091179       13
4          Cardiff  -9.654647       15
5          Chelsea  13.592411        4
6   Crystal Palace   0.191876       10
7          Everton   4.000000        8
8           Fulham -15.861198       18
9     Huddersfield -21.846379       20
10       Leicester   6.230248        7
11       Liverpool  23.141457        1
12        Man City  19.846379        2
13      Man United   0.337388        9
14       Newcastle  -4.345353       12
15     Southampton  -4.000000       11
16       Tottenham   9.861198        6
17         Watford  16.091179        3
18        West Ham -15.992174       19
19          Wolves -10.230248       16
create_rating_vector(data_df: DataFrame, items_df: DataFrame, columns_dict: Optional[Dict[str, Any]] = None) → ndarray

Calculates Elo ratings according to pairs of items data.

computation_phase()

Nothing to compute, all computations are made in ratingslib.ratings.elo.Elo.create_rating_vector() method

preparation_phase(data_df: DataFrame, items_df: DataFrame, columns_dict: Optional[Dict[str, Any]] = None)

To be overridden in subclasses.

rate(data_df: DataFrame, items_df: DataFrame, sort: bool = False, columns_dict: Optional[Dict[str, Any]] = None) → DataFrame

This method computes ratings for a pairwise data. (e.g. soccer teams games). To be overridden in subclasses.

Parameters

  • data_df (pandas.DataFrame) – The pairwise data.

  • items_df (pandas.DataFrame) – Set of items (e.g. teams) to be rated

  • sort (bool, default=True.) – If true, the output is sorted by rating value

  • columns_dict (Optional[Dict[str, str]]) – The column names of data file. See ratingslib.datasets.parameters.COLUMNS_DICT for more details.

Returns

items_df – The set of items with their rating and ranking.

Return type

pandas.DataFrame

static prepare_for_gridsearch_tuning(*, version_list: Optional[List[str]] = None, k_range: Optional[List[float]] = None, ks_range: Optional[List[float]] = None, HA_range: Optional[List[float]] = None) → Dict[str, RatingSystem]

Create instances that are intended for tuning parameters.

Parameters

  • version_list (List[str]) – List of Elo versions

  • k_range (Optional[List[float]], default=None) – List of k values. If None then parameter is not intended for tuning

  • ks_range (Optional[List[float]], default=None) – List of ks values. If None then parameter is not intended for tuning

  • HA_range (Optional[List[float]], default=None) – List of HA values. If None then parameter is not intended for tuning

Returns

rating_systems_dict – Dictionary that contains Elo instances with the parameters we want for tuning.

Return type

dict