USSA Alpine Masters Race Scoring Tool – User’s Guide
Author: Deborah Lewis
Date:
The Race Scoring Tool is the primary tool that you use to organize and process race results data. This tool allows you to specify the competitions in race series, load the results data from each competition, and generate race standings reports.
Specialized tools for scoring combined events and season standings are launched from the Race Scoring Tool. The various tools for series scoring are discussed in the Series Scoring User’s Guide.
Basic Concepts
When you run the scoring software, the main tool that is launched is the Race Scoring Tool. The RST is where you define the events in a race series, load race results, generate race standings reports, and launch specialized scoring tools for combined event or season standings scoring.
Races and Race Series
A race represents an alpine ski competition in a particular discipline (SL, GS, SG, DH), held at a specific location on a specific date. The results data for a race is loaded from a file, usually obtained by exporting the data from the race organizer’s timing data system. However, it is also possible to obtain a timing data file by a variety of other means if necessary (e.g., exporting from a spreadsheet, editing a print report into a loadable format, or even by creating by hand in a text editor if necessary). Race standings reports are generated in a variety of organizations that are relevant to masters age class competition (ranked within class, by gender, by all racers).
A race series is a series of individual races which collectively form an interesting grouping for the purposes of results reporting and scoring. A race series generally consists of races held in the same competition season, either for a specific event at a single site (such as a regional or national championship event) or for the scheduled season events (such as the season schedule for a division).
File Management
The Masters Race Scoring Tools are installed in a directory on your hard drive, referred to as the scoring tools installation directory. The installation directory contains the software, documentation, configuration files which allow you to customize the scoring tools, and the data files for race and scoring results.
The RaceData subdirectory contains the data files. Each race series that you create is managed in a separate subdirectory under the RaceData directory, with the race series name that you specified used as the directory name. Within a race series directory is stored the specification files which track the races in the series, the Results data files with the results data, and Reports files with standings reports that are generated by the scoring software.
To back up or exchange race data, work with the contents of the RaceData directory, either as a whole or for a specific race series data directory.
You should generally work with the race series data files using the facilities provided in the scoring tools. However, you may occasionally wish to work directly with the underlying files. The backing file formats have all been designed so that they can be worked with in text format if necessary. You can use standard file system and text editing tools to work with the underlying data files.
Caution: If you edit the
underlying data files directly, be sure that you are not running the scoring software
tools at the same time. And make sure
you know what you’re doing…
Creating a Race Series
When you run the Race Scoring Tool, it opens on the race series you were last working with in the tool. The name of the race series and the RaceData directory in which the series data is stored are displayed at the top of the window. The events in the series calendar are listed in the series results pane, along with the availability status of the results for each event on the calendar.
You can:
- continue working with the current race series
- switch to a different race series
- create a new race series
Within a race series, you can:
Switching between Race Series
To switch between different race series, use the Open… command in the File menu. The Open Race Series dialog presents a list of all race series that you have created – simply select the series that you want to work on and press OK.
Creating a New Race Series
You create a new race series using the New… command in the File menu. As shown in Figure 1, the New Race Series dialog allows you to specify the name and properties of the race series.
Figure
1. Creating a Race Series
The properties of a race series are:
Race Series – the name of the series. This should be a reasonably succinct but descriptive name by which you refer to this series.
Directory Name – the name of the file system directory under your tools installation RaceData directory in which the race series files will be stored. This should usually be a modified version of the descriptive name you have specified, e.g., drop out spaces and make sure there are no special characters that the file system doesn’t allow in directory names.
Organizer – the race series organizer. This is usually either a USSA masters division or USSA itself, for national events. [Umm…. where is this information used??!]
Classes – the
default age class system used in series races.
The NationalClasses system is
the standard 5-year USSA masters age classes.
Division age classes systems may use different age class groupings
(e.g., 10-year
Courses – the default convention for the number of courses and allocation of age classes onto multiple courses that is used for the events of this race series. The default course arrangement that you specify here can be overridden when specific race results are imported. Used when generating race results reports and for combined/series scoring to determine which groupings make sense.
Series type - [umm, not really used for anything useful at the moment, it may go away….]
Start year – the start year of the competition season for this race series. Used when computing competitor ages from birthdate information.
Defining the Series Calendar
Within a race series, you edit the race calendar to create entries for each event in the series. In general, each race that you define on the calendar represents a competition in a specific discipline, held at one location on a particular date.
You create a new race using the New… command in the Race menu. As shown in Figure 2, the New Race dialog allows you to add an event to the series calendar.
Figure2.
Creating a Race Entry in a Series
The required properties of a race identifier are:
Date – the date on which the competition is held
Location – the site at which the competition is held
Event – the discipline (SL, GS, SG, DH)
Optionally, you can specify a Qualifier which modifies the race identification. Any qualifier that you add should be a short, descriptive annotation, as it is used to form the backing file names for files containing data and reports on this event. You must use a qualifier if you need to distinguish between multiple events of the same type held on the same day (e.g., two DH’s run on the same day). You must also use a qualifier if you are splitting or merging race results from the same event to support different arrangements of the data for scoring purposes. You might wish to use a qualifier as a reminder to mark unusual events on the series calendar (e.g., visibly distinguish Unscored or Makeup races on a season schedule).
The composition of the < date, location, discipline [,qualifier] > must be unique within the race series. It is used to form identifiers for races in the series and in the names of the backing files in which race results and reports are stored.
You can edit the race definition for a scheduled event by selecting the event in the race series list and invoking the Edit command in the Race menu. You can also double-click the event in the list to open the Edit Race dialog. This is typically done when the discipline has been changed (e.g., a GS was turned into a SL or a two-run technical event was held as a 1-run event due to adverse weather conditions). Note: The event definition can only be edited before results data is loaded.
To remove an event from the series calendar, select the
event and invoke the Delete command
in the Race menu.
Processing Race Results Data
The Race and Report menus in the Race Scoring Tool provide operations which allow you to load timing system results data into the scoring software and generate race standings reports. The results data can also be edited if it is necessary to make corrections to the race results.
In order to work with race data in the scoring software, you must import the results data from the race timing system into the standard results data representation that is used for generating race standings reports and for computing multi-event scoring standings. As described in more detail in Timing Data File Formats, race results data can be imported into the scoring software from timing system data in either the standard USSA SkiData format or in a CSV (comma-separated values) text format containing the values needed to determine the competitor results for the event.
When working with race results data, you can:
- import timing system results data
- edit loaded race results data
- generate and view race standings reports
- mrege and split race results
Loading Race Results Data
To import the results for a race, select the race entry in the series events list of the Race Scoring Tool and invoke the Load Results… operation in the Race menu command. As shown in Figure 3, the Load Race Results tool is opened to allow you to specify the location of the timing data file from which the results data is to be loaded, along with other properties about the race data that are needed to properly import and interpret the raw timing system data.
Figure3.
Loading Race Results Data (CSV timing data format)
The top section of the results import tool contains the specification parameters for the race data that is being imported. The race identification (date, location, discipline, and optional descriptive qualifier) is determined by the series calendar that you defined in the main Race Scoring Tool. The Classes and Courses values describe the properties of the race operation. The initially selected values are determined by the default values you specified when you created the race series. The Classes value defines the age class system used for this race, while the Courses value is used to characterize whether the competitors in the race results data competed on a single or on more than one course.
The bottom section of the results import tool contains items which allow you to specify the location of the timing system data file(s) to be imported, along with the column order specification for a CSV format file and an optional StartGroupCode mapping which provides supplemental information for determining the class of the competitors. (See the Timing Data File Formats document for a detailed discussion of the CSV column specifications and the StartGroupCode mechanism.)
First, use the file browser button labeled … (to the right of the Input File(s) item) to select the timing data file to be imported. In some cases when importing CSV format data, the timing data may be split into multiple files (e.g., one file containing the men’s results and a second containing the women’s results) – in this case, you can select multiple files to be imported. After you have set the timing data file location, the contents of the raw timing data being imported is displayed in the Timing Data text pane.
If you are importing a SkiData file, the Column Order list is updated to display the field order of values in a SkiData competitor entry line – this helps you determine which field to update if you need to correct a competitor entry in order to successfully perform the import operation. If you want the timing data loader to attempt to resolve a StartGroupCode value in the nationality/team field to determine the competitor’s class, enable the Start Group Codes check box and use the … browse button to select the start-group-to-class mappings to use for this import operation.
If you are importing CSV format timing data, you must review the column order specification in the Column Order list to ensure that the order of the data you are loading is correctly specified. If the default column order is not appropriate for the file you are importing, a … browse button is provided which allows you to select an alternative column order specification from the predefined set of likely orders.
The CSV column order specifications and the StartGroupCode mapping specifications are both defined by configuration files stored in the ConfigurationSettings directory of your scoring software installation directory. The configuration files are simple text-based definition files which you can copy and modify if the built-in set of specifications does not include a choice which describes your timing data file. If there is no column order specification that accurately describes the field order in your timing data file, simply create a new specification by adding a suitable file to the RaceResultsImportColumnSpecs subdirectory of the ConfigurationSettings directory. If there is no start group mapping specification that accurately describes the coding scheme used in your timing data file, simply create a new specification by adding a suitable file to the StartGroupCodeSpecs subdirectory of the ConfigurationSettings directory.
When you have indicated the location of the timing data and set the race specification and import properties suitably, press the Import button to load the results data. If the import engine is able to obtain the values necessary to load the raw timing system data into the scoring system, the race results data is loaded and the race results reports are automatically generated. Use the Report menu operations in the Race Scoring Tool to view to the race standings reports in the various standard organizations that are appropriate for the Classes and Courses used in this race (e.g., positions by class, by gender, by all competitors on the course).
If there is a problem which prevents the race results data from being loading, a message describing the problem is displayed. Where possible, the line containing the problem is selected so that you can review and if possible correct the problem. Typically, a data import problem involves being unable to determine the gender or class of the competitor, which can frequently be corrected by providing a suitable class code or birthdate value in the competitor entry. Missing, invalid, or duplicate bib numbers also are considered to be serious problems which must be corrected in order to import the timing system data into the scoring system. Where possible, correct the problem entry and re-try the Import operation. For pervasive problems, you may need to resort to techniques such as the CSV format _SetDefault mechanism to supply missing gender or class values for sequences of competitor entries. If it’s not clear how to resolve the problem easily, give up temporarily while you reconsider the whole mess and decide how best to proceed.
Editing Loaded Results Data
It is occasionally necessary to edit the race results data after it has been loaded into the scoring software. This is primarily useful for correcting a racer’s class, such as when an open/elite class competitor was not indicated in the original timing system data or to correct an age class which was incorrectly coded in the timing system data.
To open the Race Result Editor, select the race whose data you wish to inspect in the series events list of the Race Scoring Tool and invoke the Edit Results operation in the Race menu. (Or just double-click on the race entry.)
The result editor displays the race specification and the result entries for each competitor in the race. You can correct the Courses arrangement in the race specification or edit individual competitor entries. If you have made changes, use the Save button to save the changes and regenerate the race standings reports.
Note: The result editor does not currently support
correcting a result time for a competitor.
If you need to correct a racer’s time or finish status, close the
scoring tools and edit the race result data using any text editor. Need we remind you to do this carefully?! Then re-launch the scoring tool and use the
Generate Reports operation to regenerate the race standings reports with the
modified race data.
Working with Race Results Reports
Race standings can be computed in a number of groupings (e.g., by finish position within class, by finish position within all racers of the same gender, by finish position across all competitors on the course). The standings groups which can be computed for a race are determined by the age classes used in the race and the course arrangement (e.g., all racers on a single course vs. multiple courses for different segments of the competitors).
Standings by class can always be computed. Overall standings across all competitors can only be computed when all competitors raced on the same course. Standings by gender can be computed if all competitors raced on the same course or there were separate course split by men/women. Standings by national group can only be computed when the standard 5-year national classes are used; it is not supported for division age class systems with different age class age ranges or ability class groups (the open/elite/super seed classes).
Race standings reports are generated in a very simple text format (e.g., suitable for pasting into a results article in a newsletter) and in HTML format for publishing on a web site. The HTML format makes it very easy to publish race results on the internet – just copy the relevant report files onto your web site and update the master race results page to add suitable links.
Race results reports can be viewed using the Report menu operations in the Race Scoring Tool or by browsing the RaceReports subdirectory of the race series storage directory under the RaceData directory of the scoring software installation.
Merging and Splitting Race Results
You may occasionally find that you wish to merge the results of two races into a singe “logical” race or to split the results of a race into subsets of the racers. Merge situations tend to happen when multiple courses are set for different segments of the competitors and separate race timing files are created for the “segments” of the race. Merging is usually done to support presenting a unified race result report, while splitting is a technique that may be useful for combined scoring.
The basic technique when merging or splitting is to create the new race entry in the series calendar and to load its results using the previously loaded result data of the race segments being merged or the master race that you wish to split into subsets. Race results data files are stored in the RaceResults subdirectory of the race series directory in your RaceData folder. The data for each race is stored in a file whose name is formed from the { date, location, discipline [,qualifier] } race identifier. The race data file format is a simple text-based CSV format, consisting of a short header section with some overall information about the race followed by the competitor entries. To merge or split a previously loaded race, invoke the Load Results operation to launch the Load Race Result tool and select the corresponding race data file(s) from the race series RaceResults directory as the timing data files to be loaded The standard column order specification for internal race results files is automatically installed for you, and racer classes have already been resolved, so you should not have to be concerned with supplying either column order or StartGroupCode mapping specifications. Remove the header lines or comment them out by inserting a # as the first character in the line. If splitting an existing race, delete the entries for the racers that you do not want to include in the subset race you are splitting out. Then Import as usual.
Tips and Troubleshooting
This section provides information and suggestion for dealing with a variety of issues that you may encounter while using the scoring software.
- Getting a Timing Data File to Import
- Dealing with Timing Data Import Problems
- Customizing and Extending the Tools
Getting a Timing Data
File to Import
A fundamental premise of the race scoring tools is that once timing data has been recorded in a computer, you should not have to manually reenter it. That basic assumption underpins the standard work flow when using the race scoring tools, where you simply import a results data file into the scoring software in order to load the results for a race.
Because most alpine ski race organizers nowadays use electronic timing systems run by timing software programs when they run a race, it should usually be possible to obtain a timing data file directly from the race organizer. Although the detailed steps depend on the specific timing program which was used for the race timing, the usual procedure is to export the results data as either a USSA SkiData format file (just as is done when the organizer submits the results of a scored race to USSA for inclusion in the national points system) or alternatively as a CSV text file if such an export format is supported.
If the race organizer is using the standard USSA timing software from Split Second, you may wish to get a copy of the actual binary race data file (the .alp file) in addition to or instead of an exported results file. Through an agreement with USSA, a “non-timing” version of the Split Second Alpine race timing software can be freely downloaded from the Split Second web site at www.splitsecond.com. The non-timing version of the software allows you to create, edit, and export race data, so from the .alp race data file you can decide whether you wish to use a SkiData export format or the CSV format .TMG timing data export from the Split Second software. Having this flexibility is sometimes useful, such as when the racer class coding conventions used by the race organizer do not follow the usual conventions.
In some cases, however, the race organizers do not have an automated race timing system or for some reason you are unable to obtain a data file from them. This is sad and moderately painful, but you still have options. Read on.
One case that sometimes occurs is that the race results data is only available in the form of a spreadsheet. Because most spreadsheet programs support the CSV text format for interchanging data, it should be possible to export the data from the spreadsheet into a CSV file. You can then import this file into the race scoring tool in the usual fashion, possibly with a customized column order specification needed if the data is arranged in an unusual order. (You may also need to use the _SetDefault mechanism to mark the section boundaries between age classes.) Unwanted entries such as header or descriptive lines can be pruned or commented out, using either a standard text editor on the CSV file or when you are working with the timing data in the import tool.
Another situation that sometimes occurs, although thankfully fairly rarely, is that the only form in which you can obtain the race results data is a print format text report. In this case, you will have to use a text editor to edit the file contents down to some usable form of CSV values. This generally entails removing header and footer text and editing each racer result entry in the report to convert all the formatting white space that is typically used into commas separating the actual field values of interest. This is tedious and somewhat error-prone, as your fingers occasionally munch more or less than was intended as you work through the text, but is still better than re-entering the data from scratch. Doublecheck your editing as you do this and review the loaded race report carefully when you are done to ensure that you haven’t inadvertently mangled the data during this manual editing process.
The final, desperate situation is that there is simply no data available other than a piece of paper with a race results report. This stinks and there’s nothing you can do at this point other than fire up a text editor or spreadsheet and manually enter the data so you can get it into a CSV format that can be loaded into the scoring software.
Dealing with Timing Data Import Problems
--####TO DO: The most
common problem that is encountered when importing a timing system data file
into the scoring software is difficulties with the data and encoding
conventions used to determine the racer’s class. Approaches for dealing with this include
manually editing the timing data, using the _SetDefault mechanism to mark sections of entries in a CSV file, or
using the StartGroupCode mechanism
to supply or augment the age class codes in the data file. Most of this is now discussed in the timing
data file format documentation and in the section in this document on loading
race results into the scoring tool. At some point, consider adding additional
discussion here if deemed necessary [DJL
--####TO DO: the
second most common problem that is encountered when importing a timing system
data file is missing, duplicate, or invalid bib numbers in competitor
entries. General approach is to simply
patch these cases in the import tool when they arise, perhaps using some
special range of bib numbers (e.g., 9990, 99991) to distinguish the patched
entries.
Customizing and Extending the Tools
Working with race data sometimes seems to be a never-ending series of bizarre new problems in how race organizers organize and code the timing data for a masters race. While some of this can be addressed by providing assistance to race organizers, such as suggesting conventions and techniques for them to use or by providing files and tools to set them up in a standard fashion, and some is addressed by continually making improvements in the scoring software as new situations arise, it seems that there’s always just one more thing that comes along to trip you up when you absolutely, positively just want to get the results reports published.
The scoring tools try to provide you with escapes and workarounds in a couple different ways so that you can cope with unexpected situations. First, the underlying file formats for the race and scoring data are all text-based files using fairly simple encoding conventions. This design approach to data storage allows you to go in manually with a text editor and work around fundamental problems in the scoring tools if you really need to and you know how to make the proper changes to the underlying files. This can be somewhat dangerous and you have to be careful, but it’s a nice escape hatch when you really need it.
**Important** Never edit
a file in the race series directory under your RaceData installation directory
while running the scoring tools. Always
close the tools first.
The second mechanism which is provided to allow you to resolve problems on your own is the use of user-editable configuration specifications and option settings which allow you to customize or extend the built-in capabilities of the scoring tools. The ConfigurationSettings subdirectory of the scoring software installation directory contains configuration files and user settings that can be modified or extended to customize the scoring tools.
If you encounter an encoding notation for racer class or result status that is not currently supported but which is used on a large number of entries such that you don’t want to manually edit all occurrences or if you expect to encounter this notation again in the future, you can update a synonym specification file in the ConfigurationSettings directory to define the mapping from the new value you have encountered to the standard encoding for the value.
You can also define new race locations for events in your
race series if the host area is not included in the built-in set of
locations. For each new location, add an
entry in the RaceLocations.cfg
configuration file which defines the short name of the location, a descriptive
name of the location, and the regional organization for the location. The short name should just be alphabetic
characters, with no spaces or punctuation – it is used to store values in race
data files and as a component in forming file names based on race
identifiers. The descriptive name is how
the location is presented when working with race data in the scoring tools - it
should also be fairly brief, but can include spaces or punctuation as
appropriate. For example, the location definition for
As discussed in the section on loading race results data, the options for providing column order specification for loading CSV data and the StartGroupCode mapping specification used for supplementary racer class encoding values are both provided by specification files in the ConfigurationSettings directory. The column order specifications are stored in the RaceResultsImportColumnSpecs subdirectory, while the start group mapping specifications are stored in the StartGroupCodeSpecs subdirectory. If you find you need a column order or start code mapping which is not described by any of the built-in specifications, make a copy of the specification file that is closest to what you need and use a text editor to modify the configuration file.
A column order specification file is simply a CSV format file with a single entry containing a list of column names. Columns containing significant data values must be identified by the reserved column name which identifies the column content, as described in Timing Data File Formats. Columns containing values which are not needed to load race results data can be given arbitrary names.
A start group code mapping specification consists of any
number of 2-value CSV entries. The first
value in each line must be the standard name of an age or ability class, while
the second value is the start group code used in the timing data to identify
that class. There must be at least one
entry for each racer class. You have
additional entries for a racer class if you want to allow alternate start group
notations. For example, the preferred
start group notation for the Far West men’s open class in NOP, but a start group code using the single letter N is also allowed – both sort the MOP class properly in the start order,
but the NOP notation is preferred
because it is more distinctive when working with race data files in the timing
software.
Contact Information
Director of Race Services and Scoring,
Email: djlewis@acm.org
Document History
Last update: