Routine Name:   shapematch

Description:    This function compares two waveforms generated by GENESIS
                and returns a number which represents how similar the
                waveforms are to each other.


Usage:          shapematch reference-file simulation-file
                    -start start-time -stepsize dt
                    -absdev -alternate

Arguments:      reference-file:  reference data file of outputs vs. time
                simulation-file: simulation data file of outputs vs. time

                The reference data is what you want the parameter search
                to match; the simulation data is what the simulation
                produces.

Options:        -start start-time:  The time at which waveform comparison
                    starts.  If no value is given, start at time = 0.

                -stepsize dt: The time step of the samples in the files.
                    Default = 0.0001 sec.

                -absdev: Uses the mean of absolute differences of samples
                    instead of the root-mean-squared differences to
                    calculate the match value.

                -alternate: Uses an alternate algorithm which can deal with
                    waveforms having spikes and waveforms using
                    different time points.  The alternative algorithm
                    is considerably slower than the default algorithm,
                    and has not been thoroughly debugged.


Return value:   Returns a nonnegative floating-point number representing the
                goodness of the match, with 0 representing a perfect match.
                The more different the waveforms are, the larger the value.
                The value represents the root of the mean of the squared
                differences in the waveforms at corresponding time points,
                unless the -absdev option is chosen (see above).  A huge
                positive value is returned on an error.  In the event of an
                error, a massive penalty value (1.0e6) is returned.


Example:        float match
                match = {shapematch "refdata" "simdata" -stepsize 0.00005}


Notes:          The default algorithm requires both waveforms to be defined
                on the same time points.  It should not be used for
                comparing waveforms with spikes.

                The alternate algorithm compares interspike intervals only,
                ignoring spikes.  To do this it will transform the time
                base of corresponding ISIs so that they match.  This is
                reasonable if the ISIs are similar, but if they are very
                different the results will not be very meaningful.  The
                alternate algorithm should probably be used in conjunction
                with spkcmp to compare the spike times as well.

                The -absdev option will not work for the alternate
                algorithm; it uses mean squared deviations only.

                The alternate algorithm has not been as well tested as the
                default algorithm and we cannot guarantee that it will
                function correctly.  It was stolen from Upi Bhalla's
                shapematch routine.

See also:       Parameter Search (Param), gen2spk, spkcmp
