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]