Chessratings

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:

$ pip install -e .[dev]