Counter: A program for automating faunal census

Name	Last modified	Size

Parent Directory		-
dos/	08-Feb-2006 16:10	-
mac/	08-Feb-2006 16:10	-
unix/	08-Feb-2006 16:10	-

Counter user's guide

User's Guide

by Peter N. Schweitzer

Introduction

Counter is a program to tally numerous items, with the goal of determining the numerical composition, by category, of a sample of objects. In geological applications, the sample is typically sediment, the categories are typically fossil taxa, and the objective is to carry out a faunal or floral census of the sample. Counter allows a microcomputer or terminal to replace mechanical counters, which are now more expensive than microcomputers.

Counter is distributed freely, with all source and executable code. Specific versions are supplied for MS-DOS, Macintosh, and Unix computers.

Getting in:

The user should compose a configuration file containing information such as the names of the categories, which keystrokes will be entered to count each taxa, how many objects should be counted overall, and so forth. The configuration file is ASCII text, and its format is described below. The user then invokes Counter through the command line for DOS and Unix versions or by double-clicking its icon on the Mac. If the configuration file could not be found, counter will prompt the user for the proper file specification.

The MS-DOS version permits the user to specify the foreground and background colors of the main screen, the status line, and the overscan area.

Getting out:

MS-DOS and Unix users should press Escape to exit. Macintosh users can either click the window's close box, select Quit from the File menu, or press Command-Q.

If the number of objects counted is less than the user-specified limit but more than zero, Counter will, by default, write a binary file containing the incomplete census data, and at the next invocation, will resume counting the same sample. MS-DOS and Unix users are given the choice of discarding the counts, saving to continue later, or writing the incomplete results as though the preset limit had been already reached.

Configuration:

The configuration file is a simple ASCII text file. Characteristics affecting Counter's behavior are specified by giving a keyword followed by one or more spaces or tabs followed by a numerical value. For example, to indicate that 40 objects should be counted, the configuration file should contain the line

count 40

This syntax is used for the following keywords:

count: The number following count is the maximum number of specimens of all types that can be entered. When this limit is reached, the tallies are written to an output file. Counter prompts the user for the output file name when the limit is reached.
warn: The number following warn indicates the total at which a bell or beep should be generated. Typically this is slightly less than the count limit, to indicate to the user that the sample is nearly complete.
columns: This indicates that the taxa should be displayed in columns; the number given is the number of columns that will be shown. On the MS-DOS and Unix versions, no more than four columns will be displayed.

Key configuration

Each taxon is assigned a key, and when the key is struck, the count for that taxon is incremented. Additionally, each taxon may be assigned a weight indicating how many individuals of that taxon are required to raise the total count by one. This allows Counter to deal sensibly with specimen fragments, since the user may regard the occurrence of part of a specimen as less important than the occurrence of a whole specimen. A weight may be zero. In that case, the number of specimens of that type is maintained and recorded, but does not affect progress toward the limit.

The syntax for specifying taxa is as follows:

key character [number] text

character: is any printable character that you can enter at the keyboard
number: is a single numeral, and may be omitted, in which case 1 is the weight
text: is the name of the category or taxon. If the weight is omitted, the taxon name cannot begin with a numeral.

Examples:

key t Globorotalia truncatulinoides

Whenever t is struck, the count for Globorotalia truncatulinoides will be incremented, and since the weight is implicitly 1, the total count will also be increased by one.

key k 2 Keel of menardii

The user presses k whenever the keel of menardii is encountered. In calculating the total number of specimens counted, the number of menardii keels is divided by two.

key ` 0 holothurian sclerite

The user presses the right-quote (or accent grave) key to indicate the presence of a holothurian sclerite. The number of holothurian sclerites will be recorded, but will not count towards the limit.

Default configuration file name

All versions of Counter expect a configuration file to reside in the same directory as the application and to be named counter.cfg. If no such file exists, Counter will ask the user to supply an appropriate file specification. Users of MS-DOS and Unix versions may override the default configuration file by specifying a file name on the command line.

MS-DOS color options

The following command-line options apply to the MS-DOS version only. Each option takes a numerical argument indicating the appropriate color, which can range from 0 through 15. There should be no spaces between the option and its numerical argument.

-bcn: sets the screen border color to n. The default value is 1.
-tfn: sets the text foreground color to n. The default value is 15
-tbn: sets the text background color to n. The default value is 1.
-sfn: sets the status-line foreground color to n. The default value is 14.
-sbn: sets the status-line background color to n. The default value is 1.

MS-DOS screen colors typically correspond to the following table:

     0      black
     1      blue
     2      green
     3      cyan
     4      red
     5      magenta
     6      brown
     7      light gray
     8      dark grey
     9      bright blue
    10      bright green
    11      bright cyan
    12      bright red
    13      bright magenta
    14      bright yellow
    15      bright white

Output file format

When the count limit is reached, the user is prompted for the name of the output file. If the file already exists, the new results are appended to it. Each sample is given as a single line in the output file, with the sample ID first, followed by the taxon counts, in sequence, separated by tab characters. When the output file is created, the taxon names are written to it as a single line, also separated by tabs. The resulting output file can be imported into spreadsheet programs; the taxon names will be the column headings, and the sample IDs will be the row headings. On the Macintosh, the output file is of type TEXT and creator XCEL. If you double-click it and Microsoft Excel can be found on your system, Excel will read the file.

When the counting is interrupted (i.e. when the user exits the program without having counted up to the limit), a binary file is created. If Counter finds such a binary file when it is launched, it reads both the configuration and the sample data directly from the binary file. On MS- DOS and Unix systems, the binary file is called counting.dat. On the Macintosh, it is called Interrupted sample. Details of the contents of the binary file can be determined by examining Counter's source code.

Programmer's guide

Design:

Counter is designed to be simple to operate and convenient to use and configure. Its development was prompted by specific user requests.

Compilation:

Counter was written using Standard C wherever possible. The user interface code deviates from the standard, of course, and the Unix function access is used to determine whether specific files exist and can be read. The Macintosh version was written using THINK C version 5.0.4, with calls to the Mac toolbox. The MS-DOS version was written using Turbo C 2.01, and calls some assembly-language routines to write directly into the display memory of the PC. Turbo Assembler 2.0 was used to convert the assembly language into object code. The Unix version was developed on a Data General AViiON system with the supplied GNU C compiler. It uses the curses library, and can be run using alphanumeric terminals.

Counter permits up to 128 taxa to be counted at present. To enlarge this number, change the definition of the symbol MAX_TAXA in counter.c.

The Macintosh resources can be modified using ResEdit. In particular, the default size, shape, and position of the window can be usefully modified.

Needed enhancements:

Permit the program to display color on Macintosh and Unix.
Accept non-printing keystrokes like function keys in the configuration file. This is currently working in the MS-DOS version, where the following syntax is permitted:
```
xkey number  weight  taxon
```
In this form, number is a negative integer. Function keys and other special keys do not generate character codes; Counter negates the scan code of such a key and uses the result to find out which taxon's count should be incremented. In the current implementation, the xkey configuration is usable only if number is negative.

How to get Counter

Counter can be obtained via anonymous ftp from geochange.er.usgs.gov in the directory /pub/tools/counter. Bugs and suggestions should be reported to the technical contact (below). Remember that unimplemented features are not bugs.

Technical contact:

    Peter N. Schweitzer
    MS 955, National Center
    U.S. Geological Survey
    Reston, VA 22092

    Tel: (703) 648-6533
    FAX: (703) 648-6647
    email: pschweitzer@usgs.gov