## Chessratings
A python implementation of official chess rating systems, as used by organizations such as the US Chess Federation (USCF) to rate player strength.
Currently available modules are:
- US Chess Federation (ELO): http://www.glicko.net/ratings/rating.system.pdf
## Installation
Available in PyPi.
```
pip install chessratings
```
## Usage
To use the chessratings package, import your module of choice into your python script:
```
from chessratings import uscf_elo
```
There are a few important concepts to know when using this package: Players and Tournaments.
A Player is a rated entity that can participate in a game/match against other Players. Players are initiated with, at minimum, the following information:
- **id**: an identifier such as a name
- **rating**: their most recent rating, if known
Additional optional arguments may vary by module and can be found in the source code.
```
example_player_1 = uscf_elo.Player(id='player_1', rating=1600)
example_player_2 = uscf_elo.Player(id='player_2', rating=1500)
```
A Tournament is a match or series of matches between two or more players. As per the official specifications, player ratings are updated after a Tournament is concluded.
A Tournament requires two arguments:
- **players**: a list of participating Player entities
- **tournament_results**: a summary of tournament results
The tournament_results must be provided in the following format:
```
[
[ ( player_1_id, player_2_id ), winner_id ],
[ ( ... ) ],
]
```
If the match was a draw, winner_id can be set to null (or any value other than one of the two player IDs). Here's an example:
```
players = [example_player_1, example_player_2]
tournament_results = [
[ ( 'player_1', 'player_2' ), 'player_2'],
[ ( 'player_1' ,'player_2' ), 'player_1'],
[ ( 'player_1', 'player_2' ), np.nan ]
]
tournament = uscf_elo.Tournament(players, tournament_results)
```
Running the tournaments will update player ratings, and optionally output summarized information about the tournament results.
```
tournament_results = tournament.run()
print(tournament_results)
```
Tournament results are presented as:
player id, tournament date, tournament number, number of tournament games, number of wins, number of draws, number of losses, updated rating
```
[
['player_1', datetime.date(2021, 5, 20), 1, 3, 1, 1, 1, 1584.0954259202883],
['player_2', datetime.date(2021, 5, 20), 1, 3, 1, 1, 1, 1517.178456181353]
]
```
## Contributing
If you would like to help develop this package, along with the tools you need to develop and run tests, run the following in your virtualenv:
```bash
$ pip install -e .[dev]
```
