Preparing Reports with tsh

How to list standings, pairings and more using tsh.

Updated 2018-02-26T22:46:00+05 for tsh 3.340.

As part of your regular workflow 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: “EnhancedScoreBoard”. “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.) Use the “player_photo_aspect_ratio” configuration option if your photos are not square. Databases are currently available for NASPA 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. Using this command will also generate pages of tally slips preprinted with player information, if you want to cut and distribute them to players.

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_first_page_break Specifies how many rows of pairings to print on the first page of alpha pairings. Use this if you have an unusually tall header that appears at the top of your reports.
alpha_pair_page_break Specifies how many rows of pairings to print on each page of alpha pairings. Use this if you find that the default settings are causing the bottom rows of some pages to appear on their own on a separate sheet of paper.
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_index_tally_slips If set, prevents tally slip files from cluttering your web index. You might want to use this, if you don't like cluttered indices in your browser.
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.
numeric_pairing_display If set, sorts players numerically rather than alphabetically. You might want to use this, if you can’t read the language in which the player names are written.
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.
player_photo_aspect_ratio Specifies the width:height ratio of player photos, defaulting to 1. If your photo database consists of photos with a 3:4 ratio, set this to 0.75. If you are using player photos and your images are not square, you must use this to keep the photos from being stretched.
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/NASPA, Elo/NASPA-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. Specifying “config standings_refresh” will make the HTML versions of these reports refresh themselves in the browser. 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. Using the “RoundClassRATings round division” command instead will group players by class, then rank, rather than just rank.

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 need more precise control over which fields (columns) are shown in the rating and standings reports discussed above, you can list the fields you want using the “rating_fields” configuration option. If you do not, the following fields will be displayed.

Field NameDescription
rankCurrent rank in standings
wlWin-loss record. Not shown if no pairing system is in effect; i.e., for solo events.
scoresumSum of scores. Shown if the “sum_before_spread” configuration option is set.
spreadCumulative spread. Not shown if the “scores” configuration option is set to “'WL'” or “'WLT'”.
thaipointsThai handicapped game points: 2 for a win, 1 for a tie, 0 for a loss, plus handicap values. Shown if the “thai_points” configuration option is set.
oratPretournament rating. Shown in ratings reports, but not in standings reports.
nratEstimated current post-tournament rating. Shown in ratings reports, but not in standings reports.
dratEstimated current tournament rating change. Shown in ratings reports, but not in standings reports.
classClass. Shown if the division appears to have classes configured.
nameName. configured.
lastPrevious game outcome. Not shown if no pairing system is in effect; i.e., for solo events. Also not shown in the first round of an event, because there would be no previous game.
nextNext game pairing information. Not shown if the next round has not yet been paired.

If you are using the “team” extension field in your “.t” file, you can use the “TeamStandings division” command to list team standings. If your teams are competing based on their aggregate performance across all divisions, you should use the “TotalTeamStandings” command.

(Deprecated) 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.

TheEnhancedScoreBoard” command generates a display that is superficially similar to the now deprecated “ScoreBoard” command’s display, but differs substantially in its implementation and features. To use it, you must currently run the command once from the command line at the beginning of your event. This sets up a web page for your players, containing AJAX code that periodically fetches tournament results from your web server. (Note that to use this command, you must be serving your web pages from a web server, not just straight from your file system as is possible with many operating systems.) You should use the “hook_addscore_flush” and “hook_autopair” configuration options to trigger the “saveJSON” command, which saves a division's entire state in a form that can be read by the enhanced scoreboard. The main advantages of using the enhanced scoreboard are that there is less load on the web server, and users can browse the history of the tournament round by round, even after the event is over. You can also use it with the “setESBMeSsaGe” command to display announcements for players. Use the “config esb_geometry” configuration option to specify default numbers of rows, columns, and rank offset for each enhanced scoreboard.

Ratings Data Submission

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

NASPA Ratings

There are two ways to submit ratings data to the NASPA. 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_id”, and “tournament_id” as in the following example:

# This line gives your NASPA ID
config director_id = "CM000003"
# This line gives your NASPA tournament number
# (use the LISTT command or ask John Chew if you don't know how to get it)
config tournament_id = 123

If you cannot directly connect your tsh machine to the Internet, try running the “SUBMIT” command anyway. This will create a file called “all.tsh” in your event directory, which you may upload through the Member services section of the NASPA website.

Use the “config ratings_note” configuration option if you want to include a note about the event for the rating officer. Use the “director_name” and “event_name” configuration options to include the director’s and event’s names for the historical record.

ABSP Ratings

The “ABSPgrid” command generates a ratings grid for submission to the ABSP. The grid will be saved as a text file called “abspgrid.doc” in your event directory.

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 WESPA 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”, “HighCombined count division”, “HighSpread count division”, “LowWin count division”, “LowLoss count division”, “LowCombined count division” and “LowSpread 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 “AverageOpponentScores division” commands lists average scores for all players in the given division. For example, “aos c” lists average opponent scores for all players in division C.

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 NASPA’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.

TheCOMMentary” command creates textual commentary about what happened in a given round in a division in subdirectories of the directory specified by “config commentary_directory”.

TheUPSETs” command lists the top twenty ratings upsets: games in which a significant ratings underdog managed to win. TheHighRatingChanges” command lists players whose rating has increased by the largest amount.

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/NASPA 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” or “showRankedWallChart division” commands. 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. By default, they'll be listed by rank, unless you specify the “config roster_order” configuration option.