NAME
     pkFindROI - Tcl/Tk Window Shell for Spectral Analysis


DESCRIPTION
     The NMRWish  peak  detection  command  operates  on  any  N-
     dimensional  region  of  interest extracted from a spectrum.
     It can be used directly from a  Tk  script,  or  through  an
     interactive  interface  such as the one provided in NMRDraw.
     Peak positions are estimated by  multidimensional  parabolic
     models.    These  models  are  also  used  to  estimate  the
     linewidth and extent of the peak in  all  dimensions.   Peak
     overlap is characterized by a recursive method which identi-
     fies continuous collections of points  above  the  detection
     threshold.   Noise  peaks are classified according to a Chi-
     square criterion.  Truncation artifacts are also identified,
     based  on analysis of Fourier transforms of the window func-
     tions used on the spectrum.


PEAK DETECTION SETTINGS POP-UP
     Filter Command:
          The name of a command to execute after peak  detection;
          when  executed,  the  command will be given the name of
          the current peak  table  as  its  last  argument.   The
          intent  of this option is to allow special filtering of
          the  peak  table.   For  example,  using  the   command
          "pkFilter.tcl"  will generate a "simple" version of the
          peak table from the original one.

     Chi2 Threshold:
          This is a probability threshold for noise  peak  rejec-
          tion by chi-square test.  The chi-square test estimates
          the probability that the  sum-of-squares  intensity  in
          the peak's neighborhood could be caused by random noise
          alone.  To use this test, you must enter  a  reasonable
          "Noise:"  value  above.   Increasing the chi2 threshold
          increase the rejection of peaks near the  noise  level.
          If  the  value  is set to one or zero, no peaks will be
          rejected.

     Noise:
          Enter an estimate of  the  standard  deviation  of  the
          spectral  noise  here.  The default value comes from an
          automated estimate.  This  parameter  is  used  in  the
          Chi-squared test to classify random noise peaks.  It is
          also used to estimate errors in peak  position  due  to
          random  noise  (parameters  DX DY DZ and DA in the peak
          table).

     Contour:
          Specifies the minimum number of  contour  levels  which
          define  the  "High:"  and  "Low:" peak detection thres-
          holds.

     High:
          The  detection  threshold  for  positive   peaks.    By
          default,  it is set to the height of the first positive
          contour level in use when the "Peak  Detection"  pop-up
          window appears.

     Low: The  detection  threshold  for  negative   peaks.    By
          default,  it is set to the height of the first negative
          contour level in use when the "Peak  Detection"  pop-up
          window  appears.  If want want to detect positive peaks
          only, set this parameter to a large negative number.

     DDX: ...
          Size of the detection region in +/-  points.   A  given
          point  must  be  larger than all of the other points in
          this detection region in order  to  be  detected  as  a
          peak.

     IDX: ...
          Size of  the  parabolic  interpolation  region  in  +/-
          points.   IncX:  ...  Defines  how much of the spectral
          data is read into memory for peak detection.  Values of
          zero  will  cause the entire spectral region to be read
          at once.  Since some spectral data may be too large for
          this,  it  is  possible  to  perform  peak detection on
          automatically on overlapping regions.  For example,  if
          3D  peak  detection  is  performed  with  a  setting of
          IncX=0, IncY=0, IncZ=16, the  data  will  be  read  and
          analyzed in 16-plane slabs. This will not effect deter-
          mination of peak positions, widths, and  heights,  how-
          ever it can effect the volume (VOL) and bounding region
          values (X1/X3 etc).

     Local Noise:
          By default, the Chi-square noise classification  scheme
          uses  a  uniform  noise  estimate  for all parts of the
          spectrum.  Selecting one of the X Y Z or  A  checkboxes
          will  allow for an adaptive noise estimate with respect
          to the selected dimension.  This  can  help  compensate
          for  noise  ridges.   Special  Options Currently, these
          options select how noise peaks are identified and  han-
          dled:
         Sinc Detect If this option is selected, the peak  detec-
         tion module will attempt to identify peaks which are due
         to truncation noise (sinc artifacts).

         Reject Noise Peaks If this option is selected, any  peak
         classified  as  noise (either random noise or truncation
         noise) will be automatically eliminated  from  the  peak
         table.

     Sinc Detect Parameters
          The peak detection module attempts to identify  trunca-
          tion  artifacts based on the details of window function
          and zero filling which were applied to  each  dimension
          of  the data.  By taking this information into account,
          it is possible to estimate for a  given  peak  how  far
          truncation  wiggles  would  extend  in  each  dimension
          before falling below the  detection  threshold.   XAdj:
          ... In the artifact detection procedure, the height and
          extent of the truncation peaks are modeled as a profile
          which  decreases  as  1/X, where X is the distance from
          the peak center, and in order for a small  peak  to  be
          classified as the truncation artifact of a larger peak,
          the smaller peak must fall  below  the  profile.   This
          value  is  used  as a multiplying factor to increase or
          decrease the overall profile height. XTol: ... In order
          for  a  small  peak  to be classified as the truncation
          artifact of a larger peak, the  two  peaks  must  align
          along  a  given  dimension.   This  value specifies the
          tolerance in points for deciding whether two peaks  are
          aligned.   XLW:  ...  A  rough estimate of the original
          linewidth in Hz in a given dimension before any  window
          function was used.

     Save Script
          Selecting this command will save a new version  of  the
          peak detection script "pk.tcl" without executing it.

     Done Use this button to dismiss  the  "Peak  Detection  Set-
          tings" pop-up window.

PEAK TABLE PARAMETERS
     INDEX
          the unique peak ID number.

     X_AXIS ...
          the position of the peak in points, by parabolic inter-
          polation.

     DX ...
          estimate of the error in peak position  due  to  random
          noise, in points.

     X_PPM ...
          the position of the peak in PPM, by parabolic  interpo-
          lation.

     X_HZ ...
          the position of the peak in Hz, by parabolic interpola-
          tion.

     XW ...
          the full width at half height in points,  estimated  by
          parabolic interpolation.

     XW_HZ ...
          the full width at half height in Hz, estimated by para-
          bolic interpolation.

     X1/X3 ...
          coords of the bounding region surrounding the  peak  or
          its cluster in points.

     HEIGHT
          the peak height, estimated by parabolic interpolation.

     DHEIGHT
          the error peak height due to random noise, estimated by
          parabolic interpolation.

     VOL  the peak volume, estimated as the sum of intensities in
          the  neighborhood  (bounds  given  by X1/X3 etc) of the
          peak maximum.

     ASS  location to hold assignment data.

     PCHI2
          the chi-square probability for the peak (i.e. probabil-
          ity that the peak could be due to random noise alone).

     CLUSTID
          identifies the cluster of peaks that a given peak over-
          laps.  Peaks with the same CLUSTID value are considered
          to be in one overlapped group.

     MEMCNT
          the total number of peaks which are in a  given  peak's
          cluster (i.e. peaks which have the same CLUSTID value).

     TYPE An  integer   describing   the   peak   classification;
          currently  1  =  Peak, 2 = Random Noise, 3 = Truncation
          artifact.


          pkFindROI: Peak  Detection  in  a  Region  of  Interest
          (ROI).   Arguments  for  Peak  Detection in a Region of
          Interest.
            -roi    roiID            ID of ROI  for  peak  detec-
          tion;
                                     Default is current ROI.
            -out    outName          Peak table output name.
            -reject                  Reject peaks marked as noise
                                     or truncation artifacts.

            -parent                  Record results relative to
                                     the parent data of the ROI.
            -reset                    Erase  current  peaks   and
          exit.
            -append                   Append  to   current   peak
          table.
            -nopk                    Suppress peak detection, but
                                     keep previous settings.
            -verb                     Verbose  mode   ON.    Peak
          Detection Settings:
            -dx    dxList  [1 1 ...] Detection limits +/- pts.
            -idx   itList  [1 1  ...]  Interpolation  limits  +/-
          pts.
            -plus  pThresh [0.0]      Positive  detection  thres-
          hold.
            -minus mThresh [-1e16]    Negative  detection  thres-
          hold.
            -clust          [No]        Adjust   clusters   after
          detect;
                                     used with multiple ROIs.
            -mask          [No]      Use binary mask to cluster
                                     peaks;  replaces  ROI  data.
          Noise Detection Settings:
            -sigma noise  [1.000]    Standard deviation of noise.
            -pChi  prob   [0.001]    P threshold for Chi2 test.
            -lnAdj aList  [None]     Axis list for local noise
                                     adjustment (use X  Y  Z  A).
          Truncation Artifact (Sinc) Detection Setting:
            -sinc          [No]      Use sinc detection.
            -hiAdj adjList [1.2 ...] Height adjustment factors.
            -lw    lwHz    [1.0 ...] Intrinsic linewidths.
            -tol   tolPts  [2.0 ...] Postition tolerances.   Out-
          put Printing Precision:
            -ppmPrec digits      [3] Precision for values in ppm.
            -hzPrec  digits      [3] Precision for values in Hz.
            -ptsPrec digits      [3] Precision for values in pts.