Elo Rating System ================= Context ------- The *Elo rating system* is a mathematical method used to calculate the relative skill levels of players in zero-sum games like chess, created by Hungarian-American physics professor Arpad Elo in 1960. It was adopted by the International Chess Federation (FIDE) in 1970. Currently the system has been improved by platforms such as lichess and chess.com but we shall consider its simpler, original version. Let's see how it works. Consider the following temrs: - **Score**: The score of a chess match between a player and his/her oponent is either *win* (1 point), *loss* (0 points) or *draw* (0.5 points). - **Elo** It is a positive integer intended to reflect the level of a player relative to the players community. - **Initial Elo**: The organization provides a new player with a fixed initial elo amount. - **Expected Score**: The system calculates the *probability* of a win, loss, or draw based on the rating difference between two opponents. For example, a player rated 100 points higher is expected to win roughly 64% of their games. This probability is computed by the following formula where :math:`elo_{you}, elo_{oponent}` are the player's and the oponent's elo ratings (the constant 400 value is a convention): .. math:: E(elo_{you}, elo_{oponent}) = \frac {1} {1 + {10}^{\frac{elo_{oponent} - elo_{you}} {400}}} :label: Expected Score - **Elo Update**: You gain points when you perform better than expected (e.g., beating a higher-rated player), you lose points when you perform worse than expected, and you neither gain nor loose points if you draw to a player rated like to you. The formula to compute that is as follows: .. math:: elo_{new} = elo + k*(S-E(elo, elo_{oponent}) :label: Elo Update where :math:`elo` is the current elo, :math:`S` is the *actual score* (win=1, draw=0.5, loss=0), :math:`E` is the *expected score* and `k` is a constant factor that determines how much influence a single match has on your elo. It is decided by the organization. Since the result of this formula might have decimals but the elo rating used in reality is an integer value, the result is rounded to no decimals. These formulae are needed to implement some of the requested functions but you don't have to implement then since their respective Python functions are available in the :download:`elo_f.py` file: .. literalinclude:: elo_f.py :language: python3 Goal ---- Now, we wish to process the results of a number of players. The information in represented as a **Players List** where for each player we have the name, current elo and a list of results (scores) from a number of matches (not necessarily the same number for each player). See an example below: .. literalinclude:: elo_players_list.txt :language: pycon Observe that the **Scores List** is a :class:`list` of :class:`tuple`. Each tuple has two components: #. the score properly: a :class:`float` value that is either 1.0, 0.5 or 0.0 #. the oponent elo: an :class:`int` with the elo rating of the oponent player at the time the match was played. Bearing these data structures in mind, you are required to implement the following functions and deliver them in the module :mod:`elo` (file :file:`elo.py`). The weights of these functions are 10%, 50% and 40% respectively. .. warning:: Do not leave pieces of code that are wither incomplete or contain syntax errors in the .py file to deliver since that would result in a 0.0 grade for the whole problem. Auxiliar Function ----------------- This is an auxiliar funcion that will be useful to implement the main functions later on. It is intended to compute the new elo of a player that played a number of matches. Hence, the new elo is calculated from the current elo and the score list of those matches: .. py:function:: elo_calculate(ini_elo, scoreL, k) such that **given** - *`elo*, :class:`int` representing the player's current elo. - *scoreL* a scores list as described above. - *k*, :class:`int` the k factor. **returns** a :class:`int` with the new elo calculated from the current elo, the scores in *scoreL* sequentially in that order, using the given *k* factor and applying the *Elo Update* formula above (2). For example: .. literalinclude:: elo_calculate.test :language: pycon :start-after: --ini :end-before: --fi Doctests are available in the :download:`elo_calculate.test` file. Main Function #1 ---------------- This function is intended to separate the players according to the change in their elo rating: positive, equal or negative change: .. py:function:: elo_delta_classify(playersL, k) such that **given** - *playersL* a :class:`list` of players with their scores as described above - *k*, :class:`int` the k factor. **returns** 3 new :class:`list` of players summarized info: #. The list of the players whose elo increased. The list must be ordered decreasingly. #. The list of the players whose elo change is less than 10 points. The list must be ordered increasingly. #. The list of the players whose elo decreased. The list must be ordered increasingly. All are :class:`list` of :class:`tuple` where each tuple contains the following players's information: #. an :class:`int` with the **new** elo rating. #. a :class:`str` with the player's name. #. an :class:`int` with the **former** elo rating. The input list should **not be modified**. For example: .. literalinclude:: elo_delta_classify.test :language: pycon :start-after: --ini :end-before: --fi .. note:: - Notice that in this example the second list is empty since all players either increased or decrease their rating. - In your implementation of this functions it is recommended to call the previous function. Doctests are available in the :download:`elo_delta_classify.test` file. Main Function #2 ---------------- This is function intended to add scores to a player in the players list: .. py:function:: elo_player_extend(playersL, name, scoreL, k) **given** - *playersL*, a players list as described above. - *name*, a :class:`str` with the name of a player possibly in the *playersL* - *scoreL*, a scores list as described above. - *k*, :class:`int` the k factor. **modifies** *playersL* by adding the scores in *scoreL* associated to the player called *name*. **returns** and :class:`int` the new elo rating for the player called *name* calculated from the extended scores list. If the name is not found in the players list then the values returned will be -1. For example: .. literalinclude:: elo_player_extend.test :language: pycon :start-after: --ini :end-before: --fi Doctests are available in the :download:`elo_player_extend.test` file.