Preparing Reports with tsh

How to list standings, pairings and more using tsh.

Updated Wed Oct 8 10:34:05 EDT 2008 for tsh 3.260.

After you have entered scores for your tournament, you will likely want to produce and print reports such as standings and pairings tables using tsh. Each type of report is generated using its own command, and most report-generating commands display some information on your screen while saving it to an HTML file which you may print.

To print the most recent report that you generated, enter the “BrowseLast” command to open the report in a new browser window, then use your browser’s print command. To print older reports, and to see which ones are available, enter the “Browse” command to open a report index in a new browser window.

By default, HTML files are created in the “html” subdirectory of your event directory. If your computer runs its own locally accessible web server (most computers can be configured to do so), then you may wish to create the HTML files directly in the server directory using “config html_directory” so that your players can check reports on their laptops or at browser kiosks that you have set up at your tournament. If you would like to have the HTML files directly in the event directory as well as in a subdirectory, you may use the “config html_in_event_directory” configuration option (this was default behaviour prior to version 3.170).

The formatting of the HTML file is controlled by a CSS stylesheet called “tsh.css” If you want to copy your report files to a remote web server, you must include a copy of this file in the same directory as your report files, or they will not be displayed correctly. tsh includes master versions of the stylesheet for various realms, and if there is no stylesheet in your HTML directory, it installs a copy of the appropriate one. Once it has done so, you may make your own local changes to it if you do not care for the default style, but if you think your changes might be of general use, please send them in for inclusion in the tsh distribution.

For the sake of backward compatibility and in case tsh is run on a computer without a web browser, reports are also saved in text format. If you do not want text files to clutter your event directory, use the “config no_text_files” configuration option.

Player Photos

Some commands will display photographs to help identify players, if the “config player_photos = 1” configuration option is specified in your configuration file, and if you have one of the optional photo databases installed. These currently include: “ShowPairings” and “ScoreBoard”. Use the “photo_database” configuration option to choose a photo database, then keep it updated using the “updatepix” command. (This may take a while on a slow Internet connection.) Databases are currently available for NSA and ABSP players; tournament directors from outside those jurisdictions shoudl contact John Chew to set up their own databases.

Pairings

Before each round begins, you need to print up pairings, showing who is playing whom where. If you are using Fontes Swiss pairings, these pairings will typically be available sometime in the middle of the preceding round, as soon as you have finished entering and checking the second preceding round’s results. You should post them as quickly as possible, so that anyone who finishes their game early will know right away who their next opponent is.

The pairings for a given division and round may have already been computed (and will be displayed right away), may need to be computed (and will be displayed after a brief delay), or may not yet be computable (and you’ll see an error message if you ask for them, instructing you to enter more scores before asking for the pairings).

You show pairings using the “ShowPairings round division” command. To list pairings (e.g.) for round 5, division C, enter the command “sp 5 c”. (If you have only one division, you may omit it, so you’d enter “sp 5”.) As noted at the beginning of this section, this will display on your screen who is playing whom where, create two printable HTML files called “C-alpha-pairings-005.html” (in alphabetical order of player name, in a two-column format if tsh thinks it will look better that way) and “C-pairings-005.html” (by player rank), and one text file called “C-pairings.doc”.

Several configuration options affect pairings reports. Their effects are described in the following table.

OptionEffectUsefulness
alpha_pair_single_column If set, forces alphabetical pairings to appear in single-column format. You might want to use this, if you have very long player names, as is the case at the U.S. NSSC.
assign_firsts If set, tsh will assign who goes first (starts) in each game, and will never suggest that players draw to see who does so. It’s always a good idea to use this option, to protect players from error and fraud.
no_ranked_pairings If set, prevents ranked pairings reports from being generated. You might want to use this, if you only want alphabetical pairings and don't like cluttered directories on your disk.
no_text_files If set, prevents “.doc” files from being generated. You might want to use this, if you don't like cluttered directories on your disk.
player_photos If set, displays a photo of each player’s opponent, where one is available. You should use this, if photos and a good printer are available.
track_firsts If set, tsh will keep track of who goes first (starts) or goes second (replies) in each game, and display this information in pairings reports, suggesting that they draw tiles if it doesn not know who should start. It’s always a good idea to use this option.

You may also use the “ShowManyPairings r1-r2 division” command to produce pairings reports for multiple rounds, similar to those used at the U.S. Open. This is particularly appropriate when you are pairing many rounds at a time, as for example in a round-robin tournament.

Standings and Ratings Estimates

The “RATings division” command shows current standings with estimates of new (Elo/NSA, Elo/NSA-LCT or ABSP depending on the values of “config rating_system” and “config division_rating_system” ) player ratings. “rat a” will tell you what Division A ratings would be if the tournament ended right now. If the previous round’s results are available when this command is used, an extra column will show who went first against whom and the game score unless “config no_show_last = 1” was specified If the next round pairings are available when this command is used, an extra column will show each player’s next opponent. You should use this command when all the scores are in for a round, and print its report. Files are created as with pairings.

You can show standings from earlier rounds using the “RoundRATings round division” command. Entering “rrat 3 c” will give you the standings as of round 3 for division C.

The now deprecated “STandings division” command does what the “RATings” command does, but without the ratings estimates, and is kept largely for use at nonrated events. Entering “st c” will give you the current standings for Division C. Files are created as with pairings. You can show standings from earlier rounds using the “RoundStandings round division” command. Entering “rs 4 d” will give you the standings as of round 4 for division D.

If you used the “classes” configuration command, then the class to which each player belongs will be shown in standings and ratings reports.

If you are using the “team” extension field in your “.t” file, you can use the “TeamStandings division” command to list team standings.

If you have a spare computer or external monitor, you can use the “hook_addscore_flush” and “hook_autopair” configuration options to automatically trigger the “ScoreBoard” command, which can show players up-to-the-minute scores and pairings information and act as a virtual replacement for paper wall charts.

Ratings Data Submission

tsh creates ratings data files in three different formats, depending on which rating system you will be submitting your data to.

NSA Ratings

There are two ways to submit ratings data to the NSA. The much easier way is to connect to the Internet, then enter the “SUBMIT” command. In order to use this command, you must correctly set the configuration parameters “director_name”, “event_date”, “event_name”, “rating_system” and “ratings_note”. as in the following example:

# The first two lines identify your tournament for Joe Edley
config event_name = "Dallas, TX" 
config event_date = "March 7-9, 2008"
# The next line is in case there's anything else you need to tell him
config ratings_note = "Hi, Joe!"
# The next line is to tell him who to contact if there is a problem
config director_name = "Mary Rhoades"
# The last line is unnecessary if you have not overridden the default realm 
config rating_system = 'nsa'

If you cannot directly connect your tsh machine to the Internet, you can use the following older procedure. The NSA web site accepts tsh’s own “.t” files for ratings data submission, and Joe Edley prefers that one data file be submitted per tournament rather than one data file per division. There is a stopgap script that can be used at the shell prompt (in Unix) to create a combined submission file for a multidivisional tournament: “util/concat-t folder/*.t”, which creates a file called “all.t” from all “.t” files in the folder named “folder”.

ABSP Ratings

The “ABSPgrid” command generates a ratings grid for submission to the ABSP. The grid is a text file which is displayed on the screen and saved to a file.

AUPAIR Ratings

The “AUPAIR” command generates a “.TOU” file in the format used by the “AUPAIR.EXE” program. The file is not displayed on the screen. “AUPAIR.EXE” is used by Bob Jackman and his International SOWPODS Rating System, and by many countries in southeast Asia.

Prizes and Statistics

ThePRiZes” command generates a table listing all the prizes that you will be awarding, with the current leading candidate for each. To use it, you will need to add prize declarations to your configuration file, and you should print or preview a sample report after a dry run to check for completeness and correctness.

You can show standings based on a range of rounds using the “ResultsByRound firstround-lastround division” command. Entering “rbr 1-7 b” will give you the standings based on the first seven rounds for Division B. Files are created as with pairings.

The “HighWin count division”, “HighLoss count division”, “LowWin count division” and “LowLoss count division” commands list players who have excelled in each of those categories. For example, “hw 20 a” lists the top twenty game scores in division A, the rounds in which they took place, the losing score and the names of the players involved.

The “HighRoundWins roundrange division” and “HighRoundLosses roundrange division” commands list the players who have scored the highest wins or losses respectively in each round in a designated range. For example, “hrl 2-5 b” lists the high losing play in Division B in each round from Round 2 to Round 5.

The “AVErages division” commands lists average scores for all players in the given division. For example, “ave d” lists average scores for all players in division D.

The “TOTalScore division” commands lists total scores for all players in the given division. For example, “ave d” lists average scores for all players in division D.

The “STATisticS” commands lists summary statistics for each division in the tournament. For example, “stats” lists stats such as the minimum, mean, median and maximum rating in each division, the percentage of time the higher-rated or starting player won, etc. It also invokes most of the other commands in this section to update the web versions of the reports. Suggestions for additional statistics are very welcome.

There is a command for computing the NSA’s “Tuff Luck” prize based on the lowest total of six losing spreads: “tuff 6 a” lists the “Tuff Luck” standings for Division A. The opposite of this command is the “luckySTIFF” command, which lists players based on the sum of their closest winning spreads: “stiff 3 b” lists those players in Division B who have won three games by the smallest combined spread.

If you run a U.S.-style rotisserie pool, you can use the rotofile configuration option to specify the location of a text file giving the structure of that pool, then use the “ROTO” command to display current standings. Each team is represented by a list of names, followed by a blank line. The team owner’s name is preceded by the word “owner” and a space, each team member’s name is preceded by the word “player” and a space.

If you run a U.K.-style rotisserie pool, you can use the spitfile configuration option to specify the location of a text file giving the structure of that pool, then use the “SPITroast” command to display current standings. Each line in the text file consists of all the player numbers in the division in the order in which a team owner expects them to finish, a semicolon, the team owner’s name, a semicolon, and the team name. Team names must be unique.

TheUPSETs” command lists the top twenty ratings upsets: games in which a significant ratings underdog managed to win.

Checking Scorecards and Wall Charts

tsh includes commands for producing electronic versions of player scorecards and tournament wall charts. These were originally intended to allow you to check these documents and correct your data. As of 2005, the only official version of NSA tournament results is deemed to be the data that you entered from the result slips, so these commands should be used only to point out and explain errors in the printed documents, or to replace a lost scorecard at a player’s request.

You may wish to recheck your data entry in the middle of each round. To facilitate your doing so, the “CheckRoundScores round division” will list what has been entered for each game. Entering “crs 3 h” will list scores for Round 3 in Division H. A file called “H-scores-003.html” will be created, which can be printed and given to a checker to work offline with the result slips.

You can show a scorecard using the “ShowscoreCard division player” command. Entering “sc j 5” will give you the scorecard for player J5. A file called “J-scorecard.html” will be created, which can be printed and given to a player who has lost their original scorecard. Scorecards are also displayed whenever you use the “EditScores” command. When a score has been added to a scorecard within the last two hours, the age of that modification in minutes is shown at the top of the card. This is to help determine whether an absent player may be away taking a break from a game that ran unusually late.

You can generate an HTML file containing all scorecards for a division with the “ShowDivisionScoreCards division” command. Entering “sdsc a” will create a file called “A-scorecard.html” containing the scorecards for all players, which can be printed and given to players at the beginning of the tournament. This is particularly useful when most or all of the pairings are predetermined, as for example in a round robin schedule. Depending on the length of your tournament, you may need to edit the CSS stylesheet to make the scorecards fit nicely on each page.

You can show a wallchart using the “showWallChart division” command. Entering “wc g” will give you the wall chart for division G. Typing a round number before the division name will start the wall chart at that round, in case your wall chart would otherwise be too wide to print nicely. Files are created as with pairings; the HTML version includes much more information than can fit into the text or screen versions.

If you need a printed list of all the players with their player numbers and ratings, use the “ROSTERS” command.