README

"pyChallenge" is a database software that uses different rating systems like ELO to compute the skill of players in games like chess. The following rating systems are (or will be) supported:

* ELO           (done)
* Glicko        (in progress)
* Glicko2       (planned)
* TrueSkill     (planned)

pyChallenge is a student's project at the DHBW Mannheim, Corporate State University.

Requirements

sudo apt-get install python-pip sudo pip install Sphinx==dev PyQt4

Basic Usage

pyChallenge is a command-line tool that offers various sub-commands to invoke the available features (similar to git or svn). Many commands depend on the game and rating system used. For each of these commands, it is possible to specify the game using '-g/--game GAME' (the default value is 'chess') and the algorithm using '-a/--algorithm ALGORITHM' (the default value is 'elo').

A list of all available commands and options can be obtained by calling:

./pychallenge.py -h

A short help message for each listed command is shown after issuing:

./pychallenge.py COMMAND -h

Configuration

The first step is to import a config file in the following csv format: "Key"="Value"

A default config is provided in the docs/ folder. It can be loaded by issuing:

./pychallenge.py import-config docs/constants.csv

Importing and Adding Player and Match Data

It is possible to import csv files with match data. It has to be in the following format:

"Month #","White Player #","Black Player #","Score"

Where 'Month' is an integer, 'White Player' and 'Black Player' are the nicknames of the two players and 'Score' is a value in (0, 0.5, 1).

For each entry, a new player is created (if it does not exists) and the match is inserted into the match table. Note that no rating updates are performed by this. This command does not depend on any algorithm. The match data is shared between all of them.

./pychallenge.py import-results CSVFILE

It is also possible to manually add a result by calling

./pychallenge.py add-result PLAYER1 PLAYER2 OUTCOME DATE

Both nicknames PLAYER1 and PLAYER2 have to be available. If this is not the case, it is necessary to create the players beforehand using

./pychallenge.py create-player NICKNAME FIRSTNAME LASTNAME

Each player is assigned the default rating values specified in the config imported before.

Query the History

The command 'history' can be used to list the history of one or two players. It shows all matches the player(s) and the number of matches won and lost.

./pychallenge.py history PLAYER1 [PLAYER2]

Updating the Ratings

After having imported the match data it is possible to update the ratings for each player according to the outcomes of the matches. To do this, call:

./pychallenge.py update

Best and Worst Players

The commands 'best' and 'worst' can be used to query the N best (or worst) players in a given game according to a specified rating system.

./pychallenge.py (best|worst) N

Comparison and Predictions

After having updated the ratings, it is possible to predict the outcomes of matches. This can be done using a csv file of future matches in the following format:

"Month #","White Player #","Black Player #","Score"

The outcome for each match is saved in a similar csv file specified by OFILE. if '-i/--incremental' is specified, the rating values for the players are updated after each predicted match. This is only temporary and has no impact on the actual rating values stored in the database.

./pychallenge.py predict IFILE OFILE [-i/--incremental]

To compare two players (and to predict the match outcome), issue:

./pychallenge.py compare PLAYER1 PLAYER2

To find the best opponent for a given player, call:

./pychallenger.py match PLAYER

To simple query the rating of a player, use the following command:

./pychallenge.py rating PLAYER

Clear Matches and Ranks

To clear the database, call the 'clear' command with the switches '-r/--ranks' and '-m/--matches' to clear the rank and/or match data.

./pychallenge.py clear [-r/--ranks] [-m/--matches]