====== Requirements Doc for IAGO Record and Ranking Service ======

One of the services IAGO will seek to provide is a central location to record games played (providing this information for statistical analysis and perhaps providing our own) and a central authority for game ratings/rankings.  This would allow for pan-clubhouse ladders and tournaments.  This document attempts to outline requirements for such a service.


===== Required Infrastructure =====

  * An established membership system
  * A database of games for which the system will accept reports






===== Game Recording =====

  * Game records shall contain at least the following items:
    - Roster of required tags
    - List of moves submitted
  * Game records may also provide:
    - Customized tags specific to a site, event, or game
    - Editorial marks and comments
    - General chat transcripts
    - Additional information regarding scores and other special conditions as required by the rules
      * This should not be necessary for the most part and should not be used to attempt to fully describe game states unless the text move provided is simply insufficient.  One should probably use the <comment> element where possible.
  * Records shall only be accepted from trusted submitters.
    * If we wished to allow other submission, the system would have to be able to flag trusted ones for ratings, and put the others in some other category.
  * Records shall conform to the [[record-schema|provided XML Schema]].  XML provides the following benefits:
    - It has built-in methods for validation and transformation.
    - It also makes automated parsing simpler since XML processing tools are widely available and supported.
    - Having records in a standard XML format means that PGN or any other style report could be generated at will.
    - It allows a more general approach to move representation that is (hopefully) game-agnostic.
  * Records shall be kept indefinitely and remain freely available to the public.



==== Methodology ====

  * Participating sites register acceptable domains with IAGO.
  * When new game records are available, the site sends a "ping" to the records server via http, containing the URL of the service's RSS feed.
  * Assuming the domain of the URL matches one registered with IAGO, the records server fetches the RSS feed.
  * The RSS feed must contain a list of game IDs (alphanumeric) and an associated URL that returns the appropriate game record.
    * The ID numbers **must be unique** across the given site!!
  * For every ID number IAGO does not have a record for, it goes to the associated URL, fetches the record, and processes it.
  * A system should probably be implemented that would allow site administrators to request the removal of an erroneous record.
  * An auditing system shall be implemented that allows auditors to review as-yet unexamined entries for any errors or other issues.





===== Ranking/Rating =====

Everybody's ratings would be regenerated for a particular game whenever a new game record is added.  The total regeneration allows for auditors to modify any record in the system and have the ratings reflect that.  Such a generation could be done on a daily basis if processing time became an issue.  The system would simply take each record for a specific game in "Game End" order and calculate ratings.  This would also allow us to completely change or add new rating systems accurately.

I propose the following ranking system as the default.  (See old revisions of this document for a different approach.)

The rating system should allow for more than 2 players.  While Microsoft's TrueSkill is pretty interesting, I am personally not in a place to figure out how to implement it.  I think ELO can be extended to allow for more than 2 participants.  A game with 4 players, for example, would be processed as a 6 separate duels (A over B, C, and D; B over C and D; C over D).  The resulting ratings are then averaged and posted.  Here are some 4-player examples:

<code>
Start:
---
- 1200
- 1200
- 1200
- 1200


Final:
---
- 1216
- 1205.33333333333
- 1194.66666666667
- 1184


Deltas:
---
- 16
- 5.33333333333326
- -5.33333333333326
- -16
</code>

<code>
Start:
---
- 1200
- 1400
- 1400
- 1150


Final:
---
- 1220.77899451613
- 1399.27397760856
- 1388.60731094189
- 1141.33971693341


Deltas:
---
- 20.7789945161337
- -0.726022391439074
- -11.3926890581058
- -8.66028306658882
</code>