"readme-PGN" for "40H-PGN-2023B" Tools & Utilities. "40H-PGN" is a collection of 58 "PGN" command-line utility tools by Norman Pollock (USA) for use in "Windows" or in a "Java Runtime Environment". "40H-PGN" tools and instructions are copyright (c) 2007-2023 by Norman Pollock. All rights reserved. "40H-PGN" can be freely distributed and used for non-commercial purposes as long as "40H-PGN" is kept intact and no changes are made to any files. Any commercial distribution or use of "40H-PGN", or any of its files, is strictly forbidden. Disclaimer: The "40H-PGN" package is distributed "as is". No warranty or guarantee of any kind is expressed or implied. The user assumes all risks of usage. The author is not responsible for any damage or losses of any kind caused by the use or misuse of the tools or this "readme-PGN" file. Current download sites for "40H Tools": 40hchess.epizy.com nk-qy.info/40h (Thanks to Frank Quisinsky) Please bookmark. Contact: Norman Pollock rc1242@yahoo.com ==================================================================== FAQ: 1. What is the purpose of "40H" tools? "40H" tools enable users to do specific chess tasks. 2. What does the term "40H" have to do with chess? 40H is a hexadecimal and computer science number that is equal to the number of squares in a chessboard. 40H = 64 decimal. 3. Are the "40H" downloads checked for viruses/malware? "40H" downloads are checked at www.virustotal.com 4. On which platforms will the "40H" tools work? "40H" tools come in 2 formats: "Windows" executables and "Java" class files for all major platforms including "Linux" and "Mac". Another option for non-"Windows" platforms is to use "Wine". See the "Java / Wine" section below for more details. 5. Do the "40H" tools require Internet access? Only to download the tools. 6. Are the "40H" tools portable? Yes. You can even save them on a flash drive and use them on different PCs. They are single files and no "dlls" are required. They do not require a "setup" tool and they do not affect the registry. They can be removed by simple deletion. 7. Are the "40H" tools 64-bit and do they use multiprocessing? They are each 32-bit tools and they do NOT use multiprocessing. 8. Is the "readme" file included in the download? Yes, and it is also on the website. The version on the website has the latest updates and corrections. 9. Where are the full usage instructions for each "40H-PGN" tool? They are in the last section of this "readme". Please be sure to read the relevant instructions before use. ==================================================================== OVERVIEW OF TOOLS (FULL INSTRUCTIONS AT THE END OF THIS FILE) Each "40H-PGN" tool consists of a single file. Each tool executes from a command-line in a "Command Prompt" window. The "40H-PGN" tools do not change any input file. Output appears in a new file(s). There are 58 tools in "40H-PGN". 1. "cleanUp" removes games that have certain irregularities mainly in the "Tag Section". The removed games are saved in a separate file and can be repaired using a text editor. 2. "clusterList" lists the different player clusters of the input "pgn" file. It also lists the number of games and the number of distinct opponents for each player. 3. "colorList" lists each player's results by color played - games as White, and games as Black. 4. "combine" joins 2, 3, 4, or 5 "pgn" files by concatenation (adding files consecutively). 5. "eco500" creates 500 files from a "pgn" file. The files are named "ecoA00" through "ecoE99". Each game is extracted into the output file whose name corresponds to the first three characters of its ECO code. Games without an "ECO" tag are extracted to "ecoN.pgn". 6. "ecoExtract" extracts games whose ECO code matches a user-specified ECO code, or is within a user-specified ECO range. Only the first three characters of the ECO codes are used for comparisons. 7. "ecoList" lists each ECO code used, the number of games, the White score percentage, and the number of White wins, draws, and losses. 8. "ecoPlayer" produces a list based on a user-specified player. For each color and for each ECO code used, it lists the number of games, the score percentage, and the number of wins, draws, and losses. 9. "ecoSplit" separates the input file into six files based on the first character of the ECO code. There is an output file for "A", "B", "C", "D", "E" and "no ECO". 10. "eloCheck" removes games that are missing either the "WhiteElo" or "BlackElo" tag or both. The resulting output file can be used for Elo computations without concern for distortions caused by missing Elo tags. 11. "eloExtend" inserts missing Elo tags for players who already have at least one Elo tag. "eloExtend" inserts the average of the existing Elo tags. Existing Elo tags are not overwritten. 12. "eloGap" extracts games in which the players' Elo gap (absolute value of Elo difference) is less than or equal to a user-specified maximum gap. 13. "eloInsert" inserts Elo tags with user-specified Elo ratings for user-specified players. Existing Elo tags are overwritten. 14. "eloList" lists player names, number of games, average Elo, minimum Elo, maximum Elo, Performance Elo, and opponents' average Elo. 15. "eloRemove" removes all "WhiteElo" and "BlackElo" tags. 16. "emBayes" uses Elo ratings from "BayesElo" by Remi Coulom to insert new Elo tags. The user has the option to keep existing Elo tags. 17. "emOrdo" uses rounded Elo ratings from "Ordo 1.0" by Miguel Ballicora to insert new Elo tags. The user has the option to keep existing Elo tags. 18. "emStat" uses Elo ratings from "EloStat 1.3" by Frank Schubert to insert new Elo tags. The user has the option to keep existing Elo tags. 19. "fenRemove" removes games containing a "FEN" tag except when the "FEN" position is the standard opening position. 20. "gameNum" inserts consecutive "game number" comments into the games. Each comment is placed at the beginning of the "MoveText Section". 21. "gameSplit" separates the input "pgn" file into a user-specified number (2-10000) of files. All games are kept intact within one of the output files. The number of games in each output file is "equal", plus or minus 1 game. 22. "groupExtract" extracts games in which each player's name begins with a name_search-string located in a user-created text file named "group". 23. "listExtract" extracts games in which at least one of the player names begin with a name_search-string in a user-created text file named "list". 24. "mateExtract" extracts games ending in a checkmate. "mateExtract" must be used AFTER using "pgn-extract" with the "fixresulttags" parameter. 25. "merge" joins 2, 3, 4, or 5 "pgn" files by inserting one game from each successive input file, and then repeating until all games have been inserted. 26. "minDate" extracts games that occurred within a user-specified time span. 27. "minElo" extracts games where the players' Elo values are in an user-specified range or ranges. 28. "minOccur" extracts games of players who meet or exceed a user-specified minimum number of games. 29. "minPly" extracts games in which the number of plies (half-moves) is within a user-specified range. "minPly" uses the value in the "PlyCount" tag to obtain the number of plies in a game. 30. "nameChange" performs user-specified player name changes based on a user-created text file named "changes". 31. "nameColor" adds a token, "(wh)" or "(bl)", to each player's name depending on the color being played. For example, "Karpov, A. (wh)" and "Karpov, A. (bl)". 32. "nameExtract" extracts games in which at least one player's name begins with a user-specified name_search-string. 33. "nameList" lists player names and games played in 3 different output files. It also has the option to output names in "all caps". 34. "nameSimilar" lists player names that start with the same token or the same three characters. The number of games for each player is listed. 35. "numExtract" extracts games whose game number matches a game number in a user-specified text file "numbers". 36. "pairExtract" extracts games in which each player's name begins with a different name_search-string from the same pair in a user- created a text file named "pairs". 37. "pairList" lists player pairings, the number of games, and the results of each pairing. 38. "pairSimilar" lists player pairs where the player names start with the same token AND where the players have played each other. The number of games for each pair is listed. 39. "pairSplit" extracts the games of each player pair into its own file. Only the first 1000 player pairs (in sorted order) are processed at each "pairSplit" execution. The remaining games are collected into an "exclude" file which can be processed at a later time. 40. "pgn2stream" converts a "pgn" file into a "move steam" file. A "move stream" is a full chess game condensed to a single line. It consists of the moves and the result, and optionally, the move numbers. 41. "playerExtract" extracts the games of a user-specified player. It also outputs the player's games by color and result. 42. "plyCount" counts the number of plies (half-moves) of each game and inserts a new "PlyCount" tag if one is missing. Existing "PlyCount" tags are unchanged. Also produces a listing of plycounts and the number of games. 43. "resultList" lists player names, number of games, number of wins, draws, losses, score percentages, points, and S-B tie-break points. There are three output files. 44. "resultSplit" separates the input file into four files based on the results of the games. There is an output file for "White Wins", "Draws", "Black Wins", and "no result". 45. "stream2pgn" converts a "move stream" file into a "pgn" file. A "move stream" is a full chess game condensed to a single line. It consists of the moves and the result, and optionally, the move numbers. 46. "summary" produces statistics involving games, players, dates, results, white/black, Elo ratings, plycounts, and ECOs. Optionally, "summary" can produce statistics for the number of player clusters and the number of player pairings. 47. "tagCreate" inserts a user-specified tag type (other than "Event") into the Tag Section of each game. The "Event" tag must already be present. All previous tags of the inserted tag type are removed. 48. "tagExtract" extracts games based on a user-specified tag type and a user-specified search string. The search string can either be a single token or a complete tag value. 49. "tagFix" repairs a limited number of tag irregularities. 50. "tagInsert" replaces all tag values of a user-specified tag type with user-specified values in a text file. The tag type must be present in every game of the "pgn" file. 51. "tagList" lists each tag type that occurs in the "pgn" file and the number of its occurrences. 52. "tagNull" replaces all values of a user-specified tag type with the appropriate null value EXCEPT for the "FEN" tag type. 53. "tagOrder" rearranges the tag types into a generally accepted order. The first 13 tag types are ordered as follows: "Event", "Site", "Date", "Round", "White", "Black", "Result", "WhiteElo", "BlackElo", "ECO", "SetUp" and "FEN". Then come various other tags in their original order, followed by the "PlyCount" tag. 54. "tagRemove" removes all instances of a user-specified tag type EXCEPT for "Event" and "FEN" tag types. 55. "tagValue" lists the data values of a user-specified tag type and the number of occurrences of each data value. 56. "trim" produces an output "pgn" file that puts each "full move" on the same line while also removing comments if present. "trim" lets you set the maximum output width in the "MoveText Section" from 40 to 100 characters. The default is 76 characters. 57. "truncate" counts the number of plies (half-moves) and then removes any plies occurring after a user-specified number. If a game has fewer plies than the user-specified number, that game is output without change. Results are not removed. 58. "upset" extracts games between two players having an Elo difference equal to or greater than the "min_Elo_difference", which by default, is 250. Output is in three files for wins, draws, and losses. --------- Note the "40H-EPD" tools have 6 batch script "PGN" tools that are different from any of the "40H-PGN" tools. Here is a summary of the batch script tools in "40H-EPD": pgn3fold.cmd: extracts "pgn" games containing a 3-fold repetition of a position. Uses "pgn-Extract", "epd3fold" and "numExtract". pgnFin.cmd: lists the final position of each "pgn" game in "epd" format. Uses "pgn-Extract" and "epdFin". pgnMask.cmd: extracts "pgn" games containing a user-specified position structure in "epd" format. Uses "pgn-Extract", "epdMask" and "numExtract". pgnMaterial.cmd: extracts "pgn" games containing a position with piece/ quantity values from the user-specified file "pieces". Uses "pgn-Extract", "epdMaterial" and "numExtract". pgnPly.cmd: lists the position in each "pgn" game that occurred after a user-specified ply. Outputs in "epd" format. Uses "pgn-Extract" and "epdPly". pgnPosition.cmd: extracts "pgn" games containing a position within a user-specified file of "epd" positions. Uses "pgn-Extract", "epdPosition" and "numExtract". ==================================================================== INTRODUCTION: Download the "40H-PGN" file. It is packed in 7-zip format. You can unpack it using "7-zip", available at: http://www.7-zip.org Unpacking the "40H-PGN" download file results in 58 "Windows" executable files. This "readme-PGN" file is oriented to users of the "Windows" executable files. Users of the "Java" class files have to make adjustments for use in a Java Environment. Each "40H-PGN" tool is a "command-line tool", which means that it executes on a command-line in a "Command Prompt" window. The "40H-PGN" tools were written in "Java" and then compiled using "gcj 3.4". All coding is original. Each "40H-PGN" tool consists of a single self-contained file. No external "dlls" are required. Each "40H-PGN" tool is portable and just has to be copied to be installed. It does not need a setup program and it does not write any data to the registry. Unless otherwise indicated, each "40H-PGN" tool inputs a "pgn" file. "40H-PGN" tools DO NOT MAKE ANY CHANGES to input files. Output appears in a new file(s). Output files are pre-named. Users should rename the output file(s) before they are overwritten by the next execution of the tool. "40-PGN" tools assume the games in the "pgn" input files are written in Standard Algebraic Notation ("SAN") and adhere to the "Standard PGN Specification Guide". The "Standard PGN Specification Guide" ("PGN Standards") is currently at: http://www.saremba.de/chessgml/standards/pgn/pgn-complete.htm The 58 "40H-PGN" tools are: cleanUp, clusterList, colorList, combine, eco500, ecoExtract, ecoList, ecoPlayer, ecoSplit, eloCheck, eloExtend, eloGap, eloInsert, eloList, eloRemove, emBayes, emOrdo, emStat, fenRemove, gameNum, gameSplit, groupExtract, listExtract, mateExtract, merge, minDate, minElo, minOccur, minPly, nameChange, nameColor, nameExtract, nameList, nameSimilar, nearDupe, numExtract, pairExtract, pairList, pairSimilar, pairSplit, playerExtract, plyCount, resultList, resultSplit, stream2pgn, summary, tagCreate, tagExtract, tagFix, tagInsert, tagList, tagNull, tagOrder, tagRemove, tagValue, trim, truncate and upset. Thanks to Jim Ablett for helping me get started on this project and for showing me how to create "Windows" executables for the tools. ====================================================================== LIMITATIONS: "40H-PGN" tools ONLY execute from a command-line within a Command Prompt. See http://dosprompt.info/ for Command Prompt support. "40H-PGN" tools are subject to the capacities of the maximum array sizes that are specified in their coding. These maximum array sizes are adequate for most "pgn" input files. However if you use a very large "pgn" input file, there is a possibility that an overflow error will occur or that execution will take an extended amount of time. "40H-PGN" tools are limited by the available system memory. If you can close unrelated tools that are open, then more system memory will be available. In either of the above two situations occur, the user could try any of the following workarounds: (1) Use "trim" to remove comments if present; (2) Use "gameSplit" to separate the input "pgn" file into smaller files; (3) Use "listExtract" (or "groupExtract") to extract the games of the important players. If the input "pgn" data file does not conform to "PGN Standards", "40H-PGN" tools may not perform properly. "40H-PGN" tools treat each unique player name string as a distinct player. Therefore two players using the same name string are treated as the same player. Likewise, if one player has two different name strings, he is treated as being two different players. "40H-PGN" tools might give incorrect statistical results if the input "pgn" file contains any games where the two players' names are identical. Use the "40H-PGN" tool "cleanUp" to remove such games. "40H-PGN" tools might not perform properly if the Elo tags are in certain non-standard arrangements. For example, having the "WhiteElo" tag precedes the "White" tag, or having the "Result" tag precede the "WhiteElo" tag, can cause incorrect output. Using "tagOrder" will correct this problem. "40H-PGN" tools that make calculations based on Elo ratings may not perform properly if one or both Elo ratings are missing from any game. Using "eloCheck" will remove games that are missing an Elo tag. "40H-PGN" tools cannot detect illegal moves, inconsistent results, and incorrect results. Use "Joined" by Andreas Stable to detect many types of irregularities that sometimes can be fixed using a text editor. Also, use "PGN-Extract" by David Barnes to detect and fix many types of irregularities. In extreme cases, "PGN-Extract" will delete a game having a serious irregularity. "PGN-Extract" also changes Long Algebraic Notation to Standard Algebraic Notation ("SAN"). "40H-PGN" tools cannot detect duplicate games (games with the same moves). Use "PGN-Extract" by David Barnes to detect and remove duplicate games. "40H-PGN" tools cannot detect "twin" games (games with almost the same moves). Use a combination of "pgnPly" and "epdOccur", from "40H-EPD", to detect possible "twin" games. "40H-PGN" tools cannot "ECO" classify games or sort games. Use "SCID vs. PC" by Steven Atkinson (based on "SCID" by Shane Hudson & Pascal Georges), for these purposes. "40H-PGN" tools cannot detect "blunders" within a game. Use "Game Analyser" by Thomas McBurney for this purpose. The following "40H-PGN" tools depend upon the output of external tools: "emBayes" ("BayesElo version 0056"), "emOrdo" ("Ordo 1.0"), and "emStat" ("EloStat 1.3"). Other versions of the external tools may not work properly. "40H-PGN" has no control over the external tools. Newer versions of external tools mentioned in this document may or may not work properly with "40H" tools. In addition, the availability to download those tools may change. For example, a web site may change to a new address, or even discontinue. Any such event could affect "40H" tools. It is therefore suggested that you continue to keep a copy of any (old) version of an external tool that works properly with "40H" tools. ==================================================================== INSTALLATION, FILES, AND FOLDERS: Create a folder named "40H" if it does not already exist. Extract the download into the "40H" folder. The extraction will unpack the 58 tools into a "40H-PGN" subfolder named "40H-PGN-2023B". For users who only will be using the "40H-PGN" tools occasionally, the simplest arrangement is to copy the desired tool to the folder where the input file(s) are located, and then run in that folder. Likewise, you could copy the input file(s) to the folder where the "40H-PGN" tools are located and then run in that folder. For users who will be using "40H-PGN" tools often, copy/move the "40H-PGN" tools to a folder that is already on the System Path. (Type "path" in a command window to see the System Path.) This way you can run any of the "40H-PGN" tools from any folder without having to specify the path. If you do not have such a folder on your System Path, you would first have to create the folder and then edit the Path Variable. Use "search" in "Settings" to find "System Environment Variables". Then click on "Environment Variables", then "Path" in "System Variables", and then "edit". This may vary depending on Windows version. The user should set the Working Folder to the folder that contains the input "pgn" file and any other data file. This will avoid having to specify pathnames and will result in the input and output file(s) being located in the same folder. A pathname can be used to reference a "40H-PGN" tool and an input "pgn" file, if either is not in the Working Folder. Other data files must be in the Working Folder. Input files are not changed. For extra safety, the user should save all input "pgn" files on another storage medium. Output appears in a new file(s). Running a "40H-PGN" tool without mentioning all required files and parameters will list the version number of the tool, the syntax, an example of usage, and the names of the output files. Output files are TEMPORARY files. They are created in the Working Folder. Be sure to rename/copy/move any output files that you want to keep. The next execution of the tool in that folder will overwrite the previous output file(s). Do not change an original output file to "read-only" as that will prevent the creating tool from executing in that folder. Many "40H-PGN" output filenames are in the form "out*.pgn". Many of the "out*.pgn" files are accompanied by an "exclude" file in the form "exclude*.pgn". The "out*.pgn" contains the games that were extracted. The "exclude*.pgn" file contains those games that were NOT extracted. Sometimes the "exclude*.pgn" file is more important to the user. A "40H-PGN" tool cannot use its output "pgn" file as an input file unless the filename is changed. ==================================================================== EXECUTION: Each tool executes from a command-line in a "Command Prompt" window. The general format for running a tool is: tool_name [data_filename] pgn_filename [parameter(s)] Examples: 1. summary alpha.pgn 2. eloInsert elovals alpha.pgn (uses data file) 3. emStat rating.dat alpha.pgn keep (uses data file & parameter) Data files must always be in the Working Folder. "pgn" files can be in the Working Folder or can be accessed by a pathname. After entering the proper command-line, and making sure all files are accessible, press to start execution. Some tools, like "clusterList", "pairList" and "trim", take more time to execute compared to other "40H-PGN" tools. This can be noticeable with very large input files. Output is in a new file(s) in the Working Folder. The original input file is not changed. Be sure to follow the specific instructions for each tool. ==================================================================== HANDLING LISTS PRODUCED BY 40H-PGN TOOLS Several 40H-PGN tools produce lists. You might want to extract a range of columns from one of the lists or you might want to remove a range of columns from that list. Your goal may be to create input to another tool or it may be to have the information in a concise form. In those and other cases, the tool "txtColumn", in "40H-TXT", can be helpful. "txtColumn" can extract a range of columns from a list, and it can remove a range of columns from a list. ==================================================================== HANDLING INACCURATE OUTPUT & OTHER PROBLEMS If you are getting inaccurate output from a "40H" tool, or having some other problem, be sure you are using the latest "40H" version and the latest version of any ancillary tool. Then be sure the "pgn" input file is following "PGN Standards". The following tools can check or clean up a "pgn" file: (1) "PGN-Extract" by David Barnes for example: pgn-extract -s -N -C -V -ooutfile.pgn infile.pgn (2) "tagFix" in "40H-PGN" (3) "cleanUp" in "40H-PGN" (4) "Joined" by Andreas Stable (only indicates problems) (5) "Notepad++" by Don Ho (finds hidden characters when set to show all characters) A common problem is "overflow". Often this is due to some sort of irregularity in the "pgn" file. See above. Other times it may be due to an extremely large "pgn" file. In the latter case you could split the "pgn" file into smaller files. "40H" tools that do this include "gameSplit", "ecoSplit", "minDate", "minPly", "minElo" and "resultSplit". ==================================================================== JAVA / WINE There are two main options for running "40H" tools on a non-"Windows" platform. You can use the "Java Runtime Environment" (JRE) or you can use "Wine". User feedback indicates that "JRE" is more effective than "Wine". The JRE option requires the JRE to be installed. It may already be installed, use "java -version" in a command window to check. If it is installed but is not a recent version (less than 7), you should install the latest version. Download the "Java Runtime Environment" DIRECTLY from Oracle: www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html To use the JRE option with "40H" tools you have to download the "40H" "Java" class files from the download page. Each tool is contained within one class file so there is no need for "jar" files which are used when a "Java" application contains more than one class file. External tools might not have a "JRE" version. In this case, the "Wine" option should be tried. In the following examples, "tool_name" represents the file "tool_name.class" which can either be in the Working Folder or the "classpath". Do not include the ".class" extension in the command. Filenames in a "Java Runtime Environment" are case-sensitive. Usage: java tool_name datafile java [-cp classpath] tool_name datafile Examples: java nameList alpha.pgn java -cp .\ nameList alpha.pgn java -cp \myclassfiles nameList alpha.pgn In the above examples, "nameList" represents "nameList.class". "\" may have to be replaced by "/" in some operating systems. The "Wine" option uses the "40H" "Windows" executables and runs them on the non-"Windows" platform. If the "40H" tools uses an external tool then this option should be tried. Download at: www.winehq.org/ Java-based tools, such as the "40H" tools, do not have executable versions on platforms other than "Windows". And even then, it is very rare for a Java-based tool to have a "Windows" executable. ====================================================================== BATCH SCRIPTS ("cmd" or "bat" files) Using batch scripts can greatly increase the convenience of the "40H-PGN" suite. It can be used to string together several tools. All files mentioned within the batch script should be in the Working Folder or on the Path. Assuming the following is saved as "neat.cmd": trim %1 tagOrder outR.pgn Usage: neat alpha.pgn Output: out3.pgn ====================================================================== EN PASSANT INDICATORS "En passant" indicators, "ep", "e.p." and "/ep", are sometimes present in a "pgn" game. These indicators are optional, rarely occur, and serve no purpose. A computer engine or a good chess player can easily see if an "en passant" move had occurred without needing an indicator. Also, if external "pgn" software is not adapted to "en passant" indictors, there could be errors in the counting of plies or the input of the "pgn" file. It is recommended that the user remove these indicators, if present. The "40H-PGN" tool "trim" removes them, as well as removing comments and variations. The "40H-PGN" tools "truncate" and "plyCount" remove these indicators during processing to prevent plycount errors. The indicators are not output. Other "40H-PGN" tools accept files with these indicators and output the indicators, but do not do any processing that is affected by the indicators. ====================================================================== CHECKING RESULTS Before using a "40H-PGN" tool that relies upon game results, it is a good idea to first run "pgn-extract" (by David Barnes) with the "fixresulttags" parameter. This will check for several possible errors and correct them if necessary. For example: pgn-extract -s --fixresulttags -otemp.pgn input.pgn resultSplit temp.pgn ==================================================================== ==================================================================== FULL USAGE INSTRUCTIONS: =========================(1) cleanUp =============================== "cleanUp" removes games that have certain irregularities mainly in the "Tag Section". The removed games are saved in a separate file and can be repaired using a text editor. The output file is "out2.pgn". Removed games are in "exclude2.pgn". The possible "irregularities" are: a required tag not occurring or occurring more than once, games with no result ("*") in either the "Tag Section" or at the end of "MoveText" section, a null value for a player name, an illegal "Date" value, and self-play games. Syntax: cleanUp filename.pgn Example: cleanUp alpha.pgn Output: out2.pgn, exclude2.pgn Comments: 1. "cleanUp" does NOT remove games that do not have moves. To remove such games, and games with just a few moves, use "minPly". =========================(2) clusterList =========================== "clusterList" lists the different player clusters in the input "pgn" file. It also lists the number of games and the number of distinct opponents for each player. A "cluster" consists of all the games played by a closed network of players. A "pgn" file can have more than one cluster. In that scenario, a player whose games are in one cluster, did not play (in the "pgn" file) any games against a player whose games are in another cluster, and there is no linkage through games played to each other. A player's number of distinct opponents tells how many other players in his cluster played at least one game against him. "pairList" can identity those players. There are two output files. "outCluster" separates the players by cluster. "outCluster2" lists all the players together. If the input "pgn" file has only 1 cluster, then the two output files will be the same. "clusterList" assigns an identification number to each cluster in order to distinguish one cluster from another. Syntax: clusterList filename.pgn Example: clusterList alpha.pgn Output: outCluster, outCluster2 Comments: 1. "groupExtract" can be used to extract a cluster. =========================(3) colorList ============================= "colorList" lists each player's results by color played - games as White, and games as Black. Games without a result ("*") are ignored. "playerExtract" will extract a player's games by color. "nameColor" adds a token to each player's name to distinguish games played with White and Black. Syntax: colorList filename.pgn Example: colorList alpha.pgn Output: outColor Comments: 1. Use "cleanUp" to remove games without a result ("*"). =========================(4) combine =============================== "combine" joins 2, 3, 4, or 5 "pgn" files by concatenation (adding files consecutively). Example: combine fileA.pgn fileB.pgn fileC.pgn The output file "outCB.pgn" will consist of: all games from fileA.pgn followed by all games from fileB.pgn followed by all games from fileC.pgn Syntax: combine file1.pgn file2.pgn [file3.pgn file4.pgn file5.pgn] Examples: combine alpha.pgn beta.pgn combine alpha.pgn beta.pgn gamma.pgn combine alpha.pgn beta.pgn gamma.pgn delta.pgn combine alpha.pgn beta.pgn gamma.pgn delta.pgn epsilon.pgn Output: outCB.pgn Comment: 1. Users who prefer joining "pgn" files by inserting one game from each successive input file, and then repeating until all games have been inserted, can use the tool "merge" described below. =========================(5) eco500 ================================ "eco500" creates 500 files from a "pgn" file. The files are named "ecoA00" through "ecoE99". Each game is extracted into the output file whose name corresponds to the first three characters of its ECO code. Games without an "ECO" tag are extracted to "ecoN.pgn". "eco500" works with game ECO codes of 3, 4 or 5 characters. ECO codes of 4 or 5 characters are referred to as "extended ECO codes". Examples: A41e, E99b2. However "eco500" only uses the first 3 characters for extracting games. Files are formed even if they are empty. Syntax: eco500 filename.pgn Example: eco500 alpha.pgn Output: ecoA00.pgn,..., ecoA99.pgn, ecoB00.pgn,..., ecoE99.pgn, ecoN.pgn Comment: 1. ECO codes are case-sensitive. 2. "ecoExtract" and "ecoSplit" also extract games based on ECO codes. =========================(6) ecoExtract ============================ "ecoExtract" extracts games whose ECO code matches a user-specified ECO code, or is within a user-specified ECO range. Only the first three characters of the ECO codes are used for comparisons. The output file is "outQ.pgn". Games not extracted to "outQ.pgn" are in "excludeQ.pgn". "ecoExtract" works with game ECO codes of 3, 4, or 5 characters. ECO codes of 4 or 5 characters are referred to as "extended" ECO codes. Examples: A41e, E99b2. However "ecoExtract" only uses the first 3 characters of the ECO code for extracting games. The first character of an "ECO" code must be in the range "A" to "E". The second and third characters must be in the range "0" to "9". Example: ecoExtract alpha.pgn B21 This will extract all games whose ECO code starts with "B21". For example, this will include ECO codes "B21", "B21d", "B21c2". Example: ecoExtract alpha.pgn B21 D30 This will extract all games whose ECO code starts from "B21" to "D30" inclusive. For example, this will include ECO codes "B21", "B21h", "B99", "B99m", "C00", "D06", "D30", "D30k2". To extract just the games of a specific extended ECO code, it may be better to use "tagExtract". Example: tagExtract alpha.pgn ECO "B21d" Syntax: ecoExtract filename.pgn eco_string1 [eco_string2] Examples: ecoExtract alpha.pgn B21 ecoExtract alpha.pgn B21 C14 Output: outQ.pgn, excludeQ.pgn Comments: 1. "eco_string1" and "eco_string2" are case-sensitive. 2. "ecoList" can be used to check the ECO output of "ecoExtract". =========================(7) ecoList =============================== "ecoList" lists each ECO code used, the number of games, the White score percentage, and the number of White wins, draws, and losses. Games without a Result and/or without an ECO code are not included in the output. "ecoList" works with ECO codes having a maximum of 5 characters. The user can lower the maximum characters of the ECO codes by specifying a parameter value from 1 to 4. If an ECO code's length exceeds the maximum, the excess is truncated. For example, if the parameter value is "3", ECO code value "C14a" will be truncated to "C14". Syntax: ecoList filename.pgn [1|2|3|4] Examples: ecoList alpha.pgn ecoList alpha.pgn 3 Output: outEco Comments: 1. Use "cleanUp" to remove games without a result ("*"). =========================(8) ecoPlayer ============================= "ecoPlayer" produces a list based on a user-specified player. For each color and for each ECO code used, it lists the number of games, the score percentage, and the number of wins, draws, and losses. Matches between the user-specified player's name and names in the "pgn" file are not case-sensitive. For example, if the user-specified player name is "karpov, anatoly", it will match "KARPOV, Anatoly" in the "pgn" file. Games without a Result and/or an ECO code are not included in the output. "ecoPlayer" works with ECO codes having a maximum of 5 characters. The user can lower the maximum characters of the ECO codes by specifying a parameter value from 1 to 4. If an ECO code's length exceeds the maximum, the excess is truncated. For example, if the parameter value is "3", ECO code value "C14a" will be truncated to "C14". Syntax: ecoPlayer filename.pgn player_name [1|2|3|4] Examples: ecoPlayer alpha.pgn "Burn, Amos" ecoPlayer alpha.pgn "Burn, Amos" 3 Output: outEP Comments: 1. Name matches are not case-sensitive. 2. If the "player_name" parameter value contains an embedded space, then it must be enclosed in quotation marks. 3. Use "cleanUp" to remove games without a result ("*"). =========================(9) ecoSplit ============================== "ecoSplit" separates the input file into six files based on the first character of the ECO code. There is an output file for "A", "B", "C", "D", "E" and "no ECO". "ecoA.pgn" contains games with an ECO code starting with "A", "ecoB.pgn" contains games with an ECO code starting with "B", "ecoC.pgn" contains games with an ECO code starting with "C", "ecoD.pgn" contains games with an ECO code starting with "D", "ecoE.pgn" contains games with an ECO code starting with "E", "ecoN.pgn" contains games with no ECO code, Games remain in their original order and are not sorted. Syntax: ecoSplit filename.pgn Example: ecoSplit alpha.pgn Output: ecoA.pgn, ecoB.pgn, ecoC.pgn, ecoD.pgn, ecoE.pgn, ecoN.pgn =========================(10) eloCheck ============================= "eloCheck" removes games that are missing either the "WhiteElo" or "BlackElo" tag or both. The resulting output file can be used for Elo computations without concern for distortions caused by missing Elo tags. The removed games are placed in "excludeW.pgn". The user has the option to insert the missing Elo tags and then put the edited games into "outW.pgn". Before using "eloCheck", the user can see if any Elo tags are missing by using "summary". After using "eloCheck", the output file "outW.pgn" is suitable for use with "eloGap" and "eloList" and any other tool that does Elo computations. Syntax: eloCheck filename.pgn Example: eloCheck alpha.pgn Output: outW.pgn, excludeW.pgn =========================(11) eloExtend ============================ "eloExtend" inserts missing Elo tags for players who already have at least one Elo tag. "eloExtend" inserts the average of the existing Elo tags. Existing Elo tags are not overwritten. "outS.pgn" contains the output games. "manifest-s" lists the Elo tags that were inserted. Syntax: eloExtend filename.pgn Usage: eloExtend alpha.pgn Output: out8.pgn, manifest-8 Comments: 1. The inserted Elo values are rounded to the nearest whole number. 2. Another tool for inserting missing Elo tags is "eloInsert". =========================(12) eloGap ============================== "eloGap" extracts games in which the players' Elo gap (absolute value of Elo difference) is less than or equal to a user-specified maximum gap. For example: eloGap alpha.pgn 100 extracts all games in alpha.pgn with an Elo gap from 0 to 100. The output file is "outF.pgn". Games not extracted to "outF.pgn" are sent to "excludeF.pgn". "eloGap" does not extract games missing an Elo rating. Use "eloCheck" to remove games with a missing Elo rating. Syntax: eloGap filename.pgn elo_distance Example: eloGap alpha.pgn 100 Output: outF.pgn, excludeF.pgn Comments: 1. Use "summary" to see if any Elo ratings are missing. =========================(13) eloInsert ============================ "eloInsert" inserts Elo tags with user-specified Elo ratings for user-specified players. Existing Elo tags are overwritten. The user creates a text file named "elovals" that contains the player names and Elo values on successive lines. name1 Elo for name1 name2 Elo for name2 name3 Elo for name3 "eloInsert" name matches are not case-sensitive. For example, "Acs, Peter" in "elovals" will match "ACS, peter" in the "pgn" file. If the same player name occurs more than once, only the last Elo rating is used. "elovals" must be located in the Working Folder and cannot be referenced using a pathname. Syntax: eloInsert elovals filename.pgn Example: eloInsert elovals alpha.pgn Output: outI.pgn Comments: 1. The filename "elovals" is case-sensitive. 2. Name matches are not case-sensitive. 3. A "name" must be on an odd-numbered line in "elovals", and an Elo value must be on an even-numbered line. There must not be any blank lines at the start or in the middle of "elovals". 4. Player names do not have to be in order. 5. Quotation marks must not be used in "elovals". =========================(14) eloList ================================ "eloList" lists player names, number of games, average Elo, minimum Elo, maximum Elo, Performance Elo, and opponents' average Elo. Two output lists: "outElo" is sorted by player name, "outElo2" is sorted by player Elo rating. The columns' abbreviations in the output files: "Elo" represents the average Elo rating. "Max" represents the maximum Elo rating. "Min" represents the minimum Elo rating. "Perf" represents the performance Elo rating. "Opp" represents the opponents' average Elo rating. "eloList" is intended for use with "pgn" input files that have both Elo tags present for every game. If any Elo tags are missing then computation results may be unreliable. Using "summary" will show if any Elo tags are missing. And using "eloCheck" will remove games with a missing Elo tag. The "Performance Elo" rating is an unofficial estimate of the player's Elo rating for his performance IN THIS PGN FILE. The computation of "Performance Elo" is based on the player's results, Elo ratings and his opponents' Elo ratings, IN THIS PGN FILE. Comparing a player's "Performance Elo" rating to the player's "Average Elo" rating, will give an "opinion" as to whether or not the player performed as expected. Syntax: eloList filename.pgn Example: eloList alpha.pgn Output: outElo, outElo2 Comments: 1. Use "summary" to see if any Elo ratings are missing. 2. use "eloCheck" to remove games with missing Elo tags. =========================(15) eloRemove ============================= "eloRemove" removes all "WhiteElo" and "BlackElo" tags. "eloRemove" removes both "WhiteElo" and "BlackElo" tags. It cannot remove just one of them. Use "EloStat" with "emStat", or "BayesElo" with "emBayes", or "Ordo" with "emOrdo", to compute and insert new Elo tags. Syntax: eloRemove filename.pgn Example: eloRemove alpha.pgn Output: out5.pgn =========================(16) emBayes ============================== "emBayes" uses Elo ratings from "BayesElo" (version 0056) by Remi Coulom to insert new Elo tags. The user has the option to keep existing Elo tags. In default mode, "emBayes" overwrites existing Elo tag data values. With the optional parameter "keep", existing Elo tag data values are not changed. The user must use the filename "bayes.dat" for the output file from "BayesElo" because "emBayes" requires it. Here is a sample sequence of commands for using "BayesElo": BayesElo readpgn alpha.pgn elo mm exactdist offset 2500 ratings >bayes.dat x x Note that there is NO space between ">" and "bayes.dat". The "offset" value (2500) is the starting Elo value and also the average of each player's Elo value weighted by games played. "bayes.dat" must be located in the Working Folder and cannot be referenced using a pathname. Syntax: emBayes bayes.dat filename.pgn [keep] Examples: emBayes bayes.dat alpha.pgn emBayes bayes.dat alpha.pgn keep Output: outB.pgn Comments: 1. A player with multiple name variations should have the variations consolidated before using "BayesElo". See "nameList", "nameSimilar" and "nameChange". 2. This version of "emBayes" is for use with "BayesElo 0056". Updates or variants of "BayesElo" might not work properly with "emBayes". =========================(17) emOrdo =============================== "emOrdo" uses rounded Elo ratings from "Ordo 1.0" by Miguel Ballicora to insert new Elo tags. The user has the option to keep existing Elo tags. "Ordo 1.0" produces Elo ratings to one decimal place. "emOrdo" rounds those Elo values to the nearest integer to conform with "PGN Standards". In default mode, "emOrdo" overwrites existing Elo tag data values. With the optional parameter "keep", existing Elo tag data values are not changed. The user must use the filename "rating.txt" for the output file from "Ordo 1.0" because "emOrdo" requires it. Here is a sample command for using "Ordo 1.0": Ordo -a 2500 -o rating.txt -p alpha.pgn The "-a" value (2500) is the starting Elo value and also the average of each player's Elo value WITHOUT weighting for games played. "rating.txt" must be located in the Working Folder and cannot be referenced using a pathname. Syntax: emOrdo rating.txt filename.pgn [keep] Examples: emOrdo rating.txt alpha.pgn emOrdo rating.txt alpha.pgn keep Output: outD.pgn Comments: 1. A player with multiple name variations should have the variations consolidated before using "Ordo 1.0". See "nameList", "nameSimilar" and "nameChange". 2. This version of "emOrdo" is for use with "Ordo 1.0". Updates or variants of "Ordo" might not work properly with "emOrdo". 3. "emOrdo" can produce "emStat" type output. Ordo -a 2500 -E -G -p alpha.pgn Then use the output file "rating.dat" with "emStat": emStat rating.dat alpha.pgn =========================(18) emStat =============================== "emStat" uses Elo ratings from "EloStat 1.3" by Frank Schubert to insert new Elo tags. The user has the option to keep existing Elo tags. In default mode, "emStat" overwrites existing Elo tag data values. With the optional parameter "keep", existing Elo tag data values are not changed. "emStat" requires the data file "rating.dat" produced by "EloStat 1.3". Here is a sample sequence of commands for using "EloStat 1.3": EloStat 1 alpha 2500 0 Note that when you enter the name of the "pgn" file (alpha.pgn), you do not enter the "pgn" extension. The "Start Elo" value (2500) is the starting Elo value and also the average of each player's Elo value weighted by games played. "rating.dat" must be located in the Working Folder and cannot be referenced using a pathname. Syntax: emStat rating.dat filename.pgn [keep] Examples: emStat rating.dat alpha.pgn emStat rating.dat alpha.pgn keep Output: outE.pgn Comments: 1. When using "EloStat 1.3" set "Minimum number of games" to "0" so that "rating.dat" will contain Elo ratings for all players. 2. A "pgn" data file for "EloStat 1.3" is limited to 1500 player names. Above that, "EloStat 1.3" will exit. 3. A player name in a "pgn" data file for "EloStat 1.3" is limited to 39 characters. Above that, the name is discarded. 4. A player with multiple name variations should have the variations consolidated before using "EloStat 1.3". See "nameList", "nameSimilar" and "nameChange". 5. This version of "emStat" is for use with "EloStat 1.3". Updates or variants of "EloStat" might not work properly with "emStat". =========================(19) fenRemove ============================ "fenRemove" removes games containing a "FEN" tag except when the "FEN" position is the standard opening position. The output file is "out6.pgn". Removed games are in "exclude6.pgn". The "FEN" of the standard opening position: rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1 Use "tagFix" to remove "FEN" & "SetUp" tags for the standard opening position. Syntax: fenRemove filename.pgn Example: fenRemove alpha.pgn Output: out6.pgn, exclude6.pgn Comments: 1. "fenRemove" removes almost all "Chess960" ("Fischer Random Chess") games. The only games it does not remove are the games where the "FEN" position is the standard opening position, a 1 out of 960 possibility. =========================(20) gameNum.exe ========================== "gameNum" inserts consecutive "game number" comments into the games. Each comment is placed at the beginning of the "MoveText Section". The default starting game number is "1". The user can select another starting number. A sample inserted comment: {game 4783} Syntax: gameNum filename.pgn [start_num] Examples: gameNum alpha.pgn gameNum alpha.pgn 101 Output: out4.pgn Comments: 1. Game number comments can be removed using "trim". However, "trim" will also remove all other comments. =========================(21) gameSplit ============================= "gameSplit" separates the "pgn" data file into a user-specified number (2-10000) of files. All games are kept intact within one of the output files. The number of games in each output file are "equal", plus or minus 1 game. For example, if the "pgn" data file has 98 games and the user runs "gameSplit" to split the data into 6 files, then the output files will contain: 17, 17, 16, 16, 16, and 16 games respectively. The output files can be used to reconstruct the "pgn" data file: copy /b gs*.pgn beta.pgn Syntax: gameSplit filename.pgn split_num Example: gameSplit alpha.pgn 2345 Output: gs0000.pgn, gs0002.pgn, ..., gs2344.pgn Example: gameSplit alpha.pgn 10000 Output: gs0000.pgn, gs0001.pgn, ..., gs9999.pgn Comments: 1. Do not put a comma in the "split_num". 2. If the "split_number" is equal to the number of games in the "pgn" file, then each output file will contain 1 game. 3. Use "copy /b" to concatenate the files back to the original. The "/b" option prevents the "eof" character from being appended to the end of the file. =========================(22) groupExtract ========================= "groupExtract" extracts games in which each player's name begins with a name_search-string located in a user-created text file named "group". "group" is organized in columnar format: name1 name2 name3 name4 Sample content for "group": Carlsen, Magnus Caruana, Fabiano Ding, Liren Aronian, Levon Nepomniachtchi, Ian Before creating "group", users should use "nameList" to check for accurate spelling and to see if any player name on the list has multiple spellings. More than one player could have a name beginning with the same name_search-string. "groupExtract" matches are NOT case-sensitive. Therefore "KARPOV" will match "Karpov". The order of the name_search-strings does NOT matter. Extracted games are sent to "outG.pgn". Games not extracted are sent to "excludeG.pgn". "manifest-g" lists the full names of the players in each game of "outG.pgn". The user should check "manifest-g" to see if any unwanted games were extracted. "group" must be located in the Working Folder and CANNOT be referenced using a pathname. Syntax: groupExtract group filename.pgn Example: groupExtract group alpha.pgn Output: outG.pgn, manifest-g, excludeG.pgn Comments: 1. The filename "group" is case-sensitive. 2. A name_search-string can contain several tokens, for example: Stockfish 2.2.2 x64 2CPU 3. A "group" name_search-string can be as small as one character. 4. "group" can contain blank lines, but that is not recommended. 5. Do not use quote marks ("") around search-strings in "group". =========================(23) listExtract ========================== "listExtract" extracts games in which at least one of the player names begin with a name_search-string in a user-created text file named "list". "list" is organized in columnar format: name1 name2 name3 name4 Sample content for "list": Carlsen, Magnus Caruana, Fabiano Ding, Liren Aronian, Levon Nepomniachtchi, Ian Before creating "list", users should use "nameList" to check for accurate spelling and to see if any player name on the list has multiple spellings. More than one player could have a name beginning with the same name_search-string. Games where the two players each have a name beginning with a name_search-string in "list", are output only once. "listExtract" matches are NOT case-sensitive. Therefore "KARPOV" will match "Karpov". The order of the name_search-strings does NOT matter. Extracted games are sent to "outL.pgn". Games not extracted are sent to "excludeL.pgn". "manifest-l" lists the full names of the players in each game of "outL.pgn". The user should check "manifest-l" to see if any unwanted games were extracted. "list" must be located in the Working Folder and CANNOT be referenced using a pathname. Syntax: listExtract list filename.pgn Example: listExtract list alpha.pgn Output: outL.pgn, manifest-l, excludeL.pgn Comments: 1. The filename "list" is case-sensitive. 2. A name_search-string can contain several tokens, for example: Stockfish 2.2.2 x64 2CPU 3. A "list" name_search-string can be as small as one character. 4. "list" can contain blank lines, but that is not recommended. 5. Do not use quote marks ("") around name_search-strings in "list". =========================(24) mateExtract ========================== "mateExtract" extracts games ending in a checkmate. "mateExtract" must be used AFTER using "pgn-extract" with the "fixresulttags" parameter. "mateExtract" looks for the presence of the checkmate symbol ("#") after the last move. Sample usage: pgn-Extract -s --fixresulttags -oout.pgn alpha.pgn mateExtract out.pgn Extracted games are sent to "outV.pgn". Games not extracted are sent to "excludeV.pgn". Syntax: pgn-Extract -s --fixresulttags -oout.pgn filename.pgn mateExtract out.pgn Output: outV.pgn, excludeV.pgn Comments: 1. Use "pgn-Extract" before using "mateExtract" otherwise the output could be incorrect. 2. A top player or chess engine will usually resign before getting mated. =========================(25) merge ================================ "merge" joins 2, 3, 4, or 5 "pgn" files by inserting one game from each successive input file, and then repeating until all games have been inserted. Example: Suppose fileA.pgn has 3 games, fileB.pgn has 2 games and fileC.pgn has 4 games. merge fileA.pgn fileB.pgn fileC.pgn The output file "outMR.pgn" will consist of: game1 from fileA.pgn followed by game1 from fileB.pgn followed by game1 from fileC.pgn followed by game2 from fileA.pgn followed by game2 from fileB.pgn followed by game2 from fileC.pgn followed by game3 from fileA.pgn followed by game3 from fileC.pgn followed by game4 from fileC.pgn Syntax: merge file1.pgn file2.pgn [file3.pgn file4.pgn file5.pgn] Examples: merge alpha.pgn beta.pgn merge alpha.pgn beta.pgn gamma.pgn merge alpha.pgn beta.pgn gamma.pgn delta.pgn merge alpha.pgn beta.pgn gamma.pgn delta.pgn epsilon.pgn Output: outMR.pgn Comment: 1. Users who prefer joining "pgn" files by concatenation (adding files consecutively) can use the tool "combine" described above. =========================(26) minDate ============================== "minDate" extracts games that were played within an inclusive user-specified time span. The output file is "outA.pgn". Games not extracted to "outA.pgn" are in "excludeA.pgn". If only one date is specified, that date is considered to be the starting date. If two dates are specified, the first date is the starting date, and the second date is the ending date. Games with an unknown year ("????") are not extracted. If the month and/or day is unknown ("??"), then "01" is assumed. Games whose date is not in the format "yyyy.mm.dd" are not extracted. Syntax: minDate filename.pgn starting_date [ending_date] Examples: minDate alpha.pgn 2004.05.01 minDate alpha.pgn 2004.05.01 2005.12.31 Output: outA.pgn, excludeA.pgn Comments: 1. When searching a "pgn" file, "minDate" treats a "??" value for month or day as equivalent to "01", and a "????" value for year as equivalent to "0001". =========================(27) minElo =============================== "minElo" extracts games where the players' Elo values are in an inclusive user-specified range or ranges. When one range is specified, both players' Elo values must be in that range. When two ranges are specified, one Elo must be in the first range, and the other Elo value must be in the second range. The output file is "outM.pgn". Games not extracted to "outM.pgn" are in "excludeM.pgn". Only games having TWO Elo ratings can be extracted. A missing Elo rating in a game prevents that game from being extracted. The user must specify 1, 2, or 4 Elo values as parameters. If 1 Elo value is specified, a game will be extracted if both of its Elos are greater than or equal to the parameter value. For example: minElo alpha.pgn 2500 will extract all games whose two Elos are at least 2500. If 2 Elo values are specified as parameters, a game will be extracted if both of its Elos values are in the inclusive range formed by the parameter values. For example: minElo alpha.pgn 2500 2700 will extract all games where both Elos are in the range of 2500 to 2700, inclusive. If 4 Elo values are specified as parameters, a game will be extracted if its two Elos are each in a different inclusive range formed by the parameter values. For example: minElo alpha.pgn 2500 2700 2400 2600 will extract all games where one Elo is in the inclusive range of 2500 to 2700, and the other Elo is in the inclusive range of 2400 to 2600. "0" is the minimum Elo value recognized in "minElo". For example: minElo alpha.pgn 0 2000 will extract all games where both Elos are less than or equal to 2000. "5000" is the maximum Elo value recognized in "minElo". For example: minElo alpha.pgn 2500 minElo alpha.pgn 2500 5000 will each extract all games where both Elo values are at least 2500. Syntax: minElo filename.pgn min_elo1 [max_elo1] [min_elo2 max_elo2] Examples: minElo alpha.pgn 2400 minElo alpha.pgn 2400 2600 minElo alpha.pgn 2400 2600 2500 2700 Output: outM.pgn, excludeM.pgn Comments: 1. When specifying an Elo range, the first Elo should not be larger than the second Elo. If it is, no games will be extracted. 2. To extract games where only ONE player's Elo rating must be in a specified Elo range, use "0 5000" as the other Elo range: minElo alpha.pgn 2500 2600 0 5000 3. When using 2 Elo ranges, the order of the ranges is not important: minElo alpha 2300 2400 2600 2700 will produce the same output as minElo alpha 2600 2700 2300 2400 =========================(28) minOccur ============================= "minOccur" extracts games of players who meet or exceed a user- specified minimum number of games. The output file is "outO.pgn". Games not extracted to "outO.pgn" are in "excludeO.pgn". Also produced are lists "beforeList" and "afterList". They list the names of players and the number of games, both before and after running "minOccur". Some players who meet or exceed the minimum number of games might not meet or exceed the minimum number of games in the output file. This can occur if some of their opponents did not meet or exceed the minimum number of games in the input file. Because of this situation, you should run "minOccur" again (after you have renamed/copied/moved "outO.pgn") until you reach a point where no players are removed. Syntax: minOccur filename.pgn minimum_games Example: minOccur alpha.pgn 100 Output: outO.pgn, beforeList, afterList, excludeO.pgn Comments: 1. Sometimes you have to rerun "minOccur" several times in order for ALL remaining players to meet or exceed the minimum number of games. Rename "outO.pgn" each time before you rerun "minOccur". =========================(29) minPly =============================== "minPly" extracts games in which the number of plies (half-moves) is within an inclusive user-specified range. "minPly" uses the value in the "PlyCount" tag to obtain the number of plies in a game. If there are missing "PlyCount" tags, use "plyCount" before "minPly". It will insert any missing "PlyCount" tags. Example: minPly alpha.pgn 21 30 outputs all games whose plycount is from 21 to 30, inclusive. The output file is "outY.pgn". Games not extracted to "outY.pgn" are in "excludeY.pgn". Syntax: minPly filename.pgn minimum_plies [maximum_plies] Example: minPly alpha.pgn 61 minPly alpha.pgn 61 100 Output: outY.pgn, excludeY.pgn Comments: 1. "minPly" does not extract games that do not have a "PlyCount" tag. Use "plyCount" prior to "minPly" to insert missing "PlyCount" tags. 2. To remove games with 0, 1, or 2 plies, use the command-line: minPly alpha.pgn 3 =========================(30) nameChange =========================== "nameChange" performs user-specified player name changes based on a user-created text file named "changes". "nameChange" can be used to consolidate variations of a player's name into one form. "outC.pgn" contains the output games with the name changes. "manifest-c" lists all the name changes. It is very important to check "manifest-c" that the names were changed as planned. Create the text file "changes" in columnar form as follows: name1 to be changed replacement name1 name2 to be changed replacement name2 name3 to be changed replacement name3 There must not be any blank lines at the start or in the middle of the "changes" file. The same "name to be changed" should not occur more than once. However, if he does, only the last "replacement name" is used. If the same "name to be changed" occurs more than once, only the last "replacement name" is used. The same "replacement name" can appear more than once. "changes" must be located in the Working Folder and cannot be referenced using a pathname. "tagFix" will change the name tag values if there is a structural issue with the tag. It is a good idea to use "tagFix" before using "nameChange". Syntax: nameChange changes filename.pgn Example: nameChange changes alpha.pgn Output: outC.pgn, manifest-c Comments: 1. The filename "changes" is case-sensitive. 2. "name to be changed" and "replacement name" in "changes" are case-sensitive. 3. A "name to be changed" must be on an odd-numbered line, and a "replacement name" must be on an even-numbered line. There must not be any blank lines at the start or in the middle of "changes". 4. Player names do not have to be in order. 5. Quotation marks must not be used in "changes". 6. After using "nameChange", the user should scan "manifest-c" to check that the changes went as planned. =========================(31) nameColor ============================ "nameColor" adds a token, "(wh)" or "(bl)", to each player's name depending on the color being played. For example, "Karpov, A. (wh)" and "Karpov, A. (bl)". Using the color tokens makes it easier to create lists and do calculations based on the color played. "colorList" lists player results for White and Black. Syntax: nameColor filename.pgn Example: nameColor alpha.pgn Output: outK.pgn Comments: 1. " (wh)" and " (bl)" can be removed using "find and replace" in a text editor. 2. "playerExtract" will extract a player's games by color. =========================(32) nameExtract ========================== "nameExtract" extracts games in which at least one player's name begins with a user-specified name_search-string. The name_search-string must match the beginning of the player's name including any embedded spaces and punctuation. However, the match does NOT have to be case-sensitive. For example, the search string "FiScH" will match "Fischer, Robert", "Fischer, R." and "FISCHER, Robert J.". Use "nameList" before using "nameExtract" to check the spelling of player names. More than one player could have a name beginning with the same name_search-string. Games between such players are output only once. The name_search-string must be within quotation marks if it contains an embedded space. The output file is "outN.pgn". Games not output to "outN.pgn" are output to "excludeN.pgn". "manifest-n" lists the full names of the players in each game of "outN.pgn". The user should check "manifest-n" to see if any unwanted games were extracted. "nameExtract" is similar to "listExtract". "listExtract" does the same type of search but uses a text file containing one or more user-specified name_search-strings. Syntax: nameExtract filename.pgn name_search-string Example: nameExtract alpha.pgn Stockfish Output: outN.pgn, manifest-n, excludeN.pgn Comments: 1. Matches between "name_search-string" and the beginnings of the names in the "pgn" file are not case-sensitive. 2. "name_search-string" must be enclosed within quotation marks if it has an embedded space. 3. "nameExtract" is useful for extracting all versions of a user-specified chess engine. For example, if the name_search-string is "Stockfish", then games of all versions of "Stockfish" would be extracted. 4. "nameExtract" extracts the games of multiple players whose names have the same beginning. Use "playerExtract" to extract the games of just one specific player. =========================(33) nameList ============================= "nameList" lists player names and games played in three different output files. It also has the option to output names in "all caps". The first output file "outName", lists the names in sorted order, without any headings and the number of games played. The second output file "outName2", lists the names and games played, sorted by names. It includes a heading. The third output file "outName3", lists the names and games played, sorted by games played in descending order. It includes a heading. The optional parameter "CAP" outputs all names in uppercase. This is useful in clearing up multiple spellings due to case differences. If the number of names with CAPS is less, then there is a duplicate name due to a case difference. Syntax: nameList filename.pgn [CAP] Example: nameList alpha.pgn nameList alpha.pgn CAP Output: outName, outName2, outName3 Comments: 1. "CAP" is case-sensitive. 2. "nameList" and "nameSimilar" can be used to find spelling variations of a player name. "nameChange" can be used to consolidate the spelling to one variation. =========================(34) nameSimilar ========================== "nameSimilar" lists player names that start with the same token or the same three characters. The number of games for each player is listed. "nameSimilar" is useful in finding name variations of the same player. For example, "Karpov, Anatoly" and "Karpov, A.", or "Kasparov, Garry" and "Kasparov, Gary", or "Korchnoi, Viktor" and "Kortchnoj, V." Sometimes a player's multiple names will have a capitalization difference and would not be found by "nameSimilar". For example, "Fritz" and "FRITZ". In this case, the "CAP" option of "nameList" may be helpful. Sometimes a player's multiple names will have a major spelling difference and would not be found by "nameSimilar". For example, "Yusupov, Artur" and "Jussupow, Artur". In this case, the player chose to change his name. Use "nameChange" to change the spelling of a player's name. Syntax: nameSimilar filename.pgn Example: nameSimilar alpha.pgn Output: outSimilar =========================(35) numExtract =========================== "numExtract" extracts games whose game number matches a game number in a user-specified text file "numbers". The output file is "outZ.pgn". Games not extracted to "outZ.pgn" are in "excludeZ.pgn". The output file "excludeZ.pgn" would be the desired output file if the user wanted to remove the games whose numbers are in "numbers", from the input file. The user has to create a text file named "numbers" containing the game numbers of the games to be extracted. One number per line. For example: 93 164 72 106 Games will be output in their original order even if the game numbers are not in numerical order. For example, in the above example, the games will be output as follows: game 72 game 93 game 106 game 164 Duplicate numbers are ignored. Blank lines are ignored. "numbers" must be located in the Working Folder and cannot be referenced using a pathname. Syntax: numExtract numbers filename.pgn Example: numExtract numbers alpha.pgn Output: outZ.pgn, excludeZ.pgn =========================(36) pairExtract ========================== "pairExtract" extracts games in which each player's name begins with a different name_search-string from the same pair in a user-created text file named "pairs". For each name_search-string, more than one player could have a name starting with that search-string. The output file is "outP.pgn". Games not extracted to "outP.pgn" are in "excludeP.pgn". "manifest-p" lists the full names of the players of each game in "outP.pgn". The user should check "manifest-p" to see if any unwanted games were extracted. Use "nameList" before using "pairExtract" to check the spelling of player names. To use "pairExtract", the user has to first create a text file named "pairs". This file will contain successive pairs of name_search- strings. "pairs" is organized in columnar format: name1 of pair1 name2 of pair1 name1 of pair2 name2 of pair2 "pairs" should not contain any blank lines. "pairs" must have an even number of data lines. The order of names within a pair does not matter. Sample content of a "pairs" file: Kasparov Karpov Topalov Kramnik In the above example, all games between players (regardless of color arrangement) whose names start with "Kasparov" and "Karpov", or "Topalov" and "Kramnik", will be extracted to "outP.pgn". The two player names have to match different search-strings. "pairExtract" matches are not case-sensitive. Therefore the pair: kASPARov KARpov will get the same matches as the pair: Kasparov Karpov "pairExtract" is useful for removing intra-family games between computer engines. Intra-family games are games between versions of the same engine or its derivatives. For example, the following pairs will extract intra-family games between Stockfish versions and intra-family games between Komodo versions: Stockfish Stockfish Komodo Komodo In this case "excludeP.pgn" would be the useful output file because it will NOT contain the intra-family games. "pairs" must be located in the Working Folder and cannot be referenced using a pathname. Syntax: pairExtract pairs filename.pgn Example: pairExtract pairs alpha.pgn Output: outP.pgn, manifest-p, excludeP.pgn Comments: 1. The filename "pairs" is case-sensitive. 2. Matches between names in "pairs" and the beginning of the names in the "pgn" file are not case-sensitive. 3. A name_search-string can contain several tokens, for example: "Kasparov, Garry" 4. A "pairs" name_search-string can be as small as one character. 5. Quotation marks must not be used within "pairs". =========================(37) pairList =========================== "pairList" lists player pairings, the number of games, and the results of each pairing. Each pairing lists the TOTAL results between the two players. There are two listings for each pairing so that the user can find the pairing with either player's name first. Color played is ignored. If you wish to see the results by color played, use "nameColor" before using "pairList". Results are read from the point of view of the first player listed. For example: Spassky, Boris V. : Smyslov, Vasily 11 : 4+ : 5= : 2- : 59.09% In this example, Spassky is listed first. The "11" is the total number of games played between them. "4+" indicates that Spassky won "4" games. "5=" indicates "5" draws. "2-" indicates that Spassky lost "2" games. "59.09%" is Spassky's score percentage. Each pairing is listed twice, with each player being "first" in one of the pairings. The order of the pairings has nothing to do with the color played because the results are the TOTAL results for all games between the players. If you want to see the pairing results based on the color played, then first use "nameColor" before using "pairList". Syntax: pairList filename.pgn Example: pairList alpha.pgn Output: outPairs Comment: 1. "clusterList" lists the number of distinct opponents for each player. =========================(38) pairSimilar.exe ====================== "pairSimilar" lists player pairs where the player names start with the same token AND where the players have played each other. The number of games for each pair is listed. "pairSimilar" helps to identify "intra-family" games. Those are games between different versions of the same computer engine family or games between derivatives of the same computer engine. Once such games are identified, they can be extracted using "pairExtract". For example, "Stockfish 2.2.2" and "Stockfish 2.3.1", would be listed by "pairSimilar". However intra-family pairs "Fritz" and "Deep Fritz", and "Fruit" and "Toga", would NOT be listed. "pairSimilar" might list engine pairs that are NOT intra-family pairs. For example, "Deep Fritz" and "Deep Shredder". Syntax: pairSimilar filename.pgn Example: pairSimilar alpha.pgn Output: outPS Comments: 1. Use "pairExtract" to extract the games of user-specified player pairs. =========================(39) pairSplit ============================ "pairSplit" extracts the games of each player pair into their own file. Only the first 1000 player pairs (in sorted order) are processed at each "pairSplit" execution. The remaining games are collected into an "exclude" file which can be processed at a later time. The games of the player pairs are put into the files "box000.pgn", "box001.pgn", ... , "box999.pgn", assuming there are at least 1000 player pairs. If less than 1000 player pairs, the number of files equals the number of pairs. If there are more than 1000 player pairs, then the leftover games are extracted to "excludeBox.pgn". The output file "manifest-box" lists each player pairing (in sorted order) with the file containing its games. The number of games of each player pairing is also listed. The games in "excludeBox.pgn" can be processed by "pairSplit" but only after renaming "excludeBox.pgn". Also, the previous output files in the working folder must be renamed/copied/moved or the next execution of "pairSplit" will overwrite them. One execution of "pairSplit" is sufficient to create a file for each player pairing in a 45-player round-robin tournament (990 files). Syntax: pairSplit filename.pgn Example: pairSplit alpha.pgn Output: box000.pgn --> box999.pgn, excludeBox.pgn, manifest-box Comments: 1. "pairList" can tell you how many player pairs are in the data file so you can determine in advance how many executions of "pairSplit" will be needed. =========================(40) pgn2stream =========================== "pgn2stream" converts a "pgn" file into a "move steam" file. A "move stream" is a full chess game condensed to a single line. It consists of the moves and the result, and optionally, the move numbers. Examples (shortened): 1. h3 e5 2. c4 Nc6 3. e3 Nf6 4. a3 d5 5. cxd5 Nxd5 6. Qc2 a6 7. Nf3 Be6 1/2-1/2 a3 d5 e3 c5 Bb5+ Bd7 Bxd7+ Nxd7 f4 e6 Nf3 Bd6 O-O 1-0 "outStream" is the output file containing move numbers. "outStream2" is the output file without move numbers. "pgn2stream" does NOT convert games with a "FEN" tag to a "move stream". Instead, a blank line is output. That maintains the relationship between the game number and the line number. The user can remove all "FEN" games before using "pgn2stream" by using "fenRemove" on the input file. "pgn2stream" removes comments, nags, variations, and major symbolic annotation symbols (!, !!, ?, ??, !?, ?!, +-, -+, +/-, -/+, +=, =+, +/=, =/+, =, ~, and N), if present. Using "gameNum" on the input file before using "pgn2stream" will help coordinate the game number and the line number in the "move stream" file. Syntax: pgn2stream filename.pgn Example: pgn2stream alpha.pgn Output: outStream, outStream2 Comment: 1. "stream2pgn" converts a "move stream" file to a "pgn" file. Using "pgn2stream" after using "stream2pgn", will insert move numbers into the original input (if any were missing). =========================(41) playerExtract ========================== "playerExtract" extracts the games of a user-specified player. It also outputs the player's games by color and result. The name_search-string must match the player's name exactly including any embedded spaces and punctuation. However, the match does NOT have to be case-sensitive. For example, the search string "stockfish 12" will match "StockFish 12". The name_search-string must be within quotation marks if it contains an embedded space. The player's games are output to "outPlayer.pgn". Games not output to "outPlayer.pgn" are output to "excludePlayer.pgn". The output file "excludePlayer.pgn" would be the desired output file if the user wanted to remove the games of the user-specified player from the input file. The player's games as White and Black are extracted to "outWhite.pgn" and "outBlack.pgn" respectively. The player's wins, draws and losses are extracted to "outWin.pgn", "outDraw.pgn" and "outLose.pgn" respectively. The player's games without a result are extracted to "outNoRes.pgn". Use "nameList" before using "playerExtract" to check the spelling of the players' names. Self-play games will cause some sort of output error based on color or the result. Those games will be output only once to "outPlayer.pgn". Use "cleanUp" to remove self-play games (and games without a result) before using "playerExtract". Syntax: playerExtract filename.pgn name_search-string Example: playerExtract alpha.pgn "Karpov, Anatoly" Output: outPlayer.pgn, outWhite.pgn, outBlack.pgn, outWin.pgn, outDraw.pgn, outLose.pgn, outNoRes.pgn, excludePlayer.pgn Comments: 1. "playerExtract" matches between the name in "name_search-string" and the names in the "pgn" file are not case-sensitive. 2. "name_search-string" must be enclosed within quotation marks if it has an embedded space. 3. "playerExtract" extracts the games of one specific player. Use "nameExtract" to extract the games of multiple players whose names have the same starting characters. =========================(42) plyCount ============================= "plyCount" counts the number of plies (half-moves) of each game and inserts a new "PlyCount" tag if one is missing. Existing "PlyCount" tags are unchanged. "plyCount" also produces "outPlies" which is a listing of plycounts and the number of occurrences. "plyCount" only counts those plies that are physically present in the "MoveText Section". Moves embedded in the "FEN" position are not counted. "plyCount" removes "en passant" indicators "ep", "e.p." and "/ep", if present, to prevent them from adding to the ply count. Syntax: plyCount filename.pgn Example: plyCount alpha.pgn Output: outX.pgn, outPlies Comments: 1. "plyCount" can be used with "minPly" to extract games whose ply counts lie in a user-specified range. =========================(43) resultList =========================== "resultList" lists player names, number of games, number of wins, draws, losses, score percentages, result points, and S-B tie-break points. There are three output files. Games without a Result ("*") are ignored in the output. The output file "outRes" contains player names, the number of games, the number of wins, draws, losses, and score percentages. It is sorted by player name. The output file "outRes2" contains the same data as "outRes" but is sorted by descending score percentage. The output file "outRes3" contains player names, the number of games, the number of wins, draws, losses, result points, S-B points, and score percentages. "outRes3" is sorted by descending result points, and secondly by decreasing S-B (Sonneborn-Berger) tie-break points. "outRes3" is intended for use with "Round-Robin" or "Swiss System" tournaments where a "result table" is desired. "outRes3" contains all information that is normally associated with a "result table" except for results between each pair of players. Use the "40H-PGN" tool "pairList" to see the results between each pair of players. Although many round-robin tournaments use "S-B" as one of their tie-breakers. many others do not. Syntax: resultList filename.pgn Example: resultList alpha.pgn Output: outRes, outRes2, outRes3 Comments: 1. "cleanUp" will remove games without a result ("*"). =========================(44) resultSplit ========================== "resultSplit" separates the "pgn" data file into four files based on the results of the games. There is an output file for "White Wins", "Draws", "Black Wins", and "no result". "resW.pgn" contains games that White won. "resD.pgn" contains games that ended in a draw. "resB.pgn" contains games that Black won. "resN.pgn" contains games without a Result. Syntax: resultSplit filename.pgn Example: resultSplit alpha.pgn Output: resW.pgn, resD.pgn, resB.pgn, resN.pgn Comments: 1. Use "cleanUp" to remove games without a result ("*"). 2. "resultSplit" extracts all the "no result" games in the input file, while"playerExtract" extracts the "no result" games of a specified player. =========================(45) stream2pgn =========================== "stream2pgn" converts a "move stream" file into a "pgn" file. A "move stream" is a full chess game condensed to a single line. It consists of the moves and the result, and optionally, the move numbers. "steam2pgn" can also convert a modified "move stream" that is missing the move numbers and/or the result. Examples (shortened): a3 f5 e3 Nf6 f4 e6 Nf3 b6 Be2 Bb7 O-O Be7 d3 O-O Ne5 d6 Bf3 c6 Nc4 1-0 h3 e5 c4 Nc6 Nc3 g6 Nf3 Bg7 g3 Nge7 d3 d5 cxd5 Nxd5 Bd2 Be6 Bg2 O-O 1. a3 f5 2. e3 Nf6 3. f4 e6 4. Nf3 b6 5. Be2 Bb7 6. O-O Be7 7. d3 O-O 8. Ne5 d6 9. Bf3 c6 10. Nc4 1-0 1. h3 e5 2. c4 Nc6 3. Nc3 g6 4. Nf3 Bg7 5. g3 Nge7 6. d3 d5 7. cxd5 Nxd5 8. Bd2 Be6 9. Bg2 O-O [Event "?"] [Site "?"] [Date "????.??.??"] [Round "1"] [White "?"] [Black "?"] [Result "1-0"] 1. a3 f5 2. e3 Nf6 3. f4 e6 4. Nf3 b6 5. Be2 Bb7 6. O-O Be7 7. d3 O-O 8. Ne5 d6 9. Bf3 c6 10. Nc4 1-0 [Event "?"] [Site "?"] [Date "????.??.??"] [Round "2"] [White "?"] [Black "?"] [Result "*"] 1. h3 e5 2. c4 Nc6 3. Nc3 g6 4. Nf3 Bg7 5. g3 Nge7 6. d3 d5 7. cxd5 Nxd5 8. Bd2 Be6 9. Bg2 O-O * [Event "?"] [Site "?"] [Date "????.??.??"] [Round "3"] [White "?"] [Black "?"] [Result "1-0"] 1. a3 f5 2. e3 Nf6 3. f4 e6 4. Nf3 b6 5. Be2 Bb7 6. O-O Be7 7. d3 O-O 8. Ne5 d6 9. Bf3 c6 10. Nc4 1-0 [Event "?"] [Site "?"] [Date "????.??.??"] [Round "4"] [White "?"] [Black "?"] [Result "*"] 1. h3 e5 2. c4 Nc6 3. Nc3 g6 4. Nf3 Bg7 5. g3 Nge7 6. d3 d5 7. cxd5 Nxd5 8. Bd2 Be6 9. Bg2 O-O * "stream2pgn" ignores blank lines in the input file. The "Round" tag value in "outST.pgn" is the line number of the "move stream" in the input file, assuming no blank lines. Using "gameNum" on the output file "outST.pgn" will help coordinate the game number and line number in the "move stream" file, assuming no blank lines. Syntax: stream2pgn move_stream_filename Example: stream2pgn gamelines Output: outST.pgn Comments: 1. Each "move stream" MUST be on a SINGLE line of the text file. Sometimes a text editor will use a soft word-wrap if the single line exceeds its low character limit (1024 for example). However, the "move stream" line may still be a single line in the text file. In this case, use a different text editor to avoid this situation. 2. You can use "trim" on "outST.pgn" to improve its formatting. =========================(46) summary ============================== "summary" produces statistics involving games, players, clusters, dates, Elo ratings, results, ECO values, and plycounts. The Elo average and standard deviation statistics are based on the games, not the players. For example, the average of White Elo is the sum of the White Elo values in all the games, divided by the number of games with a White Elo value. All Standard Deviation calculations in "summary" use the "Population" formula. Plycount statistics are based on PlyCount tags. Use "plyCount" to insert missing "PlyCount" tags. Syntax: summary filename.pgn Examples: summary alpha.pgn Output: to the display, outSummary Comments: 1. Try using "tagFix" on the input "pgn" file if there is unusual output. =========================(47) tagCreate ============================ "tagCreate" inserts a user-specified tag type (other than "Event") into the Tag Section of each game. The "Event" tag must already be present. All previous tags of the inserted tag type are removed. The user-specified tag type and its value must be written on the first line in a text file named "newtag". Lines after the first line are ignored. Example of the first line in "newtag": [Source "Reinfeld 1001 Sac and Comb"] The new tags are inserted at the bottom of the Tag Section of each game. The Tag Section can then be re-ordered using "tagOrder". All tags of this type will have the same tag value. To customize the values you could use a text editor or "tagInsert". "tagCreate" should NOT be used to insert new "Elo", "ECO" or "Plycount" tags. New "Elo" tags can be inserted by "embayes", "emOrdo" or "emStat". New "ECO" tags can be inserted by SCID or "PGN-Extract". New "PlyCount" tags can be inserted by "plyCount". "tagCreate" can only insert one new tag type on each execution. If you want to insert another tag type, rename "out9.pgn" before using it as an input file. If the new tags have the same value then use "tagCreate". You can use a text editor when the new tags have many different values. Example: tagCreate newtag alpha.pgn tagOrder out9.pgn Output: out9.pgn, out3.pgn Comments: 1. The filename "newtag" is case-sensitive. 2. A text file for the new tag is used instead of a command line due to issues with embedded quotation marks. =========================(48) tagExtract ========================= "tagExtract" extracts games based on a user-specified tag type and a user-specified search string. The search string can either be a single token or a complete tag value. "tagExtract" is the only tool in "40H-PGN" tools that can extract games based on any tag-type. It is not tag type specific. "tagExtract", in Standard mode, extracts games where there is a match between a user-specified search token and a token in a tag value of the user-specified tag type. Some tokens may have a punctuation mark attached, such as a comma or a period. The match is not case-sensitive. "tagExtract", in Optional mode (parameter "entire"), extracts games where there is a match between the user-specified search string and a complete tag value of the user-specified tag type. The search string MUST be enclosed in quotation marks if it has an embedded space. The match is not case-sensitive. Using "tagValue" before using "tagExtract" provides a list of all the tag values of a user-specified tag. It is not recommended to use "tagExtract" to extract the games of a specific player because you would have to extract twice, once with "White" and once with "Black". Instead, use either "playerExtract" or "nameExtract". The output file is "outT.pgn". "manifest-t" lists the players in the games in "outT.pgn". Games not extracted to "outT.pgn" are put into "excludeT.pgn". Syntax: tagExtract filename.pgn tag_name search_string [entire] Examples: tagExtract alpha.pgn Event Open tagExtract alpha.pgn Site "New York, N.Y." entire Output: outT.pgn, excludeT.pgn, manifest-t Comments: 1. "tag_name" is "case-sensitive". 2. In "Standard" mode, matches between the token in "search-string" and the tokens in the "tag_name" tags are not case-sensitive. 3. In "Optional" mode with the parameter "entire", matches between the "search-string" and the tag values in the "tag_name" tags are not case-sensitive. 4. Quotation marks are not necessary for a single token except in rare circumstances. For example: "&". =========================(49) tagFix ============================== "tagFix" repairs a limited number of tag irregularities. "tagFix" produces "out7.pgn" and "manifest-f". "manifest-f" lists the repairs and should be examined after each execution to be sure that no unexpected repairs were performed. "tagFix" removes hidden control characters at the beginning of a "UTF-8" encoded "pgn" file. "tagFix" removes backslash ("\") character(s) at the end of any tag value. For example, [Site "New York\\"] becomes [Site "New York"]. Without this fix, Windows would consider the closing quotation mark to be part of the tag data value. "tagFix" removes beginning or ending space(s) (" ") in a tag value. For example: [Site " New York " ] becomes [Site "New York"]. The extra space in the middle of a tag data value is not removed. "tagFix" removes a comma (",") at the end of a "White" or "Black" tag value. "tagFix" removes a period (".") at the end of a "White" or "Black" tag value provided the last token of the name has at least two characters (not counting the period). For example: "Jones, AC." becomes "Jones, AC", but "Smith, B." is unchanged. If needed, "tagFix" inserts a "space" after a "comma" in the name value of a "White" or "Black" tag. For example: [White "Spassky,Boris"] becomes [White "Spassky, Boris"]. If needed, "tagFix" inserts a "period" after an isolated uppercase alphabetical character in the data value of a "White" or "Black" tag provided the data value contains a comma. For example: [Black "Smith, A"] becomes [Black "Smith, A."]. [White "Jones, A B"] becomes [White "Jones, A. B."] "tagFix" will not insert a period in [White "Wilson, AB"]. "tagFix" will not insert a period after an isolated non-alphabetical character such as in [Black "Naum 4"]. "tagFix" will not insert a period after an isolated single lowercase alphabetical character such as in [White "Jones, y"] or as in [White "Jones y Smith, Tom"]. "tagFix" will not insert a period after a single alphabetical character followed by a comma, as in [Black "A, Robert"]. "tagFix" will not insert a period if the name does not have a comma, as in [White "King George V"]. However [White "King, George V"] will be changed to [White "King, George V.]. For "FEN" and "SetUp" tags, "tagFix" does the following: 1. Removes any "FEN" & "SetUp" tags for the standard opening position. 2. Removes individual "SetUp" tags not accompanied by "FEN" tags. 3. Ensures that "FEN" tags are accompanied by "SetUp" tags with value "1". "tagFix" inserts a null value ("?" or "*" or "????.??.??") for a missing tag data value (""). Syntax: tagFix filename.pgn Example: tagFix alpha.pgn Output: out7.pgn, manifest-f Comments: 1. Examine "manifest-f" to look for any unexpected change(s) made by "tagFix". =========================(50) tagInsert ============================ "tagInsert" replaces all tag values of a user-specified tag type with user-specified values in a text file. The chosen tag type must be present in every game of the "pgn" file. The user-specified file is named "tagdata". Tag values must be on successive lines, with no lines blank. The line number of the tag value has to correspond to the number of the game where it will be inserted. If the chosen tag type is not present at all or is not present in some games, you can use "tagCreate" to fix the problem. It will, after removing any existing tags of the tag type, insert a new tag in every game. The values of the new tags are unimportant because "tagInsert" will be replacing those values. "tagInsert" might NOT work properly if the number of tag values in "tagdata" is NOT equal to the number of games in the "pgn" file. If they are not equal, a WARNING message with the different numbers will be displayed. See the comment below. If the new tags have many different values then use "tagInsert". Use "tagCreate" when all the new tags have the same value. Also a text editor can be used. Syntax: tagInsert filename.pgn tag_type tagdata Example: tagInsert alpha.pgn Round tagdata Output: out1.pgn Comments: 1. "tag_type" and the filename "tagdata" are case-sensitive. 2. Sometimes the number of data values in "tagdata" is not what you expect because of a missing at the end of the last data line, or because of extra blank data lines. 3. The best way to create a long column of data values is to use an Excel worksheet. Then save it as a text file. =========================(51) tagList ============================== "tagList" lists each tag type that occurs in the "pgn" file and its number of occurrences. Syntax: tagList filename.pgn Example: tagList alpha.pgn Output: outTag =========================(52) tagNull ============================== "tagNull" replaces all values of a user-specified tag type with the appropriate null value EXCEPT for the "FEN" tag type. The tag type is listed as a parameter. Unless specified below, the null value is "?". For the "Date" tag and "...Date" tags (for example "EventDate"), the null value is "????.??.??". For the "Result" tag, the null value is "*". Also the result value at the end of the "MoveText Section" is set to "*". For the "Time" tag, the null value is "??:??:??". For the "SetUp" tag, the null value is "0". "tagNull" will NOT replace the values of "FEN" tags as that will usually make the PGN game description ILLEGAL. "fenRemove" removes GAMES with a "FEN" tag except if the "FEN" value is the standard opening position. "tagFix" removes "FEN" tags whose value is the standard opening position. "tagNull" replaces all previous tag values even if some of them were the null value. Therefore the number of null values inserted equals the number of tag occurrences. Use "tagList" before using "tagNull" to see the previous tag types. If you wish to set more than one tag type to its default value, then you have to rerun "tagNull" for each tag type. Be sure to rename "outH.pgn" before the next execution of "tagNull". For example: tagNull alpha.pgn Event copy outH.pgn temp.pgn tagNull temp.pgn Site copy outH.pgn temp.pgn tagNull temp.pgn Round The file "outH.pgn" will now have the tag types Event, Site, and Round set to their default values. Syntax: tagNull filename.pgn tag_name Example: tagNull alpha.pgn Round Output: outH.pgn Comments: 1. "tag_name" is case-sensitive. =========================(53) tagOrder ============================= "tagOrder" rearranges the tag types into a generally accepted order. The first 13 tag types are ordered as follows: "Event", "Site", "Date", "Round", "White", "Black", "Result", "WhiteElo", "BlackElo", "ECO", "SetUp" and "FEN". Then come various other tags in their original order, followed by the "PlyCount" tag. Syntax: tagOrder filename.pgn Examples: tagOrder alpha.pgn Output: out3.pgn =========================(54) tagRemove ============================ "tagRemove" removes all instances of a user-specified tag type EXCEPT for "Event" and "FEN" tag types. The tag type to be removed is listed as a parameter. It is NOT recommended to remove required tags types: "Site", "Date", "Round", "White", "Black" and "Result". "Event" is a required tag that "tagRemove" will NOT remove. With "tagRemove" you can remove many miscellaneous tags types at one time by using the parameter value "misc". "misc" will remove all tag types EXCEPT: "Event", "Site", "Date", "Round", "White", "Black", "Result", "WhiteElo", "BlackElo", "ECO", "SetUp", "FEN", "PlyCount", "TimeControl" and "Termination". Be careful using the parameter value "misc". It may remove important tag types that you want to keep. Users should first use "tagList" to check which tag types are present. "tagRemove" will NOT remove "FEN" tags as that will usually make the PGN game description ILLEGAL. "fenRemove" removes GAMES with a "FEN" tag except if the "FEN" value is the standard opening position. "tagFix" removes "FEN" tags whose value is the standard opening position. If you wish to remove more than one tag type without using "misc", then you have to run "tagRemove" for each tag type to be removed. Be sure to rename/copy "outJ.pgn" before the next execution of "tagRemove". For example: tagRemove alpha.pgn Site copy outJ.pgn temp.pgn tagRemove temp.pgn Round copy outJ.pgn temp.pgn tagRemove temp.pgn ECO The output file "outJ.pgn" will no longer have the tag types "Site", "Round" and "ECO". Syntax: tagRemove filename.pgn [tag_name | misc] Example: tagRemove alpha.pgn WhiteElo Example: tagRemove alpha.pgn misc Output: outJ.pgn Comments: 1. "tag_name" and "misc" are case-sensitive. 2. "eloRemove" removes all "WhiteElo" and "BlackElo" tags. 3. An alternative to removing tags is to use "tagNull" to insert null values. =========================(55) tagValue ============================= "tagValue" lists the data values of a user-specified tag type and the number of occurrences of each data value. Syntax: tagValue filename.pgn tag_name Example: tagValue alpha.pgn Event Example: tagValue alpha.pgn Termination Output: outVal Comments: 1. "tag_name" is case-sensitive. =========================(56) trim ================================= "trim" produces an output "pgn" file that puts each "full move" on the same line while also removing comments if present. "trim" lets you set the maximum output width in the "MoveText Section" from 40 to 100 characters. The default is 76 characters. "trim" removes comments, nags, variations, and major symbolic annotation symbols (!, !!, ?, ??, !?, ?!, +-, -+, +/-, -/+, +=, =+, +/=, =/+, =, ~, and N), if present. "trim" removes "en passant" indicators "ep", "e.p." and "/ep", if present. If needed, "trim" inserts a space (" ") after a move number. For example, "1.e4" becomes "1. e4". "trim" changes any occurrences of numerical castling notation ("0-0", "0-0-0") to alphabetical ("O-O", "O-O-O"). "trim" changes any occurrences of "1. ..." to "1...", and similarly for any other move number. "trim" starts each new line of moves with a move number. Syntax: trim filename.pgn [output_width] Examples: trim alpha.pgn trim alpha.pgn 60 Output: outR.pgn =========================(57) truncate ============================= "truncate" counts the number of plies (half-moves) and then removes any plies occurring after a user-specified number. If a game has fewer plies than the user-specified number, that game is output without change. Results are not removed. "truncate" removes existing "PlyCount" tags. New "PlyCount" tags can be inserted using "plyCount". "truncate" removes comments, nags, variations, and major symbolic annotation symbols (!, !!, ?, ??, !?, ?!, +-, -+, +/-, -/+, +=, =+, +/=, =/+, =, ~, and N), if present. "truncate" removes "en passant" indicators "ep", "e.p." and "/ep", if present, so that they do not distort the ply count. Syntax: truncate filename.pgn maximum_plies Example: truncate alpha.pgn 50 Output: outU.pgn Comments: 1. To remove all game moves but leave the results: truncate alpha.pgn 0 =========================(58) upset ================================ "upset" extracts games between two players having an Elo difference equal to or greater than the "min_Elo_difference", which by default, is 250. Output is in three files for wins, draws, and losses. The user can specify another minimum Elo difference. Output files "outU1.pgn", "outU2.pgn" and "outU3.pgn" contain games between players whose Elo difference is equal to or greater than the "min_Elo_difference". All other games are sent to "excludeU4.pgn". Output file "outU1.pgn" contains games won by the player with the lower Elo. These games are the "upsets". Output file "outU2.pgn" contains games ending in a draw. Output file "outU3.pgn" contains games won by the player with the higher Elo. Output file "excludeU4.pgn" contains all other games. "upset" does not extract games missing an Elo rating or missing a result. Use "eloCheck" to remove games with a missing Elo rating. Use "cleanUp" to remove games without a result ("*"). Syntax: upset filename.pgn [min_Elo_difference] Usage: upset alpha.pgn upset alpha.pgn 300 Output: outU1.pgn, outU2.pgn, outU3.pgn, excludeU4.pgn ==================================================================== ====================================================================