get_imb: Identify chess inaccuracies, mistakes, and blunders

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

Identify chess inaccuracies, mistakes, and blunders

Description

The function get_imb() identifies inaccuracies, mistakes, and blunders in a chess game, based on how much the evaluation changes after a move.

Usage

get_imb(
  scores,
  moves,
  bestmoves,
  color,
  cap = 1000,
  cap_action = "replace",
  first_ply = 1,
  to_move = "white",
  mate = 50000
)

Arguments

scores	A numeric vector of chess engine evaluations. Positions that are mate in x should be indicated by the same numeric value as the mate parameter (with negative values when black is to give mate).
moves	A character vector of moves in the same format as bestmoves.
bestmoves	A character vector of moves in the same format as moves.
color	A single-element character vector indicating which side to analyze. Allowed values are 'black' or 'white'.
cap	(Default = 1000) A single-element numeric vector of the maximum allowed value for centipawn score. Should always be less than the setting for mate.
cap_action	(Default = 'replace') A single-element character vector indicating whether to exclude scores outside the range [-cap, cap], to replace them with the cap, or to not use a cap. Allowed values are 'exclude', 'replace', or 'none'.
first_ply	(Default = 1) A single-element integer vector indicating the first ply to be included in the calculation. May not be larger than the number of elements in score.
to_move	(Default = 'white') A single-element character vector indicating which side's turn it is.
mate	(Default = 50000) A single-element numeric vector indicating what centipawn value was used to represent mate in the scores parameter. Should always be greater than the setting for cap. It should also be greater than the largest non-mating evaluation in the game to avoid unexpected behavior.

Details

The user must provide a vector of evaluations for the game via the scores parameter. The sign convention is that positive values indicate white is ahead, while negative values indicate black is ahead. Evaluation produced using a UCI chess engine use a different convention, where the score is from the player's point of view. Use the function convert_scores to change the sign convention before passing the evaluations to get_imb().

The scores parameter should include an evaluation for the initial position, before white has moved. In addition, a vector of the game's moves (moves), and a vector of the engine's preferred moves (bestmoves) must also be provided. The move data is used to avoid marking a move as an inaccuracy, mistake, or blunder when it is the best move available. The color parameter is used to indicate which side to evaluate.

The thresholds for marking moves are based on evaluations after applying an exponential scaling function (2 / (1 + exp(-0.004 * scores)) - 1), borrowed from lichess.org. This function downplays the impact of less-than-perfect play when one side is far ahead. The idea being that the player who is ahead may avoid moves that lead to material gain if those moves lead to complicated tactics. In such positions players often go for simple and solid moves that maintain a clear advantage. These types of moves aren't really blunders. Similarly, a player in a lost position may make moves designed to complicate the position and create chances for a comeback, even if the move objectively loses material with perfect play by the opponent.

The value of cap serves a similar purpose to move scaling. That is the player with a decisive advantage can have valid reasons not to play the best move. The cap can be disabled by setting the parameter cap_action to 'none'.

Some engines may give poor evaluations to valid opening moves. To skip the classification of opening moves, set the first_ply parameter to indicate the desired starting ply. For example, to start from move 8, set first_ply to 15. (The ply count starts with the initial position, so the beginning of the second move occurs at ply 3, and each subsequent move begins on an odd ply.) If starting from a position where black is to move, the parameter to_move must be set to 'black'.

Value

A named list of move numbers for the $inaccuracies, $mistakes, and $blunders.

Note

Since the calculations are based on the ones used by lichess.org, get_imb() should produce numbers very close to those given by lichess. To replicate the lichess calculation, use the default settings for cap (1000), cap_action ('replace'), first_ply (1), to_move ('white'), and mate (> 1000). In addition, the first element of scores should be an evaluation of the initial position, and be equal to 15. The results may not be identical to lichess (even if the same engine is used) since most chess engines are non-deterministic for a variety of reasons, but they should be fairly close.

See Also

• get_acpl() for calculating average centipawn loss.

• get_evals() to load scores from a PGN file.

• get_moves() to get moves from movetext.

• evaluate_game() or evaluate_pgn() to calculate scores.

• convert_scores() to set values for 'mate x'.

• parse_gamelog() to extract the best moves from UCI engine output.

Examples

scores <- c(12, -171, -72, -50000, -50000)
moves <- c("g2g4", "e7e6", "f2f4", "d8h4")
bestmoves <- c("d2d4", "d7d5", "g1f3", "d8h4")
get_imb(scores, moves, bestmoves, color = 'white')

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