Learn R Programming

chess

Overview

{chess} is an opinionated wrapper for R around python-chess, an amazing library created by Niklas Fiekas. It allows users to read and write PGN files as well as create and explore game trees such as the ones seen in chess books.

Installation

Install the released version of {chess} from CRAN:

install.packages("chess")

Or install the development version from GitHub with:

# install.packages("remotes")
remotes::install_github("curso-r/chess")

This should automatically install python-chess to your {reticulate} environment, but you can also explicitly do it with a convenient function:

chess::install_chess()

Example

To read an existing game, simply use read_game(). To explore it you can use forward()/back(), as well as variations()/variation() to see all variations listed for the next move and choose one of them.

library(chess)

# Read final game from the Queen's Gambit
file <- system.file("harmon.pgn", package = "chess")
harmon_borgov <- read_game(file)

# Starting position
harmon_borgov
#>         <Start>
#> r n b q k b n r
#> p p p p p p p p
#> . . . . . . . .
#> . . . . . . . .
#> . . . . . . . .
#> . . . . . . . .
#> P P P P P P P P
#> R N B Q K B N R

# Navigate to 2. c4
harmon_borgov %>%
  forward(3)
#>         <2. c4>
#> r n b q k b n r
#> p p p . p p p p
#> . . . . . . . .
#> . . . p . . . .
#> . . P P . . . .
#> . . . . . . . .
#> P P . . P P P P
#> R N B Q K B N R

# See all variations for 2...
harmon_borgov %>%
  forward(3) %>%
  variations()
#>       <2... e5>          <2... e6>
#> r n b q k b n r    r n b q k b n r
#> p p p . . p p p    p p p . . p p p
#> . . . . . . . .    . . . . p . . .
#> . . . p p . . .    . . . p . . . .
#> . . P P . . . .    . . P P . . . .
#> . . . . . . . .    . . . . . . . .
#> P P . . P P P P    P P . . P P P P
#> R N B Q K B N R    R N B Q K B N R

# Follow the sideline
harmon_borgov %>%
  forward(3) %>%
  variation(2)
#>       <2... e6>
#> r n b q k b n r
#> p p p . . p p p
#> . . . . p . . .
#> . . . p . . . .
#> . . P P . . . .
#> . . . . . . . .
#> P P . . P P P P
#> R N B Q K B N R

Many other games are included with the package so you can get up and running as soon as you install {chess}! See vignette("games") for more information.

You can also create your own game with game() and add variations to it: the move() function adds moves as well as branches the tree of the game. Strings are converted to simple moves, while list()s behave exactly as parenthesis in PGN, creating a variation of the last move. Here you can see how to recreate a Scholar’s mate and some ways to avoid it:

# Scholar's mate and some defenses
scholars_mate <- game() %>%
  move("e4") %>%
  move("e5", list("e6"), list("d5")) %>%
  move("Bc4") %>%
  move("Nc6", list("Nf6")) %>%
  move("Qh5") %>%
  move("Nf6", list("g6", "Qf3", "Nf6")) %>%
  move("Qxf7")

# Last mainline move
scholars_mate
#>      <4. Qxf7#>
#> r . b q k b . r
#> p p p p . Q p p
#> . . n . . n . .
#> . . . . p . . .
#> . . B . P . . .
#> . . . . . . . .
#> P P P P . P P P
#> R N B . K . N R

Note that there are many ways to structure the input to move(). See vignette("chess") for more information.

{chess} also features many ways of seeing both the game as a whole and the board at a specific point in time.

# Print with unicode (doesn't look good on GitHub)
print(scholars_mate, unicode = TRUE)
#>      <4. Qxf7#>
#> ♜ . ♝ ♛ ♚ ♝ . ♜
#> ♟ ♟ ♟ ♟ . ♕ ♟ ♟
#> . . ♞ . . ♞ . .
#> . . . . ♟ . . .
#> . . ♗ . ♙ . . .
#> . . . . . . . .
#> ♙ ♙ ♙ ♙ . ♙ ♙ ♙
#> ♖ ♘ ♗ . ♔ . ♘ ♖

# Export the FEN of the board
fen(scholars_mate)
#> [1] "r1bqkb1r/pppp1Qpp/2n2n2/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR b KQkq - 0 4"

# See the PGN after some move
str(back(scholars_mate, 3))
#> 2... Nc6 3. Qh5 Nf6 ( 3... g6 4. Qf3 Nf6 ) 4. Qxf7#

# Export the PGN after some move
pgn(back(scholars_mate, 3))
#> [1] "2... Nc6 3. Qh5 Nf6 ( 3... g6 4. Qf3 Nf6 ) 4. Qxf7#"

# Plot current board
plot(scholars_mate)

Motivation

python-chess served as the inspiration (and backbone) for {chess}. While the original version (and {rchess} for that matter) broadly handles “move generation, move validation” (with powerful classes and object-oriented syntax), {chess} focuses on making it easy to create and explore PGNs as trees.

By narrowing down the scope of the API, I believe the package becomes more intuitive to people who just want to quickly create shareable game analyses or easily explore other people’s games without having to resort to point and click software.

{chess}’s first use was helping me study Bobby Fischer’s My 60 Memorable Games. After some very difficult parsing, I was able to convert the whole book to PGN and upload it to lichess, but I still felt like the interface was too clumsy…

Roadmap

  • NAGs
  • Comments
  • Headers
  • Start game from FEN
  • Better plotting
  • More status functions
  • Other OSs
  • Unit tests
  • Advanced usage
  • Styler
  • CRAN
  • Stockfish API
  • Static boards (puzzles)
  • Shiny?

Code of Conduct

Please note that the chess project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

License

{chess} is licensed under the GPL 3 (or any later version at your option). Check out LICENSE.md for the full text.

Copy Link

Version

Install

install.packages('chess')

Monthly Downloads

252

Version

1.0.1

License

GPL-3

Issues

Pull Requests

Stars

Forks

Maintainer

Last Published

December 4th, 2020

Functions in chess (1.0.1)

install_chess

Install python-chess
result

Get result of the game ("*" if it hasn't ended)
root

Get the root node of a game
line

Branch game with next move
read_game

Read a game from a PGN
move_

Make moves and create variations
print.chess.pgn.Variations

Print a list of variations
move

Make moves and create variations
variations

Get all variations for next move (the children of current node)
write_game

Save a game as an PGN
%>%

Pipe operator
halfmove_clock

Get number of half-moves since the last capture or pawn move
note

Get comment for a move
nag

Parse Numeric Annotation Glyph (NAG) of a move
move_number

Get number of move
plot.chess.pgn.GameNode

Plot rendering of the board
moves

Get all legal moves available
ply_number

Get number of ply
print.chess.pgn.GameNode

Print game node
parse_move

Parse move in context
write_svg

Save an SVG with rendering of the board
print.chess.Board

Print board
pgn

Get PGN for node of a game
variation

Follow variation of a move, playing its first move
turn

Get whose turn it is
play

Move a piece on the board
board_color

Get information about the current board given a color
board_move

Get information about the current board given a move
forward

Advance in the game tree, playing next move from current branch
back

Go back in the game tree, reverting the last move from current branch
fen

Get FEN representation of board
board_is

Get information about the current board
glyph_to_nag

Convert glyph to NAG
board_to_string

Convert a board to either unicode or ASCII string
game

Create a new game