Tournament results API

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).

General

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.

The classes described here are implemented in the gomill.tournament_results and gomill.gtp_games modules, but you should not normally import these directly. See Using the API in scripts.

Tournament_results objects

class gomill.tournament_results.Tournament_results

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:

get_matchup_ids()

Return type:list of strings

Return the tournament’s matchup ids.

get_matchup(matchup_id)

Return type:Matchup_description

Describe the matchup with the specified id.

get_matchups()

Return type:map matchup id → Matchup_description

Describe all matchups.

get_matchup_stats(matchup_id)

Return type:Matchup_stats object

Return statistics for the matchup with the specified id.

get_matchup_results(matchup_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.

Matchup_description objects

class gomill.tournament_results.Matchup_description

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):

id

The matchup id (a string, usually 1 to 3 characters).

player_1

player_2

The player codes of the two players. These are never equal.

name

String describing the matchup (eg 'xxx v yyy').

board_size

Integer (eg 19).

komi

Float (eg 7.0).

alternating

Bool. If this is False, player_1 played black and player_2 played white; otherwise they alternated.

handicap

Integer or None.

handicap_style

String: 'fixed' or 'free'.

move_limit

Integer or None. See Playing games.

scorer

String: 'internal' or 'players'. See Scoring.

number_of_games

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:

describe_details()

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).

Matchup_stats objects

class gomill.tournament_results.Matchup_stats

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_1

player_2

The player codes of the two players. These are never equal.

total

Integer. The number of games played in the matchup.

wins_1

wins_2

Integer. The number of games won by each player.

forfeits_1

forfeits_2

Integer. The number of games in which each player lost by forfeit.

unknown

Integer. The number of games whose result is unknown.

average_time_1

average_time_2

float or None. The average CPU time taken by each 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.

played_1b

played_2b

Integer. The number of games in which each player took Black.

played_1w

played_2w

Integer. The number of games in which each player took White.

alternating

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:

wins_b

Integer. The number of games in which Black won.

wins_w

Integer. The number of games in which White won.

wins_1b

wins_2b

Integer. The number of games in which each player won with Black.

wins_1w

wins_2w

Integer. The number of games in which each player won with White.

If alternating is False, the following attributes are also available:

colour_1

colour_2

The colour taken by each player.

Game_result objects

class gomill.gtp_games.Game_result

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.

Game_results can be retrieved from Tournament_results objects.

Game_results have the following attributes (which should be treated as read-only):

game_id

Short string uniquely identifying the game within the tournament. See Game identification.

players

Map colour → player code.

player_b

player code of the Black player.

player_w

player code of the White player.

winning_player

player code or None.

losing_player

player code or None.

winning_colour

colour or None.

losing_colour

colour or None.

is_jigo

Bool: True if the game was a jigo.

is_unknown

Bool: True if the game’s result is unknown.

is_forfeit

Bool: True if one of the players lost the game by forfeit; see Playing games.

sgf_result

String describing the game’s result. This is in the format used for the SGF RE property (eg 'B+1.5').

detail

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.

cpu_times

Map player code → time.

The time value is a float representing a number of seconds, or None if time information is not available.

See CPU time for more details.

Game_results support the following method:

describe()

Return type:string

Return a short human-readable description of the result.

For example, 'xxx beat yyy (W+2.5)'.

Using the API in scripts

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.get_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.