diff options
| -rw-r--r-- | README.md | 108 |
1 files changed, 108 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..5d1a510 --- /dev/null +++ b/README.md @@ -0,0 +1,108 @@ +Overview +======== + +This application allows to apply Elo-like rankings to Formula One races. + +Requirements +============ + + * python 2.x (developed and tested on 2.7.8) + * SQLAlchemy + * PySQLite (optional) + * MySQL connector for python (optional) + * dateutil + +Import scripts use some additional libraries, such as: + + * BeautifulSoup4 + * lxml + * urllib, urllib2, urlparse + +You can use the application with either SQLite database or MySQL database (in that case you, well, need a MySQL database). + +Installation +============ + +1. Fetch this repository +2. Configure your database (see: Configuration:Database) +3. Fill the database with result data +4. All done! + +Usage +===== +``` +usage: elo.py [-h] [--date DATE] [--limit LIMIT] [-v] [--force] [COMMAND] + +positional arguments: + COMMAND Action to execute against the database: + print - prints the rankings for all drivers ranked in 12 months, + reset - resets the rankings, + rate - calculates the rankings + init - init clean database for the application + Default value is 'print'. + +optional arguments: + -h, --help show this help message and exit + --date DATE Date for which the action should be executed. + Print ratings for DATE, + reset ratings all the way down to DATE + or rank the races all the way up to DATE. + --limit LIMIT Ranking list (display) cut-off point. + -v Display verbose info on rating progress to STDERR. + --force, -f Force database initialization (for "init" command). +``` + +Configuration +============= + +Application configuration consists of two JSON-formatted files: elo.json and db.json. + +Database +-------- + +`db.json` holds database configuration. Two example files (for both MySQL and SQLite) are provided. If you want a quick-start solution, just rename the `db.json.SQLITE-EXAMPLE` to `db.json`. + +The first time you run the application against a fresh database, you have to initialize the structure, by running: + + ./elo.py init + +At any time, you can do a hard reset on the existing database, by running init with `--force` parameter. This truncates all the data, including race results data from the database, and recreates the structure. + +Results data are provided in elo.db pre-filled SQLite database or in sql/results.sql, in plain SQL format. + +Elo parameters +-------------- + +`elo.json` contains algorithm parameter for Elo ratings: + + * initial driver ranking + * algorithm disparity options + * algorithm importance for distinct race types (championship/non-championship, qualifying/race) + * algorithm importance thresholds + +Remember that any change to parameters should lead to ranking reset (`./elo.py reset; ./elo.py rate`) if you want consistent rating criteria throughout the entires time span of results database. + +More information +================ + +More elaborate write-up of the methodology and general approach to the problem can be found in the doc/ directory of source code repository, which contains: + + * races.md: explanation of race selection for the results database + * results.md: summary of the scoring method + * sources.md: summary of sources used for result data + * challenges.md: two most dificult aspects of the project, described in detail + * sql.md: useful or interesting queries to be run against the database (may only be applicable to the MySQL database) + +Author +====== + +If you want to contact me about the application, you can drop me a private message on Reddit: /u/emkael (although I know it's not exactly rocket science to work out other means of communication, from the GitHub account alone). I'll do my best to help. + +License +======= + +lol, idk. + +Do: use it, share it, mix it, modify it, analyse it - just leave some attribution. + +Don't: sell it? |