{chess} is anopinionated wrapper for R aroundpython-chess, anamazing library created byNiklasFiekas. It allows users to read and writePGNfiles as well as create and explore game trees such as the ones seen inchess books.
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 itwith a convenient function:
chess::install_chess()To read an existing game, simply useread_game(). Toexplore it you can useforward()/back(), aswell asvariations()/variation() to see allvariations listed for the next move and choose one of them.
library(chess)# Read final game from the Queen's Gambitfile<-system.file("harmon.pgn",package ="chess")harmon_borgov<-read_game(file)# Starting positionharmon_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. c4harmon_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 sidelineharmon_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 RMany other games are included with the package so you can get up andrunning as soon as you install{chess}! Seevignette("games") for more information.
You can also create your own game withgame() and addvariations to it: themove() function adds moves as well asbranches the tree of the game. Strings are converted to simple moves,whilelist()s behave exactly as parenthesis in PGN,creating a variation of the last move. Here you can see how to recreateaScholar’smate and some ways to avoid 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 tomove(). Seevignette("chess") for moreinformation.
{chess} also features many ways of seeing both the gameas 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 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)
python-chess served as the inspiration (and backbone) for{chess}. While the original version (and{rchess} forthat matter) broadly handles “move generation, move validation” (withpowerful 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 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’sMy 60 Memorable Games. After some very difficultparsing,I was able to convert the whole book to PGN andupload it to lichess, butI still felt like the interface was too clumsy…
Please note that the chess project is released with aContributorCode of Conduct. By contributing to this project, you agree to abideby its terms.
{chess} is licensed under the GPL 3 (or any laterversion at your option). Check outLICENSE.mdfor the full text.