This is a Python interface for processing the game results stored in a tournament’s state file. It can be used to write custom reports, or to find games with particular results.
Note that it can be used only for tournaments (not for tuning events).
Page contents
In this interface, players are identified using their player codes (that is, their keys in the control file’s players dictionary).
Note
In a playoff tournament, it is possible to define a matchup in which the same player takes both colours. In this case, the player code used for the second player will be the player code from the control file with '#2' appended.
In the descriptions below, colour represents a single-character string, either 'b' or 'w'.
The classes described here are implemented in the tournament_results and gtp_games modules, but you should not normally import these directly. See Using the API in scripts.
A Tournament_results object provides access to the game results and statistics for a single tournament.
The tournament results are catalogued in terms of matchups, with each matchup corresponding to a series of games which had the same players and settings. Each matchup has an id, which is a short string.
Tournament_results objects are normally retrieved from Competition or Ringmaster objects; see Using the API in scripts.
Tournament_results objects support the following methods:
| Return type: | list of strings |
|---|
Return the tournament’s matchup ids.
| Return type: | Matchup_description |
|---|
Describe the matchup with the specified id.
| Return type: | map matchup id → Matchup_description |
|---|
Describe all matchups.
| Return type: | Matchup_stats object |
|---|
Return statistics for the matchup with the specified id.
| Return type: | list of Game_result objects |
|---|
Return the individual game results for the matchup with the specified id.
The list is in unspecified order (in particular, the colours don’t necessarily alternate, even if alternating is True for the matchup).
Void games do not appear in these results.
A Matchup_description describes a series of games which had the same players and settings. The information comes from the current contents of the tournament’s control file.
Matchup_descriptions are normally retrieved from Tournament_results objects.
Matchup_descriptions have the following attributes (which should be treated as read-only):
The matchup id (a string, usually 1 to 3 characters).
The player code of the first player.
The player code of the second player.
player_1 and player_2 are always different.
String describing the matchup (eg 'xxx v yyy').
Integer (eg 19).
Float (eg 7.0).
Bool. If this is False, player_1 played black and player_2 played white; otherwise they alternated.
Integer or None.
String: 'fixed' or 'free'.
Integer or None. See Playing games.
String: 'internal' or 'players'. See Scoring.
Integer or None. This is the number of games requested in the control file; it may not match the number of game results that are available.
Matchup_descriptions support the following method:
| Return type: | string |
|---|
Return a text description of the matchup’s game settings.
This covers the most important game settings which can’t be observed in the results table (board size, handicap, and komi).
A Matchup_stats object provides basic summary information for a matchup. The information comes from the tournament’s state file.
Matchup_stats objects are normally retrieved from Tournament_results objects.
Matchup_stats objects have the following attributes (which should be treated as read-only):
player code of the first player.
player code of the second player.
Integer. The number of games played in the matchup.
Integer. The number of games won by the first player.
Integer. The number of games won by the second player.
Integer. The number of games in which the first player lost by forfeit.
Integer. The number of games in which the second player lost by forfeit.
Integer. The number of games whose result is unknown.
float or None. The average CPU time taken by the first player.
float or None. The average CPU time taken by the second player.
If CPU times are available for only some games, the average is taken over the games for which they are available. If they aren’t available for any games, the average is given as None. See CPU time for notes on how CPU times are obtained.
Integer. The number of games in which the first player took Black.
Integer. The number of games in which the first player took White.
Integer. The number of games in which the second player took Black.
Integer. The number of games in which the second player took White.
Bool. This is true if each player played at least one game as Black and at least one game as White.
This doesn’t always equal the alternating attribute from the corresponding Matchup_description object (in particular, if only one game was played in the matchup, it will always be False).
If alternating is True, the following attributes are also available:
Integer. The number of games in which Black won.
Integer. The number of games in which White won.
Integer. The number of games in which the first player won with Black.
Integer. The number of games in which the first player won with White.
Integer. The number of games in which the second player won with Black.
Integer. The number of games in which the second player won with White.
If alternating is False, the following attributes are also available:
The colour taken by the first player.
The colour taken by the second player.
A Game_result contains the information recorded for an individual game. The information comes from the tournament’s state file.
Note
If an SGF game record has been written for the game, you can retrieve its location in the filesystem from a Ringmaster object using ringmaster.get_sgf_pathname(game_id).
The player codes used here are the same as the ones in the corresponding Matchup_description‘s player_1 and player_2 attributes.
See Playing games and Details of scoring for an explanation of the possible game results. Games with unknown result can be distinguished as having winning_player None but is_jigo False.
Game_results can be retrieved from Tournament_results objects.
Game_results have the following attributes (which should be treated as read-only):
Short string uniquely identifying the game within the tournament. See Game identification.
Map colour → player code.
player code of the Black player.
player code of the White player.
player code or None.
player code or None.
colour or None.
colour or None.
Bool: True if the game was a jigo.
Bool: True if one of the players lost the game by forfeit; see Playing games.
String describing the game’s result. This is in the format used for the SGF RE property (eg 'B+1.5').
Additional information about the game result (string or None).
This is present (not None) for those game results which are not wins on points, jigos, or wins by resignation.
Game_results support the following method:
| Return type: | string |
|---|
Return a short human-readable description of the result.
For example, 'xxx beat yyy (W+2.5)'.
To write a standalone script using the tournaments results API, obtain a Tournament_results object from a Ringmaster object as follows:
from gomill import ringmasters
ringmaster = ringmasters.Ringmaster(control_file_pathname)
ringmaster.load_status()
tournament_results = ringmaster.tournament_results()
All of these calls report problems by raising the RingmasterError exception defined in the ringmasters module.
See the find_forfeits.py example script for a more fleshed-out example.