|Coastal and Marine Geology Program|
SOFTWARE DOCUMENTATION - GSSTAT
Type: Main program
Purpose: This program will generate both method of moments and inclusive graphics statistics and extrapolate the fine fraction down to the clay/colloidal clay boundary (0.1 microns). The program is also useful for extrapolating grain-size distributions into portions of the clay fraction not detected during analysis by multi-channel particle-size analyzers (e.g. Coulter Counters, Elzones).
Operating System: Windows 95/98/ME/NT/2000/XP
Source Language: Microsoft Visual Basic version 6.0
Source Code: GSSTAT.VBP and associated forms
Program Category: Data processing
Input: A comma-delimited file in ASCII format that contains twenty fields including: sample identifier, latitude, longitude, and the frequency or cumulative frequency percentages of the whole-phi fractions from 11 phi through -5 phi. The first line of the input file must be a header record that lists the field attributes. The navigation fields may be left blank; the percentages of the phi classes supplied must total 100% (+/- 0.2%).
Output: A comma-delimited file in ASCII format that contains thirty-three fields including: sample identifier, latitude, longitude, %gravel, %sand, %silt, %clay, sediment classification, median, mean, standard deviation, skewness, kurtosis, verbal description, and the frequency or cumulative frequency percentages of the whole-phi fractions from 13 phi through -5 phi. If the user has selected inclusive graphics statistics, the verbal-description field will be populated. If the user has selected extrapolation, the two additional phi-fraction fields will be populated with data. The first line of the output file is a header that lists the field attributes. The sediment classification is based on work by Shepard (1954) and algorithms of Breslau (Schlee and Webster 1966). Phi notation is based on that of Krumbein (1934) and Inman (1952); method of moments statistics are based on equations of Krumbein and Pettijohn (1938) and Collias et al. (1963), and include the Shepard’s correction to the second and fourth moments (Kenny and Keeping, 1954); and the inclusive graphics statistics and verbal descriptions are based on the equations of Folk (1974). To prevent “overshoots” found in classic spline methods, curves for the inclusive graphics statistics were generated by constrained cubic spline interpolation (Kruger, 2003).
Usage: Upon successful installation, the program may be executed by simply selecting the program icon. Alternately, the program may be executed by selecting START, then RUN, and then typing the path and name of the program. The program opens a window that presents the user with several options that may be performed in any order. The users can 1.) select either method of moments or inclusive graphics statistics; 2.) select the method of extrapolation (either none, linear, exponential, or the average of these two); 3.) enter the smallest particle size actually measured (in microns); 4.) select the format of the phi-class percentages in the input file (i.e. frequency or cumulative frequency percent); and 5.) enter the format of the phi-class percentages in the output file (i.e. frequency or cumulative frequency percent). If “none” is selected as the method of extrapolation, then the program can simply be used to generate statistics for particle-size distributions, and entering the smallest particle size measured is not necessary. Linear extrapolation tends to slightly overestimate the amount of clay present in a typical distribution and may be used by operators to account for material within the colloidal fraction. Exponential extrapolation tends to slightly underestimate the amount of clay present in a typical distribution and may be used by operators who want data that represents the minimal amount of clay present. Although an operator may select linear extrapolation, exponential extrapolation, or the mean of both extrapolations, the mean usually provides the most accurate estimate and is, therefore, the recommended solution for most applications.
Errors may occur within the inclusive graphics statistics if any of the phi data fields contain greater than 90% of the distribution. In records where a phi data field contains greater than 90% of the distribution, the kurtosis value may be invalid; in the rare instance where a phi data field contains 100% of the distribution; all statistics for that record are invalid. If a distribution such as this exists in a data set, users should select “method of moments” statistics.
Selecting the “input file” button opens a selection window that allows the user to identify the file to be processed and to specify its location. The input file must be in comma delimited ASCII text (.txt or .csv) and have twenty fields that include: Sample Identifier, Latitude, Longitude, and the percentages (cumulative or frequency) of the 11 phi to -5 phi fractions. The latitude and longitude fields may be left blank (i.e., not omitted, but comma delimited), but the remaining fields must be populated, and the sum of the percentages of gravel, sand, silt, and clay must total 100% (+/- 0.2%). The program expects the first line of the input file to be a header showing the attribute names; no embedded commas are allowed in any of the data fields.
Selecting the “output file” button opens a selection window that allows the user to name the file to be generated and to specify the destination directory. The program will not run unless an output file is selected, nor will the program allow identical input and output file names in a given directory. If a file of the same name already exists in the destination directory, a window will open warning the user that the existing file will be replaced. If no destination directory is specified, C:\ is the default output directory. The program will generate an error message if the full path and names of the input and output files are not different.
Selecting the “Run” command button drives the program. The program generates the output file in the requested destination directory and allows the user to view input and brief diagnostic results in a display window to determine whether errors have occurred. The output file also has a header for its first line, but now contains thirty-three fields including: sample identifier, latitude, longitude, %gravel, %sand, %silt, %clay, sediment classification, median, mean, standard deviation, skewness, kurtosis, verbal description, and the frequency or cumulative frequency percentages of the whole-phi fractions from 13 phi through -5 phi. If the user has selected inclusive graphics statistics, the verbal-description field will be populated. If the user has selected extrapolation, the two additional phi-fraction fields will be populated. The new fields in the records are inserted between the navigation fields and those fields for the phi percentages.
Selecting the “Reset-Restart” button clears the input and output file selections and restarts the program. Selecting the “Information” button allows the user to view the documentation, and 5 schematics including: a correlation chart of the phi classes with the Wentworth (1922) grade scale, equations for methods of moments statistics with graphical representations, equations for inclusive graphics statistics with verbal descriptions, extrapolation options (none, linear, exponential, and averaged), and the Shepard (1954) classification scheme.
Selecting “Close” exits the program and closes the window. On systems with no mouse, the user can hold down the “Alt” button and press the underlined character of the desired function. Holding down the “Alt” button and pressing the F4 key will close the foremost window. Successful completion of a required option changes the color of the button. When all required options are completed successfully the “Run” button will turn yellow. After selection, the yellow “Run” button will turn red when data processing is complete.
Diagnostics: The program GSSTAT will generate error messages when necessary if problems associated with input file format, required parameters, or data content are encountered. Most of the error messages appear in a new drop-down window (i.e. Message Box); some warnings appear in the list view screen of the main program window. Examples of the most common error messages include:
You have already converted this file. Do you really want to run again? – This error appears when the user selects the “Run” button twice without restarting the program.
Setup Parameter Missing - can not run. – This message appears when the user has not selected or entered all of the required parameters (e.g. not selected an input file). To avoid this error, users must ensure that all yellow boxes have turned green.
Smallest Measured Diameter is too small. The program is expecting a size of 0.1 microns, or greater. – This message is displayed when the user has selected extrapolation and a smallest measured size less than the size to which the program will extrapolate (the colloidal-clay boundary).
You have selected extrapolation from above 2 microns. A significant portion of the grain size distribution will be extrapolated. This may cause your statistics to be invalid. – This error message appears when the user enters a Smallest Measured Diameter greater than 2 microns. The user is warned, but the program will continue.
A large error occurred while examining the input record. This may be due to incorrect input file format, F% vs CF%. Click OK to mark the record bad and continue, or Cancel to return to the setup screen and change the file format button, then restart. – This error appears when the cumulative frequency percent is off by more than 10% (>110% or <90%). The user has the option to tag the record or abort the program. The message in this window also specifically warns the user to check the format of the input file to insure that the cumulative frequency percent versus frequency percent option is properly set. Blank records or records with unpopulated grain-size data fields in the input file will also cause this error message to be generated. If the user continues, the message “ERROR CFP Not 100” i3s placed in the 34th field of the associated output record.
Aborted Run - If the user terminates the program before normal completion of a run, the final record of the output file will include the message “User ABORTED this data run.”
CFP is not 100 +/- 0.2 – This message is displayed when the percentages of the various size fractions do not total 100% (+/‑ 0.2%). The program will continue, but an error message will appear in the 34th field and in the list view screen of the main program window.
The input file you have specified does not exist at this location. – This message appears if the user selects the wrong input file name or path.
WARNING: The output file you have specified already exists! The file will be overwritten if the name is not changed. – This message is displayed when the user has specified an output file that currently exists. Unless the user wants to overwrite the existing file, they should specify a unique filename.
WARNING: The first record of this input file is not properly formatted. It may be an output file. – This message is displayed if there are more than 20 fields in the input file.
WARNING: The first record of this input file is not properly formatted. – This message appear3s if there are less than 20 fields in the input file header.
A required field was missing while examining this input record. – This message will be displayed if there are less than 20 fields in the current data record of the file being read. If the user elects to continue, the message “ERROR Input missing a field” is generated in the 34th field of the output file for that record.
A non-numeric character was found in one or more of these input fields. – This message is displayed if one of more phi fields in a given record contains non-numeric characters such as an alpha “O” instead of numeric zero, or an alpha “L” instead of a one. If the user elects to continue, the message “ERROR Non-Numeric Character” will be appended to the 34th field in that record of the output file. Users are strongly encouraged to validate their data prior to running the software to ensure that no non-numeric characters are present in the phi data fields.
The Input and Output Filenames cannot be identical. – This message is displayed if the user has entered the same file names and paths for both input and output files.
ERROR # N Has occurred. Procedure halted abnormally. – This error is displayed if the program crashes and lets the user at least take a look at the last data read/written for troubleshooting purposes. (N is a VB trappable error code number). The message is written to the output file, and the disk files are closed so that converted records are not lost or corrupted. Below are a few of the more common trappable error codes (Visual Basic 6.0). A more complete list can be found at http://www.halfile.com/vb.html.
3 Return without
Disclaimer: Although this program has been used by the U.S. Geological Survey (USGS) and Eliason Data Services no warranty is expressed or implied.
Author: A. Eliason
Eliason Data Services
230 Meetinghouse Road
Mashpee, MA 02649
Maintenance: L. Poppe
U.S. Geological Survey
384 Woods Hole Road
Woods Hole, MA 02543
(508) 548-8700 x2314
Collias, E.E., Rona, M.R., McManus, D.A., and Creager, J.S., 1963, Machine processing of geological data. University of Washington Technical Report Number 87, 119p.
Folk, R.L., 1974, Petrology of sedimentary rocks, Hemphill Publishing Co., Austin, Texas, 182pp.
Inman, D.L., 1952, Measures for describing size of sediments. Journal of Sedimentary Petrology 19(2), 125-145.
Kenney, J.F., and Keeping, E.S., 1954, Mathematics of statistics, part one. Princeton, New Jersey, D. Van Nostrand Company, Inc., 348pp.
Kruger, C.J.C., 2003, Constrained Cubic Spline Interpolation. http://www.korf.co.uk/spline.pdf
Krumbein, W.C., 1934, Size frequency distribution of sediments. Journal of Sedimentary Petrology (4), 65-77.
Krumbein, W.C., and Pettijohn, F.J., 1938, Manual of Sedimentary Petrography, Appleton-Century-Crofts, New York, 549p.
Schlee, J., and Webster, J., 1967, A computer program for grain-size data: Sedimentology 8(1), 45-54.
Shepard, F.P., 1954, Nomenclature based on Sand-Silt-Clay ratios. Journal of Sedimentary Petrology 24 (3), 151-158.
Wentworth, C.K., 1922, A scale of grade and class terms for clastic sediments. Journal of Geology 30, 377-392.