Routine Name:   gen2spk

Description:    This program takes ascii files generated by GENESIS
                containing simulation times and membrane potentials
                (normally of the soma) and extracts the spike times
                relative to the onset of a current-clamp square-wave
                pulse.   The output will be a file which will have currents
                and spike times listed in the file.

Usage:          gen2spk datafile current-start current-duration \
                        total-duration -stepsize dt -maxaccuracy

Arguments:      datafile: the ascii input file.  The format of the input
                    file is as follows: The beginning of a trial is
                    indicated by the following two lines:

                        /newplot
                        /plotname 0.234

                    i.e. the plotname is the current value for that
                    trial (units are arbitrary but are usually in nA).
                    This format is taken from Matt Wilson's xplot
                    program, which is useful for displaying simulation
                    output.  The subsequent lines consist of time/Vm pairs
                    as follows:

                        0 -0.0770584
                        0.0002 -0.077233
                        etc.

                    which can be generated automatically by the
                    asc_file object of GENESIS.  Multiple trials can be
                    put in one file, as long as they're separated by the
                    /newplot, /plotname ... sequence described above.

                current-start: the time in the trace where current
                    injection begins.  Most simulations allow the cell to
                    reach equilibrium before injecting current (e.g.  for
                    50-100 msec or more).  All spike times will be relative
                    to the starting time of the current injection.  Units
                    are in seconds (SI units).

                current-duration: the duration of the current injection, in
                    seconds.

                total-duration: the total duration of the entire trace,
                    including the time before and after the current
                    injection.

Options:        -stepsize dt: the output time step i.e. the time between
                    samples in the output file.  This is usually much
                    larger than the simulation time step.  The default
                    value is 0.0001 (0.1 msec).

                -maxaccuracy:  the output spike times are printed with ten
                    digits of precision rather than 4 (the default).
                    Obviously this is only useful if your output step
                    size is small enough so that the accuracy will make
                    a difference (i.e. less than 0.0001).

Output:         A file with the same name as the input file but with
                .spk.sim added.  The file format is:

                CURR 0.1
                SPK  0.0010
                SPK  0.0123
                --------------------
                CURR 0.2
                SPK  0.0004
                SPK  0.0054
                SPK  0.0080
                ...

                etc.  CURR means the current value and is equal to the
                value in the /plotname line in the input file.  Each spike
                gets a SPK line; the value to the right of the SPK is the
                time in seconds when the spike occurred, relative to the
                start of the current injection.  Different currents are
                separated by a line of dashes.

Algorithm:      See the comments in the file src/param/gen2spk.c.


Notes:          This routine is used mainly for generating data for the
                spkcmp function for current injection simulations.
                However, it is not limited to this use and will extract
                spikes from any membrane potential waveform.

                The /newplot and /plotname lines must be written out
                explicitly to disk using writefile.  Make sure they are
                flushed to disk before starting the simulation so that they
                don't appear in the middle of what asc_file writes.  See
                the parameter search demos for examples of this.

                Some weird waveforms may defeat the spike-identifying
                algorithm.  Very small (low amplitude) spikes are a good
                example of this.  Be careful when using this routine in
                cases like this, and check the outputs with a visual
                display of the membrane potential waveform.

Example:            genesis>  gen2spk "Vmfile" 0.2 1.0 1.5

                In this case, the current comes on at 0.2 seconds, lasts
                for 1.0 seconds (i.e. until the simulation time is 1.2
                seconds) and the whole trace is 1.5 seconds long.

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