Read Me file for SpikeCount.exe,
        Release v. 1.0 (2003-05-22).

Win32:  Windows 95, Windows NT 4.0, or later.

This program counts spikes (positive peaks) in an
ASCII data file, as from a sound recording.

Install SpikeCount by unZIPing the release file to
any convenient directory.

You should see:
   ReadMe.txt      . . .   12,170 bytes
   sample.txt      . . .  581,253 bytes
   sample.wav      . . .  101,722 bytes
   samp200.txt     . . .  564,172 bytes
   SpikeCount.exe  . . .  376,832 bytes
   
Drop the .exe into any folder to create an icon.

There are no known bugs.   Note the disclaimer
at the bottom of this ReadMe file.

---------------------------------------------------
Program Details:

SpikeCount may be invoked in any of three run modes:

1. GRAPHIC mode.  This is the default, with no switch
   on the invocation line.   In this mode, both a
   new text window (as in TEXT mode, below)
   and a graphic control panel are presented.
   The values of h and w, as well as file names,
   may be omitted from the invocation line.
   If both h and w appear, they will be used
   as defaults; file names always are ignored.

   A Help menu system is available in GRAPHIC
   mode.   The entire content of the help
   menu system is copied below to provide
   ReadMe documentation details.

   In addition to [Quit] and [Help] controls,
   editable fields are provided for interactive
   entry of the h and w parameters.   Files
   may be selected interactively via the
   [Select Files] button.

   In GRAPHIC mode, it is possible to check
   filenames and format without counting spikes
   by using the [Check] button.   This may save
   time when numerous files with uncertain format
   are available.
   
   The [Count] button initiates the same counting
   process as in TEXT mode, with the same output
   format (except initial Help screen) as in TEXT
   mode.

2. TEXT mode.   The switch, "-t", must appear
   somewhere on the invocation line.   The syntax is:

     % SpikeCount -t  h   w  fname1 [, fname2, ...]
   
   Here  h  is a percent height and  w  is a percent
   width; h and w are explained below.   Any number
   of file names may be listed, up to the OS limit or
   10,000 characters, whichever is less.  Each file
   name must end in .txt or .asc; it must begin with
   a header as described below and contain signed
   double data, one value per line.  Up to about
   25,000,000 data lines may appear in a file.

   The file name(s) on the invocation line are tested
   for correctness.   Then, a new text output window
   is created:  This window contains first a help
   screen and then a list of all valid file names.
   To proceed, hit the {RETURN} key (=CR) with the
   new window the active window; to abort without
   counting spikes, enter an 'x'.
  
   To proceed, the format of each file is checked.
   For files in correct format, spikes then are counted,
   and a one-line report is presented in the new
   text window for each file as follows:
  
   (filename): n.nn s (m.m ms) | N spikes => X/sec.
  
   In this report, the duration of the file is given
   first in seconds and milliseconds, as determined
   from time-scale information in the file header.
   The number of spikes N then is reported, followed
   by the average spike rate X in the file.

   Messages may be cut-and-pasted from the new text
   window to save them.

3. SILENT mode.   The switch, "-s", must appear
   somewhere on the invocation line.  In this mode,
   output messages are minimized, and no initial
   help screen is presented.   The count begins
   immediately on all files which have a valid name
   and internal format.   SILENT mode and TEXT
   mode otherwise are the same.

------------- Demonstration Example:

An ASCII audio file, sample.txt, is provided to
use with SpikeCount.  A copy in Windows PCM format
also is provided as sample.wav.  

The same file, normalized to 200% (as explained
below), is provided as samp200.txt.

Visual inspection of sample.txt in CoolEdit(R) or
a similar utility shows about 65 irregular spikes,
depending on ones criterion.

Invoking SpikeCount with default h and w parameters
of 50% and 10%, opening sample.txt, and running
[Count], yields a spike count of 53 spikes for
sample.txt and 65 for samp200.txt.

The advantage of over-normalization is evident with
these files and these parameters, but the user will
have to decide what to consider a spike before
settling on a good parameter set to use.   Once the
parameters have been decided according to the user's
criterion, they may be used to count spikes in any
file with similar characteristics.  

-----------------
Development Details:

SpikeCount was written in C++, using the Borland
BCC 5.01a Interactive Development Environment.
There were over 5000 lines of compiled code in
18 modules, including debugging routines but
not counting graphic resources.   Development
took 5 months of occasional effort, including
writing and revision of the SRS and preliminary
design documents.

============= GRAPHIC mode help menues: ========
Overview:
SpikeCount scans ASCII text files for spikes.   It reports
results to a newly created text window.

The input data are signed doubles, one per line, between
+1 and -1.   The files must have .txt or .asc extensions.

The file header is on exactly five lines, and the first
datum begins on the sixth line.   There must be no blank or
empty line, or nondata value, after the header.   The header
format is:  (keyword)(:)(tab)(value) as follows:
+-------------------------------------------
|SAMPLES:         (decimal integer > 999)
|BITSPERSAMPLE:   (decimal integer > 7)
|CHANNELS:        1
|SAMPLERATE:      (decimal integer > 5999)
|NORMALIZED:      TRUE
|(first signed-double datum)
| . . .

Syntax:  SpikeCount [-s|-t] h w filename1 [filename2 . . .]
  -s for silent (batch) mode; -t for text mode; none for
  the default graphical mode (in which filenames are ignored).

Spike height h and width w are in percent 0.0001..99.9999.
The percent w is of the longest inactive stretch T in the
file:  Positive peaks above about h for about w*T or more
time will be counted; thus the width threshold narrows to
detect narrower spikes if they are more numerous.  Glitches
to less than about h for less than 1/10 w*T are ignored.
SAMPLES = number of data in the file; SAMPLERATE = data/s;
BITSPERSAMPLE (resolution) is checked but not used;
CHANNELS and NORMALIZED must be '1' and 'TRUE', respectively.

Input file (path)names must include only printable
characters and may not begin with a hyphen ('-').   The
following characters also are not allowed:  " ' * ? ` | > <
=====================
Height Parameter:
The data are assumed signed doubles each falling within +1
and -1 limits.  All data in every file are checked, and
anything falling outside these limits will cause an input
file to be rejected.

Within these limits, the percent height h parameter will
represent a threshold height percentage H relative to the
greatest positive value(s) in the file.   SpikeCount works
best if values in the file are normalized to make the most
positive data value 1.

Some audio file editting tools, such as CoolEdit(R), can
normalize low-amplitude data to 100%, making the greatest
excursion(s) from 0 equal exactly to +1 or -1.   If
normalized to 200% by such a tool, data between .5 and 1,
and between -.5 and -1, will be grown to +1 and -1
respectively, and all other data will be scaled up
proportionally.  This may make spikes in the data more
regular in height and therefore more easily counted, but
individual evaluation of each kind of sample is required to
be sure this will work.
=====================
Width Parameter:
Generally, a spike will be a pulse of several cycles above
the height threshold H value.   The percent width w
parameter ignores cycles and only considers time duration
(number of data lines) above and below H.

The value entered for w will be scaled against the average
rate of change in the file:  Somewhat simplifying, w should
be viewed as setting a width threshold as w percent of the
longest extent of nonpulse time in the file.

For just one spike in the input file, w is effectively the
duty cycle relative to H; w=3 means that an excursion over H
with 3% duty cycle or more (over the duration of the entire
file) will be recognized as a spike.   As the number of
spikes in the file increases, w becomes a percentage of a
smaller and smaller duration, thus letting SpikeCount become
on the average more and more precise in recognizing spikes.

A glitch is a brief change of level which should be
ignored.  SpikeCount's glitch rejection requires a downward
glitch to last more than 1/10 of the w determined threshold
to (mistakenly) terminate the spike.

Some attention has to be paid to the data:  Many very
closely spaced spikes may be counted mistakenly as fewer,
because of spike boundary rejection as glitches.   So, w
should be set lower if this happens.  Similarly, a pulse of
only a few slow cycles might possibly be counted as several
spikes; if so, w should be set higher.
====================
Check Command:
The Check button causes SpikeCount to check the selected
input files for a correct file name and extension.   Files
with an invalid name or extension will be listed to the text
output window.

Files with good names then are checked for existence, read
permission, correct header syntax, valid data, and for
consistency of the header with the data found.  Problems
with the selected files again are reported to the text
output window, and a list of remaining, valid file names is
given.

SpikeCount then stops and waits for further user input; no
spike counting is done.

In general, this command can save time when a large number
of files, some invalid, are to be examined for correct
format.   It about halves the time to obtain a validity
check on large, valid input files, as compared with the full
Count command.

To obtain a spike count, it is necessary to repeat the
checks done here by using the Count command.
====================
Count Command:
This command performs the same checks as Check; it then
goes on to count the spikes in each file found valid.

The spike criteria used are introduced in the Spike Height
and Spike Width help menues.   Basically, the initial Check
finds the greatest positive value p in the current file and
sets the spike height threshold H equal to p*h/100; it also
finds the longest duration T either above or below h/100 and
sets the spike width threshold W equal to T*w/100.

During Counting, the H and W thresholds then are used to
examine the duration of possible spikes and separate them
from noise; Count outputs the result to the output text
window.

Count also outputs a summary report of the number of files
counted, along with a list of names of files not counted
because of failing Check.

Look at your data and compare the counts to be sure h and
w are set appropriately.   If you find that you are missing
peaks you think should have been counted as spikes, try
setting h lower if it seems to be a height problem or w
lower if your peaks are narrow.   If your spike counts are
too high, try setting h or w (or both) higher.
====================
About . . .:

       SpikeCount v. r1.0.  Originated 2002-09-18.

                      by J. M. Williams
                     jwill@AstraGate.net
                      Copyright (c) 2003

This program is freeware and may be distributed freely by
any means for any reason, provided the executable and readme
file always are distributed together and neither is altered
in any way.


   Disclaimer:  This program was implemented for fun with
   requirements and design decomposition.   It is believed
   accurately described in the Help menues; however, it is
   distributed strictly as-is, with no guarantee of fitness for
   any purpose.

