{chess} is an opinionated wrapper for R aroundpython-chess, an amazinglibrary created by Niklas Fiekas. Itallows users to read and writePGN files aswell as create and explore game trees such as the ones seen in chessbooks.
The package is still maturing! So I very much encourage you to send yoursuggestions and bugs as issues in thepackage repository.
Installation
You can install the most recent version of {chess} fromCRAN with:
install.packages("chess")This should automatically install python-chess to your {reticulate}environment, but you can also explicitly do it with a convenientfunction:
chess::install_chess()Example
To read an existing game, simply use read_game(). To explore it youcan use forward()/back(), as well as variations()/variation() tosee all variations listed for the next move and choose one of them.
library(chess)# Read first game from My 60 Memorable Gamesfile <- system.file("m60mg.pgn", package = "chess")fischer_sherwin <- read_game(file, n_max = 1)# Starting positionfischer_sherwin#> <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 4. g3fischer_sherwin %>% forward(7)#> <4. g3>#> r . b q k b n r#> p p . p . p p p#> . . n . p . . .#> . . p . . . . .#> . . . . P . . .#> . . . P . N P .#> P P P . . P . P#> R N B Q K B . R# See all variations for 4...fischer_sherwin %>% forward(7) %>% variations()#> <4... Nf6> <4... d5>#> r . b q k b . r r . b q k b n r#> p p . p . p p p p p . . . p p p#> . . n . p n . . . . n . p . . .#> . . p . . . . . . . p p . . . .#> . . . . P . . . . . . . P . . .#> . . . P . N P . . . . P . N P .#> P P P . . P . P P P P . . P . P#> R N B Q K B . R R N B Q K B . R# Follow the sidelinefischer_sherwin %>% forward(7) %>% variation(2)#> <4... d5>#> r . b q k b n r#> p p . . . p p p#> . . n . p . . .#> . . p p . . . .#> . . . . P . . .#> . . . P . N P .#> P P P . . P . P#> R N B Q K B . RYou can also create your own game with game() and add variations toit: the move() function adds moves as well as branches the tree of thegame. Strings are converted to simple moves, while list()s behaveexactly as parenthesis in PGN, creating a variation of the last move.Here you can see how to recreate a Scholar’smate and some ways toavoid it:
# Scholar's mate and some defensesscholars_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 movescholars_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 RNote that there are many ways to structure the input to move(). Seevignette("chess") for more information.
{chess} also features many ways of seeing both the game as a whole andthe board at a specific point in time.
# Print with unicode (doesn't look good on the web)print(scholars_mate, unicode = TRUE)#> <4. Qxf7#>#> ♜ . ♝ ♛ ♚ ♝ . ♜#> ♟ ♟ ♟ ♟ . ♕ ♟ ♟#> . . ♞ . . ♞ . .#> . . . . ♟ . . .#> . . ♗ . ♙ . . .#> . . . . . . . .#> ♙ ♙ ♙ ♙ . ♙ ♙ ♙#> ♖ ♘ ♗ . ♔ . ♘ ♖# Export the FEN of the boardfen(scholars_mate)#> [1] "r1bqkb1r/pppp1Qpp/2n2n2/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR b KQkq - 0 4"# See the PGN after some movestr(back(scholars_mate, 3))#> 2... Nc6 3. Qh5 Nf6 ( 3... g6 4. Qf3 Nf6 ) 4. Qxf7## Export the PGN after some movepgn(back(scholars_mate, 3))#> [1] "2... Nc6 3. Qh5 Nf6 ( 3... g6 4. Qf3 Nf6 ) 4. Qxf7#"# Plot current boardplot(scholars_mate)
Motivation
python-chess served as the inspiration (and backbone) for {chess}.While the original version (and{rchess} for that matter) broadlyhandles “move generation, move validation” (with powerful classes andobject-oriented syntax), {chess} focuses on making it easy to createand explore PGNs as trees.
By narrowing down the scope of the API, I believe the package becomesmore intuitive to people who just want to quickly create shareable gameanalyses or easily explore other people’s games without having to resortto point and click software.
{chess}’s first use was helping me study Bobby Fischer’s My 60Memorable Games. After some very difficult parsing,I was able to convert the whole book to PGN and upload it tolichess, but I still felt like theinterface was too clumsy…
