
dpeakpick(1)                 Khoros                  dpeakpick(1)

PROGRAM
     dpeakpick - Find peaks or troughs in 1D data set

SYNTAX
     dpeakpick

     -i             input file

     [-f]           output ASCII file

     [-o]           VIFF format output file

     [-p]           if true, find peaks

     [-m]           if FALSE find first n, and if TRUE find
                    max/min n, peaks or troughs

     [-e]           If TRUE, endpoints will be considered for
                    peak designation

     [-w]           Num steps on both sides of point on which to
                    base peak decision

     [-hwr]         min that abs value of average slope over win-
                    dow can be

     [-d]           data processing direction (0 = down vectors,
                    1 = across bands)

     [-all]         Find all peaks or troughs
                                        -OR-

     [-n]           Number of peaks or troughs to find

     [-V]           Gives the version for dpeakpick

     [-U]           Gives the usage for dpeakpick

     [-P]           Prompts for command line options

     [-A [file1]]   Creates the answer file called dpeakpick.ans
                    or file1

     [-a [file1]]   Uses dpeakpick.ans or file1 as the answer
                    file

DESCRIPTION
     dpeakpick finds peaks or troughs in 1D data vectors by doing
     an estimate of the first derivative.  Peaks are detected by
     watching for sign changes in the slope of the line:
               slope = f(x) - f(x-1)
     In addition, two parameters, the window size (-w option) and
     the height to width ratio (-hwr option), are available for
     "smoothing" the data.  Increasing the values of these param-
     eters will tend to reduce the number of peaks found in the
     data set.  If flat peaks are encountered, the last point of
     the flat area will be assigned as the peak position.  When
     dealing with complex data, the real and imaginary components
     are processed individually.

     Output Files
          Output files can be in two different formats, ASCII (-f
          option) and VIFF (-o option).  The ASCII output file
          contains the following information for each vector (or
          band) in the data set: the number of peaks detected;
          the mean and standard deviation of peak to peak dis-
          tances; and the actual peak positions and values.

          The VIFF output file is an implicit file in which the
          peak or trough values are preserved, and all other
          values are set to zero.  Note that if data has peaks
          with amplitude = 0.0, these peaks will not show up in
          the VIFF output file.

     Find Peaks or Troughs
          The user has the option to specify whether peaks or
          troughs (-p option) be detected in the input sequence.
          Setting p to TRUE will cause peaks to be detected, and
          setting p to FALSE causes troughs to be detected.

     Number of Peaks
          There are two mutually exclusive options available for
          selecting the number of peaks or troughs to be
          detected.  If "Find All" is selected (-all option set
          to TRUE), every peak or trough in the data set will be
          recorded.  By selecting "Specify Number of Peaks" (-n
          N), the user can specify the number of peaks (N) that
          will be recorded.  If vectors containing fewer peaks
          than specified by the user are encountered, the maximum
          number found will be recorded, and a warning statement
          printed (this treatment includes signals in which no
          peaks or troughs are detected).  If the -all option is
          selected but set to FALSE, the number of peaks speci-
          fied by -n will be found.

     Find max/min or first N peaks/troughs
          If the number of peaks or troughs to be found is speci-
          fied (-n option described above), then the user can
          also specify whether those peaks/troughs are the first
          encountered or are the maximum/minimum in the data set.
          If -m is TRUE, the maximum/minimum N peaks/troughs will
          be found; if -m is FALSE, the first N peaks/troughs are
          recorded.

     Include Endpoints
          If this option (-e) is selected and set to FALSE, the
          first and last points in a data sequence will not be
          considered for peak or trough designation. If this
          option is set to TRUE, endpoints will be considered for
          peak or trough designation.  If this option is not
          selected, "include endpoints" will default to FALSE.

     Window Size
          Window size (-w option) describes the number of steps
          on both sides of a point that must be monotonically
          increasing/decreasing before the point will be counted
          as a peak or trough.  The default window size is 1,
          which provides for exact realization of the equation
          above, and maximizes the number of peaks detected.  Two
          special cases exist at the beginning and ending of a
          data sequence, where the window size on one side of the
          point in question will not be satisfied by the number
          of points available.  In such cases, the decision of
          whether the point is an extreme will be based on the
          available points.  The upper limit on window size is
          (signal length - 1)/2.

     Height to Width Ratio
          The height to width ratio (-hwr) is a heuristic parame-
          ter which, if selected, can be adjusted to decrease the
          number of peaks detected by requiring that the absolute
          value of the average slope over the window size
          (described above) be above the hwr value specified.  A
          hwr value of 0 is equivalent to not selecting this
          option.

     Data Processing Direction
          Data can be processed with either band or vector orien-
          tation (-d option). The default data processing direc-
          tion is in the band direction (d = 1). This means that
          each band is processed as a signal (instead of each
          vector being a signal).  The direction of processing
          can be changed so that processing occurs down vectors
          by setting the -d option to 0.  In other words, data
          stored in multi-band format will be processed as a set
          of data sequences, where each sequence corresponds to a
          pixel location, and the points of each sequence are
          defined by the bands corresponding to that pixel loca-
          tion.

REQUIRED ARGUMENTS
     -i     type: infile
            desc: input file

OPTIONAL ARGUMENTS
     -f     type: outfile
            desc: output ASCII file

     -o     type: outfile
            desc: VIFF format output file

     -p     type: boolean
            desc: if true, find peaks
            default: true

     -m     type: boolean
            desc: if FALSE find first n, and if TRUE find max/min
            n, peaks or troughs
            default: true

     -e     type: boolean
            desc: If TRUE, endpoints will be considered for peak
            designation
            default: false

     -w     type: integer
            desc: Num steps on both sides of point on which to
            base peak decision
            default: 1
            bounds: value > 0

     -hwr   type: float
            desc: min that abs value of average slope over window
            can be
            default: 0
            bounds: value >= 0.0

     -d     type: boolean
            desc: data processing direction (0 = down vectors, 1
            = across bands)
            default: true

     ***   These arguments are MUTUALLY EXCLUSIVE   ***
      If desired, you may provide ONE AND ONLY ONE of:

     -all   desc: Find all peaks or troughs
            default: true

     -n     desc: Number of peaks or troughs to find
            default: 1
            bounds: value > 0

            ********

EXAMPLES
SEE ALSO
     intro(1), verror(3), vgparms(3), vutils(3), ldpeakpick(3)

RESTRICTIONS
     dpeakpick Works only on VTT_TYP_FLOAT and VFF_TYP_COMPLEX
     implicit data file.

COPYRIGHT
     Copyright 1991, University of New Mexico.  All rights
     reserved.

Khoros                    Release: 1.0                          1

