;SERCH
;---------------------------------------------------------------
;! Finds line signals in transposed data cube
;# TASK SPECTRAL ANALYSIS
;-----------------------------------------------------------------------
;;  Copyright (C) 1997, 2008, 2014
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
SERCH     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
SERCH    Finds line signals in a v-x-y transposed image cube
INNAME                             Input image name (name)
INCLASS                            Input image name (class)
INSEQ             0.0     9999.0   Input image name (seq. #)
INDISK            0.0        9.0   Input image disk unit #
BLC                                Bottom left corner of input
TRC                                Top right corner of input
YINC              0.0       64.    Pixel increment on Y axis
                                   (usually right ascension)
ZINC              0.0       64.    Pixel increment on Z axis
                                   (usually declination)
BCHAN             0.0              Lowest width in channels
ECHAN             0.0              Highest width in channels
CHINC             0.0              Increment in widths
CHANSEL                            Up to 10 sets of begin, end
                                   and increment channel numbers
                                   for line search regions
PIXAVG                             Estimate of average offset
                                   from 0 of non-signal areas
PIXSTD                             Estimate of true noise rms
NBOXES           0.0         40.0  Number of spectral regions to
                                   be used in fitting baseline
                                   0 => no baseline fit
BOX              0.0       4096.0  Pairs of begin-end channels
                                   for spectral baseline regions
ICUT                               Report all "signals" with
                                   Signal/noise over ICUT.
                                   0 => 8
DOWEIGHT       -1.0         1.0    > 0 => use filters weighted
                                   by channel rms's, otherwise
                                   use unweighted filter
DOOUTPUT       -1.0         1.0    > 0 => write hyper cube of
                                   S/N > ICUT and < -ICUT.
OUTNAME                            Hyper cube name
OUTCLASS                           Hyper cube class
OUTSEQ          0.0                Hyper cube sequence number
OUTDISK         0.0                Hyper cube disk number
DOHIST                             > 0 => plot/print histogram
                                   = 0 => print histogram
                                   < 0 -> no histogram
FUNCTYPE                           'LG' => do log10 plot of #
                                   samples, else linear
LTYPE        -410.0        410.0   Type of labeling: 1 border,
                                   2 no ticks, 3 - 6 standard,
                                   7 - 10 only tick labels
                                   <0 -> no date/time
OUTTEXT                            Name of output log file,
                                   No output to file if blank
DOTV           -1.0         1.0    > 0 Do plot on the TV, else
                                   make a plot file
GRCHAN          0.0         8.0    Graphics channel 0 => 1.
BADDISK                            Disk to avoid for scratch
----------------------------------------------------------------
SERCH
Task:  Searches through a transposed data cube to try to find a line
       signal.  It loops over the expected line width (from BCHAN to
       ECHAN by CHINC) convolving each spectrum with a Gaussian of the
       current width and reports all channels/pixels having
       signal-to-noise over ICUT.  It accumulates a histogram of the S/N
       ratios and will plot it if requested.  It can write a lot of
       information to a text file including the noise levels in each
       channel, the reported points, and the histogram.

       Based on an algorithm due to Juan Uson.
Adverbs:
  INNAME.....Input image name (name).     Standard defaults.
  INCLASS....Input image name (class).    Standard defaults.
  INSEQ......Input image name (seq. #).   0 => highest.
  INDISK.....Disk drive # of input image. 0 => any.
  OUTSEQ.....Output image name (seq. #). 0 => highest unique.
  BLC........Bottom right corner in input image of desired
             subimage.  Default is entire image.
  TRC........Top right corner in input image of desired
             subimage.  Default is entire image.
  YINC.......Pixel increment kept from input Y axis (which is usually
             right ascension).  0 => 1.
  ZINC.......Pixel increment kept from input Z axis (which is usually
             declination).  0 => 1.
  BCHAN......Lowest line width tested in channels: 0 -> 2.
  ECHAN......Highest line width tested in channels: 0 -> 10.
  CHINC......Increment in line widths tested in channels; 0 -> 2.
             BCHAN, ECHAN, and CHINC do not have toi have integer
             values.
  CHANSEL....Up to 10 sets of begin/end/increment channel numbers to be
             tested for line signal.  CHANSEL(1,*) = 0 => 1
             CHANSEL(2,1) = 0 => NCHAN, CHANSEL(3,*) = 0 => 1.
             Other CHANSEL(2,*) = 0 => ignore this set.
             N.B. channel numbers are counted from 1 wrt to BLC(1).
  PIXAVG.....Estimate of average non-signal flux in image.
  PIXSTD.....Estimate of non-signal (true) rms in image.  IMSTAT - or
             better IMEAN - can provide these.  SERCH finds the true rms
             and average in each spectral channel, but will converge
             faster with good initial guesses.
  NBOXES.....Number of channel ranges to be used to find and subtract a
             linear spectral baseline on a point-by-point basis. 0 ->
             no baseline is subtracted.
  BOX........Up to 20 begin/end channels used to fit the linear spectral
             baseline.
             N.B. channel numbers are counted from 1 wrt to BLC(1).
  ICUT.......A flux cutoff in signal-to-noise ratio for reporting
             apparent signals.  if abs(S/N) >= ICUT it is reported and,
             if DOOUTPUT is true, written to the output file.   0 -> 8.
  DOWEIGHT...The solutions may be determined by weighting each channel
             equally (DOWEIGHT <= 0) or inversely to the square of its
             rms (DOWEIGHT > 0).
  DOOUTPUT...If > 0, an output file of siognal-to-noise will be written.
             All S/N less in absolute value than ICUT will be written as
             zero.  If the input file has N axes with > 1 pixel on them,
             then the output file will have its N+1 axis used for tested
             line width in channels.
  OUTNAME....Output file name.  Default is INNAME.
  OUTCLASS...Output file class.  Default is SERCH.
  OUTSEQ.....Output file sequence number.  0 -> one greater than
             previous maximum.
  OUTDISK....Output file disk number.
  DOHIST.....Determines whether a histogram is determined and plotted
             and/or printed.  < 0 => no histogram, >= 0 => print
             histogram iff OUTTEXT is not blank, > 0 => plot histogram.
  FUNCTYPE...Type of axis plot for number of samples in each box.
             'LG' => log base 10, else linear.
  LTYPE......Labelling type, see HELP LTYPE for details:
             1 = border, 2 = no ticks, 3 or 7 = standard, 4 or 8 =
             relative to ref. pixel, 5 or 9 = relative to subimage
             (BLC, TRC) center, 6 or 10 = pixels.  7-10 all labels
             other than tick numbers and axis type are omitted.
             Less than 0 is the same except that the plot file
             version number and create time are omitted.
             Add n * 100 to alter the metric scaling.
  OUTTEXT....Output file to log histograms, results, sigmas, etc. for
             later user processing.  The file is created if it does not
             exist and appended to if it already exists.  Nothing is is
             written to a file if the name is blank.  File name should
             contain directory and file parts, i.e, "LOCAL:SERCH.OUT".
             DOHIST must be >= 0 for the file to contain the histogram.
  DOTV.......> 0 => plot directly on the TV device, otherwise make a
             plot file for later display on one or more devices
             (including the TV if desired).  Only if DOHIST > 0.
  GRCHAN.....Graphics channel (1 - 7) to use for line drawing.  0 => 1.
  BADDISK....Disk drives to avoid for scratch file.
----------------------------------------------------------------
