chesstrainer-package.RdThe main purpose of the chesstrainer package is to create sequences of moves (lines), save them, and then test yourself on these sequences. This is especially useful for training openings, but can also be used for creating chess puzzles or training tactics.
To start the trainer, run play() from the console. When starting the trainer for the first time, a directory is created for storing settings and a directory where sequences will be stored. A few example sequences also come with the package and you will receive a prompt whether to copy these sequences to the sequence directory. To familiarize yourself with the trainer, it would be good to do so.
You will then receive a prompt to enter a player name. Choose a name and hit enter.
The trainer then starts in add mode (see the ‘Note’ section at the bottom if you receive an error that the graphics device does not support event handling). For now, click on the window showing the chess board and hit <space> (i.e., the space bar), which will switch to the test mode. One of the existing sequences will then be chosen at random. The trainer may immediately prompt you to play a certain opening (via a comment at the top of the window), it may make some moves for you, or it may start at a later position during a game. Either way, you will then have to make the correct move based on the position. You do this by left-clicking and dragging the piece to be played from its current position to the desired target square. If the line width of the green rectangles (that show up when moving a piece) is too narrow or too thick, you can use the <(> and <)> keys to decrease/increase the line width. Adjust this value such that the rectangles are clearly visible, but do not overlap into adjacent squares.
The trainer will then make the next move, after which you will then again have to make the correct move. This will continue until the end of the sequence. If you do not know what the correct move is, the <h> key will provide a hint showing which piece to move. Hitting <h> for a second time will show the target square. Once the sequence has ended, left-clicking starts a new sequence.
In test mode, information is shown at the bottom about the current mode, the name of the current sequence, the player name, the current move number and the total number of moves of the sequence, the number of times that the sequence has been played so far, the age of the sequence (how many days ago the sequence was last played), the estimated difficulty of the sequence (see below), and the sequence score (see below).
With <F1>, you can receive an overview of all keyboard shortcuts. These will be explained in further detail below. You can quit the trainer with the <q> key.
The trainer keeps track of a score for each sequence. For a new sequence, the score starts out at 100. The score is multiplied by 0.8 after completing a sequence without any mistakes. When making a wrong move when playing a sequence, the score is increased by 40 points (up to a maximum of 100). You can use the <t> key to take back the score adjustment (but you should only do this when making the wrong move accidentally). Receiving a hint with the <h> key increases the score by 20 points (40 points when asking for both the starting and the target square, so this is equivalent to making a mistake).
The trainer uses the score to choose the next sequence. Sequences with higher scores have a higher chance to be presented. The probability of playing a particular sequence is computed with \(p_i = s_i^e / \sum s_i^e\), where \(s_i\) is the score of the \(i\)th sequence and \(e\) is the ‘exponent value’. This is set to 2 by default and enhances the probability that sequences with higher scores are more likely to be played. The exponent value can be adjusted with the <^> (or <6>) key. Setting the exponent value to 0 makes all sequences equally likely to be played. Setting it to a large value (e.g., 10) makes it very likely that the sequence with the highest score is played next. The score for the current sequence can also be set manually with the <o> key. Setting the score to 0 means that the sequence has a zero probability of being presented.
After completing a sequence, the current score for the sequence is saved (together with the number of times that the sequence has been played and when it was last played) to the sequence file. This way, your progress in learning the sequence is saved permanently across sessions. Using the <g> key, a progress graph (showing the sequence scores over consecutive plays) for the current sequence can be shown (if the sequence has been played before). This is useful to check whether progress is being made in learning the sequence. You can zoom into the graph by left-clicking twice (once for the start and once for the end of the interval). This can be repeated to zoom in further. Clicking the right mouse button zooms all the way out. Clicking outside of the graph, right-clicking anywhere when zoomed out, or the <escape> key closes the graph.
Using the <G> key, you can toggle whether the progress graph will be automatically shown at the end of each completed sequence.
With <F11>, you can obtain a plot of the average score of all sequences (in the current sequence directory; see below) as a function of each completed sequence during the current session. The horizontal dotted line corresponds to the average score at the beginning of the session. This is useful to check whether progress is being made in learning all of the sequences.
Using the <l> key, you can obtain a list of all sequences (note: this is shown in the console), together with their current score, the number of times they have been played (the play frequency), their age (in days; NA if a sequence has not been played before), the estimated difficulty of the sequence, and the current play probability (with 0 to 5 asterisks next to it based on the probability).
In test mode, you can use Ctrl-<d> to delete the current sequence. Note that this is permanent and all progress information about the sequence will be lost. You will receive a prompt to confirm the deletion.
Using the </> key (or <,> which is useful for a German keyboard layout), you can select a subset of the sequences in various ways by entering:
a search term (which is applied as a regular expression to the filenames of the sequences),
a sequence number (e.g., 2 to select the 2nd sequence),
a sequence number range (e.g., 2-5 to select sequences 2 to 5),
something like score > 80 to select sequences with a score above a certain threshold,
something like played < 1 to select sequences that have been played less than a certain number of times,
something like age > 2 to select sequences that have been played more than a certain number of days ago,
something like difficulty > 20 to select sequences with a difficulty above a certain threshold,
a FEN to select all sequences that contain a position matching the FEN,
c: followed by a (case insensitive) text string to select all sequences where a comment contains the text string.
The keywords score, played, age, and difficulty can be abbreviated to s, p, a, and d (so s > 80, p < 1, a > 2, and d > 20 would also work). Other comparators such as >=, <, and >= can also be used (e.g., s <= 10).
Hitting <enter> at the prompt (i.e., not entering any search string) keeps the current selection. Entering * at the prompt selects all sequences. The <*> (or <8>) key also selects all sequences without using </> first. If you only want to search for sequences (without selecting them), you can use the <|> key.
In test mode, sequences are played by default at random based on the score as described above. However, you can toggle into a different selection mode with the <m> key. Selection can be based on:
the score where sequences with higher scores have a higher play probability (the default),
the score where the sequence with the highest score is played next,
the play frequency where sequences with lower play frequencies have a higher play probability,
the play frequency where the sequence with the lowest play frequency is played next,
the age where sequences that were last played longer ago have a higher play probability,
the age where the sequence that was last played the longest ago is played next,
the difficulty where more difficult sequences have a higher play probability,
the difficulty where the sequence with the highest difficulty is played next.
The exponent value affects selection modes 1, 3, 5, and 7. Setting the exponent value to a large value makes mode 1 essentially the same as mode 2 (and similarly, mode 3 like mode 4, mode 5 like mode 6, and mode 7 like mode 8). For modes 2, 4, 6, and 8, if the highest score, lowest play frequency, highest age, or highest difficulty is the same for multiple sequences, the alphabetically first one is played next. For modes 5 and 6, sequences that have never been played before are given the highest priority. For all modes, sequences whose score was set to 0 are never played.
In test mode, the <r> key repeats the last played sequence. At the end of a sequence, you can also use the middle mouse button to repeat the sequence (before a new sequence is started). With the <R> key, you can toggle whether a sequence will be automatically repeated if a mistake was made while playing the sequence.
With the <x> key, you can switch into a timed mode. In this mode, all moves played during a sequence must be completed in a certain amount of time, which is given by the total number of moves that must be played in the sequence times the current setting for ‘time per move’ (which is 5 seconds by default). For example, if 8 moves must be played, then you have \(8 \times 5 = 40\) seconds in total to complete all moves (the time taken by the trainer for playing moves is not counted). Not completing the moves within this amount of time is treated like a mistake (i.e., the score is increased by 40 points).
When playing a sequence in this mode, the bar to the right of the board indicates whether the current playing time is above (in green) or below (in red) the amount of time you should have spent on the moves so far (i.e., if every move took exactly the amount of time allowed by the ‘time per move’ setting).
The ‘time per move’ value can be adjusted via the <F6> key.
After playing a sequence multiple times, the difficulty of the sequence can be estimated based on past performance. By default, this is computed as the average score increase (ASI) over the plays of the sequence. Using the <d> key, one can bring up a menu to choose from a variety of different methods for estimating the difficulty, including:
the average score increase over the plays of the sequence (ASI),
the percentage of plays where the score did not improve (PNI),
the number of plays where the score did not improve (NNI),
the percentage of plays with a change in the score trend (PCT),
the average of the scores of the sequence (AVG),
the standard deviation of the scores of the sequence (SD),
the root mean square successive difference (RMSSD),
the decay parameter from an exponential regression model (ERM).
These different calculations methods reflect the difficulty of a sequence in various ways. Sequences with high values for the ASI, PNI, NNI, PCT, SD, and RMSSD tend to show larger fluctuations in their scores over time and are apparently difficult to remember. Sequences with high AVG values are also difficult. Sequences with high ERM values are deviating strongly from the optimal decrease in the score that should happen when never making mistakes while playing a sequence (i.e., \(100\), \(100 \times 0.8 = 80\), \(80 \times 0.8 = 64\), and so on). By default, only the 15 most recent scores are used in the calculation of these statistics. Also, by default the difficulty is only computed when a sequence has been played at least 5 times. These values can also be adjusted via the menu that comes up when hitting the <d> key.
As described above, the trainer comes with a few example sequences to teach you how it can be used, but serious use of the trainer requires that you add your own sequences. With <space>, you can switch into the add mode, where you can enter new sequences. The first thing to decide is whether the player should play with white or black. With the <f> key, the board can be flipped accordingly (the player always plays with the pieces shown at the bottom). Next, you need to decide whether some moves will be automatically played at the beginning of a sequence. If some moves should be played automatically, then simply make these moves on the board. Once you arrive at the position where a player should start making moves, hit the <z> key (note that ‘Show’ at the bottom left then turns from ‘Yes’ to ‘No’). Now continue playing the line as it should be played. The sequence must end with a move by the player. If you make a mistake when playing a move, use the <t> or left arrow key to take the move back. Once the sequence is complete, use the <s> key to save the sequence. You will be prompted for a filename. Once the sequence has been saved, it will automatically become part of the sequences that may be presented in test mode.
A sequence may also start immediately in the starting position. Here, you will hit the <z> key right at the beginning. Since it is then essentially impossible for a player to know what they should play (since there are many sensible moves one could make), you will have to instruct the player what they should do. Using the <c> key, you can add a comment to the current move which will be shown to the player (before they have to make the move). For example, you could tell the player to play the Spanish (Ruy Lopez) opening. You should then make the appropriate moves on the board.
Comments can be added to any move using the <c> key. This may be useful if one could venture into multiple sensible lines in a given position. You would then have to instruct the player to make a particular move (either by telling the player directly which move to make or giving some appropriate hint, such as the name of a particular line/variation). Comments are also useful for mentioning variation names or other useful information.
If a sequence should commence not at the starting position of a chess game, but later on, you can move the pieces into the desired position and then use the <0> key to make the current position the starting position for a particular sequence. Alternatively, you can use the <b> key to start a board editor (see below for details).
The <e> key can be used to edit the comments for a particular sequence. This way, you can also add a ‘start comment’ and/or an ‘end comment’ to a particular sequence (the former will be shown in an overlay box before the sequence starts, the latter at the top after the last move). The <E> key opens up the data editor on the data frame that contains the moves for the current sequence. This can also be used to add, edit, and remove comments in the comment column or make adjustments to the other columns (but this should only be done if their meaning is clear).
With the <?> key, you can search for sequences that start with the same moves that have been entered/played so far (this also works in test mode). If any matching sequences are found, a prompt will ask if they should be selected. This is useful for checking what sequences are already available based on some initial moves (and then practicing these sequences) or finding other sequences similar to the one currently being played. Alternatively, with the <'> key, you can search for sequences that include the same position (irrespective of the particular moves that led to the position).
With the <.> key, you can select the last saved sequence (if one was saved before in the current session). This is useful for checking the sequence in test mode and/or creating multiple branching lines from the ending position of this sequence. Similarly, in test mode, the <a> key will create a copy of the current sequence, which can then be extended with additional moves (and saved as a new sequence). The <A> key does the same thing, but only plays the moves to the currently shown position. At the end of a sequence, the right mouse button also switches to add mode.
In add or test mode, you can bookmark a sequence with the <<> key. In add mode, the last saved sequence is bookmarked. In test mode, the currently played sequence is bookmarked. With the <>> key, you can select and manage bookmarks (use <F1> while managing the bookmarks to obtain help). This is useful for creating multiple branching lines from the ending position of certain sequences or to remember sequences that you want to come back to at a later point.
Sequences are saved to and selected from the current sequence directory. You can add, remove, and select sequence directories with the <F8> key. Removing a sequence directory simply removes it from being shown in the list of sequence directories (i.e., it does not delete the directory or any sequences therein). Bookmarks are specific to each sequence directory. Also, selecting a sequence directory switches to the sequence selection mode that was active when it was last selected.
Note that sequences are quite personalized, since they involve going into a particular line that one deems most appropriate (and hence wants to remember). Others may disagree and prefer a different line. Therefore, you should create sequences that you want to train yourself on, so you will be able to play them quickly from memory in actual games.
When in add mode, the <b> key opens up a board editor. Here, you can quickly set up a more advanced position (e.g., for a chess puzzle). With left-click and drag, pieces can be moved around. With right-click and drag, you can copy a piece that is already on the board. A right-click without a drag (or moving a piece to the left or right of the board) deletes a piece. The <f> key flips the board. The <n> key resets the board into the starting position. The <c> key clears the board. The <s> key can be used to select which side plays the first move. The <r> key can be used to enter castling availability in FEN notation (K = white can castle kingside, Q = white can castle queenside, k = black can castle kingside, q = black can castle queenside, - = neither side can castle). With the <o> key, you can enter a FEN to set up the corresponding position. With <F1>, you can receive a help overlay. You can quit the board editor with <q> or <escape>.
The trainer can be used by multiple players (i.e., sequence scores and other progress information is player specific). A player can be selected with the <p> key. You can either enter a player number, the name of an existing player, or enter a new player name. Note that player names must be syntactically valid (i.e., should start with a letter and not contain any spaces).
The current player can be deleted with Ctrl-<r>. Since this deletes all progress information for this player from the sequence files, you will receive a prompt to confirm this.
With <F2>, a leaderboard (based on the lowest average score) and player statistics are shown (i.e., the average score, the standard deviation of the scores, the minimum and maximum score, and the total number of sequences played). The statistics are based on the currently selected sequences (or all sequences in the current sequence directory if no selection has been applied). Also, sequences whose score was manually set to 0 are not included in these statistics.
For each player, the trainer also keeps track of each session including the play time. With <F12>, you can obtain a plot of your session history, showing the play time (in minutes) over days (multiple sessions on the same day are collapsed into a single session; sessions shorter than one minute are not counted). The total play time across all sessions is also shown. With the <down>/<up> cursor keys (or the middle mouse button), you can toggle to a view of the number of sequences played over days. You can zoom into a particular time frame by left-clicking twice (once for the start and once for the end of the interval). This can be repeated to zoom in further. Clicking the right mouse button zooms all the way out. With the <right>/<left> cursor keys, you can toggle to a view of the history over weeks and months (these views are only available if the session history spans multiple weeks/months). Again, one can zoom into particular time frames in these views by clicking the left mouse button twice. Clicking outside of the graph, right-clicking anywhere when zoomed out, or <escape> closes the graph.
The trainer plays various sounds (when playing moves, when capturing pieces, when making a wrong move, or when completing a sequence). This may or may not work depending on your operating system and configuration. See the playsound function for further details.
The sound volume can be decreased/increased with the <[> and <]> keys. Setting the volume to 0 disables the sound. This can also be useful if playing sounds adds too much lag.
If Stockfish (https://stockfishchess.org) is installed, it can be used in the background to automatically obtain position evaluations when adding sequences. For this, specify the path (including the executable) to Stockfish via the sfpath argument of the play function. If this is set correctly, then position evaluations will be automatically computed and added to a sequence in add mode. Evaluations are given in centipawns divided by 100, except for forced mates, which are given as \(\pm99.9\). When playing a sequence, these evaluations are then shown as an evaluation bar on the left of the board.
By default, evaluations are based on a search depth of 16 half-moves. Obtaining such an evaluation for a given position should be relatively quick and not add much lag when creating a sequence. In add mode, the <h> key shows the best move according to Stockfish in a given position. The <H> key will run a deeper analysis (by default based on search depth of 24) and show the best move according to Stockfish. Since this may take some time, a progress bar is shown at the top while the analysis is running. With <F7>, you can adjust the Stockfish settings, including the calculation depths (for fast and deep evaluations and for the play mode; see below), the number of principal evaluations that will be evaluated (for fast and deep evaluations), the number of threads that Stockfish can use during its calculations (the default is 1), the hash size in MB (the default is 256), and the maximum depth of the line(s) shown at the top of the board when asking for the best move in add mode (10 half-moves by default).
In test mode, the <u> key updates the evaluations for all moves in a sequence by recalculating the evaluations with the current setting for a deeper analysis. Note that this can take a bit of time, depending on the number of moves in the sequence. After updating the evaluations, they are automatically saved to the sequence file.
Note that asking Stockfish to evaluate impossible positions (e.g., black is in check but it is white's turn to move) crashes Stockfish. This should be handled gracefully by the trainer.
If Stockfish is running, you can switch into play mode at any time with the <\> or <#> key. This is especially useful at the end of a sequence, to continue playing further moves against the computer from the end position of a sequence (e.g., to practice holding an advantage gained during an opening sequence). In this mode, the computer chooses by default its move according to a search depth of 6 half-moves, but this can be adjusted via <F7>. Here, one can also set a limit on the play strength of Stockfish (either as a skill level between 0 and 20 or as an approximate Elo value).
Using the <g> key in play mode shows a graph of the position evaluations for the moves played so far (this also works in add mode). Using the <t> key, you can take back the last move (i.e., the move played by the computer and your own move).
Using the left and right arrow keys, you can go back and forward one move. This automatically takes you into the analysis mode, where you can try out variations and/or force the computer to make a different move. Using the <1> and <2> keys (or the up and down arrow keys), you can jump to the beginning and end of the game. Using the <3>, <4>, and <5> keys, you can jump to the first quarter, the middle, or the third quarter of the game. Using the <0> key, you can store the current game (i.e., sequence of moves) as the main variation. Using the <9> key, you can jump back to the end of the main variation.
The <\> or <#> key when in play mode toggles between the analysis and the play mode. On the other hand, <space> takes you back to the mode that was active before the play mode was chosen.
When playing a sequence, the graphical elements shown on the playing board are created by repeatedly drawing on top of the board. Therefore, when resizing the board, all elements are redrawn, which takes a few moments. With the <escape> key, the board can be redrawn in its current state, after which it can be resized without having to wait for all previous graphical elements to be redrawn.
Clicking the right mouse button on a square adds a circle to the square. Dragging the mouse from one square to another while pressing the right mouse button draws an arrow. Those familiar with the https://lichess.org website will recognize these visualizations. Clicking with the left mouse button on a square, the <escape> key, or making a move removes these visualizations. When adding a sequence, circles and arrows that are drawn are also saved and will be shown when replaying the sequence in test mode. When such annotations are shown as part of a move that is made by the trainer, the sequence will only proceed after a click.
Various other settings can be adjusted while the trainer is running:
By default, there is a 0.5 second sleep time between moves played by the trainer. This can be decreased/increased with the <-> and <+> keys.
By default, the trainer waits for a mouse click at the end of a sequence before starting a new sequence. You can toggle this on/off with the <w> key.
With the <i> key, the language of the trainer can be toggled between English and German (author note: I wrote this trainer in part for my chess playing kids, which is the reason why a German translation is available).
With the <v> key, the evaluation bar can be toggled on/off (if no evaluations are available for a sequence, the bar is never shown). Note that if the evaluation bar is turned off, it is still shown at the end of a sequence in test mode.
The settings are stored across sessions and can be shown with <F3>. With <F4>, you can adjust the colors. With <F5>, you can adjust the size of the text at the top, the text at the bottom, and the size of the evaluation value in the evaluation bar (if it is shown).
With <F6>, you can adjust some miscellaneous settings, namely the multiplier for the score when completing a sequence without any mistakes (0.8 by default), the score penalty when making a wrong move (40 by default), the score penalty per hint (20 by default), the number of animation steps for the evaluation bar (5 by default), the time per move for the timed mode (5 seconds by default), and the idle time (120 seconds by default; time without any inputs longer than this value is not counted towards the play time for the session history).
With <F9>, the FEN of the current position is printed to the console and the position is opened on the https://lichess.org website for analysis. With Ctrl-<f>, the FEN is printed and copied to the clipboard (this makes use of the write_clip function from the clipr package). With Ctrl-<c>, the current sequence name is printed and copied to the clipboard in test mode.
With <F10>, you can obtain histograms of the scores of the (selected) sequences, how many times they have been played, how long ago they were played, their difficulty, and a scatterplot of the number of times they have been played versus their scores. In the scatterplot, the dotted line indicates the best possible performance (i.e., never making a mistake when playing the sequence over and over) and the solid line the actual performance (as estimated based on a regression model; only shown when there are 5 or more points).
If you would like to remove the config files (for the settings and colors), you can use the following two commands:
file.remove(file.path(tools::R_user_dir(package="chesstrainer", which="config"), "settings.rds"))
file.remove(file.path(tools::R_user_dir(package="chesstrainer", which="config"), "colors.rds"))This may be useful in case these files were corrupted with nonsensical settings. The files will be recreated (with default values) when restarting the trainer. If you would like to remove both of these files and the directory where these files are stored, you can use:
unlink(tools::R_user_dir(package="chesstrainer", which="config"), recursive=TRUE)If you would like to remove the default directory where sequences are stored (and all files therein), you can use:
unlink(file.path(tools::R_user_dir(package="chesstrainer", which="data"), "sequences"), recursive=TRUE)If you would like to remove the directory where the session history of all players is stored (and all files therein), you can use:
unlink(file.path(tools::R_user_dir(package="chesstrainer", which="data"), "sessions"), recursive=TRUE)It is advisable to regularly make a backup of the sequences you have created. The default directory where sequences are stored can be found with the command: file.path(tools::R_user_dir(package="chesstrainer", which="data"), "sequences").
The chess pieces used in the package were obtained from https://commons.wikimedia.org/wiki/Category:SVG_chess_pieces where they are available under the Creative Commons Attribution-Share Alike 3.0 Unported License.
The sound files used in the package were obtained from https://github.com/lichess-org/lila/tree/master where they are available under the GNU Affero General Public License.
The trainer makes extensive use of getGraphicsEvent to capture mouse movements and keyboard inputs. Only some graphics devices support this. If you receive the error message ‘The graphics device does not support event handling’, then the default graphics device that was opened does not support event handling. For example, this will be the case for the RStudioGD graphics device that is used by RStudio. You can then try running x11() before starting the trainer with play().