get_engine_match: Determine the fraction of a player's moves that match an...

In dryguy/rbitr: Arbiter: One who ensures adherence to the rules and laws of chess

Determine the fraction of a player's moves that match an engine's moves

Description

The get_engine_match() function calculates the fraction of moves played that correspond to the 'best' move as determined by a chess engine.

Usage

get_engine_match(gamelog, movetext, depth = NULL)

Arguments

gamelog	A list of engine output from rbitr's evaluate_game() function.
movetext	A single-element character vector containing a sequence of moves in standard algebraic notation (SAN).
depth	(Optional, default = NULL) A single-element integer vector indicating which search depth to return. The value must not be less than 1 or greater than the maximum depth reported by the engine. A value of NULL returns data for the maximum available depth.

Details

The get_engine_match() function requires a gamelog in the same format as the one returned by evaluate_game(). It also requires the moves of the game to be supplied in the same format provided by get_pgn().

If desired, the analysis depth used to determine the best move may be specified using the depth parameter. If depth is set to a value higher than what is available for some moves, evaluate_game() will return an error. If no value for depth is provided, the deepest analysis at each ply will be used.

The ratio is determined by counting the number of moves that are the same as the engine's preferred moves, and then dividing by the total number of moves in the game: bestmove_ratio = # of moves matching the engine / total # of moves

Value

A list containing the ratio of engine-matching moves to the total number of moves for both white ($white_ratio) and black ($black_ratio).

Note

By itself, observing a player to have a high percentage of moves that are the same as engine moves is not necessarily evidence of illicit computer assistance. Having a high percentage can be a consequence of a game having many forcing lines. It is also the case that if many games are analyzed, it becomes likely that some of them will have high matching percentages by chance alone. Prof. Ken Regan calls this the parable of the golfers.

See Also

• get_pgn() for loading the movetext from a pgn file.

• evaluate_game() for creating a gamelog.

Examples

movetext <- '1. e4 g5 2. Nc3 f5 3. Qh5# 1-0'
# Modify engine_path as required for your engine location & operating system
engine_path <- '//stockfish.exe'
gamelog <- evaluate_game(movetext, engine_path, n_pv = 1, limiter = 'depth',
                         limit = 1)
get_engine_match(gamelog, movetext)

dryguy/rbitr documentation built on Oct. 15, 2024, 6:18 a.m.