; XGAUS
;---------------------------------------------------------------
;! Fits 1-dimensional Gaussians to images
;# TASK ANALYSIS PLOT SPECTRAL ONED MODELING TV-APPL
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2005, 2008
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
XGAUS     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
XGAUS     Fits 1-dimensional Gaussians to images
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 #
OUTNAME                            Output image name (name)
OUTCLASS                           Output image name (class)
OUTSEQ           -1.0     9999.0   Output image name (seq. #)
OUTDISK           0.0        9.0   Output image disk unit #.
BLC                                Bottom left corner of input
TRC                                Top right corner of input
YINC              0.0      128.0   Do every YINCth row
ZINC              0.0      128.0   Do every ZINCth plane
FLUX              0.0              Flux cutoff (see HELP)
BCHAN            -1.0      512.0   # channels at left for
                                   baseline (-1 => no baseline)
ECHAN            -1.0      512.0   # channels at right for
                                   baseline (0 => none)
DOOUTPUT         -1.0        1.0   Write residual image
DOSLICE          -1.0        2.0   Plot data on TEK/TV
DOMODEL          -1.0        1.0   Plot model on TEK/TV
DORESID          -1.0        1.0   Plot residuals on TEK/TV
PIXRANGE                           Min,Max of image intensity
                                     Max <= Min => entire range
LTYPE            0.0         6.0   Type of labeling: 1 border,
                                   2 no ticks, 3 standard, 4 rel
                                   to center, 5 rel to subim cen
                                   6 map pixels
PIXVAL           0.0               Display if peak < PIXVAL
NITER            0.0      4000.0   Max # fit iterations
                                    0 -> 100.
NGAUSS           1.0         4.0   Number of Gaussians
                                   Guess of model parameters
GMAX             0.0                 Peak of component (JY)
GPOS                                 X position (pixels wrt the
                                     reference pixel)
GWIDTH           0.0                 FWHM of comp. (pixels)
                                   Solve for model parameters?
DOMAX          -1.0         1.0      Solve for GMAX?
DOPOS          -1.0         1.0      Solve for GPOS?
DOWIDTH        -1.0         1.0      Solve for GWIDTH?
DOTV            -1.0          1.0  > 0 use TV instead of TEK
GRCHAN           0.0          7.0  TV graphics channel to use
BADDISK                            Disk to avoid for scratch
----------------------------------------------------------------
XGAUS
Task:  Fits one-dimensional Gaussians to each row of an image.
       (Normally XGAUS will be used on images with frequency or
       velocity as the first axis, but it will procede with others as
       well.)  The task fits up to 4 Gaussians plus a linear baseline
       to each row and writes up to 4 + 8*NGAUSS n-1 dimensional
       images containing the fit parameters and their uncertainties.
       Optionally, it will write the residual image as well.  With a
       careful choice of input parameters, the task is capable of
       running in a batch-like mode.  However, particularly for NGAUSS
       > 1, an interactive mode (using the TEK graphics terminal or
       the TV graphics planes) is recommended.  Note that, since the
       TV and TEK are not allowed in BATCH jobs, XGAUS turns off all
       interactive options and TEK/TV displays when it is run in
       batch.

       We strongly recommend beginning with DOTV=1 (the Tek crosshairs
       have trouble), GRCHAN=0 (use color to differentiate what is
       plotted), DOSLICE=2 (allow initial guesses to be set),
       DOMODEL=1 (see what was fit).  The initial guess uses channels
       1-BCHAN and Nchan to Nchan-ECHAN+1 to set the DC level and
       slope.  It is plotted as X signs.  The data are plotted with
       stepped connecting lines, the fit as a smooth connecting line,
       and the residual as a dashed line.  With GRCHAN=0, the guess is
       in graphics channel 2 (usually green), the data in 1 (usually
       yellow), the fit in 4 (usually cyan), and the residual in 3
       (usually pink).
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.
  OUTNAME....Output image name (name).      Standard defaults.
  OUTCLASS...Output image name (class).     Standard defaults.
             Used only for the residual image.  The OUTCLASSes
             for the fit parameters are SLOPE, CONST, AMPLn,
             CENTRn, and WIDTHn and for the uncertainties are
             DSLOPE, DCONST, DAMPLn, DCENTn, and DWIDTn.
             The "flux" of each component (ampl * width * 1.06)
             is written with OUTCLASSes of FLUXn and DFLUXn.
  OUTSEQ.....Output image name (seq. #).   0 => highest unique.
  OUTDISK....Disk drive # of output image. 0 => highest
             number with sufficient space.
  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.......Do only every YINC'th row (beginning at BLC(2)).
  ZINC.......Do only every ZINC'th plane (beginning at BLC(3)).
  FLUX.......A flux cutoff in the same units as the input image
             (i.e. Jy/beam).  If a row does not have three
             consecutive points above this level, no component
             is fit to the row.  It is also used to limit the
             points which determine the initial guess.
  BCHAN......Number of points at the left edge of the input row
             used to determine the initial guess for the linear
             baseline.  -1 => do not fit a baseline.
             0 => no channels at the left, i.e. the initial
             guess for the baseline slope will be zero.
  ECHAN......Number of points at the right edge of the input row
             used to determine the initial guess for baseline.
             0 => no channels at the right, i.e. the initial
             guess for the baseline slope will be zero.
  DOOUTPUT...True (> 0) requests that the residual (data-model)
             map be catalogued (using OUTCLASS).
  DOSLICE....True (> 0) implies plot the data on the TEK or TV.  > 1
             also requests a TEK/TV plot of the initial guess.  It
             must be set > 1. if you wish the option to correct
             initial guesses with the TEK cross hairs or TV cursor.
             If DOSLICE > 1 and NGAUSS > 1, the program pauses after
             plotting its initial guess and requests user input from
             the terminal.  Hit RETURN to procede with the program's
             initial guess.  Enter BAD to have the solution for the
             row blanked and E to have the program request your
             guidance as to a better initial guess.  During the
             entering of a new initial guess with the TEK crosshairs
             or TV cursor, you may request that a particular component
             be null (held at 0 amplitude) by indicating that its peak
             or halfwidth point is outside the plot area.
  DOMODEL....True (> 0) requests a plot of the final model for each
             row on the TEK/TV.
  DORESID....True (> 0) requests a plot of the final residual values
             in each row.  If any one or more of DOSLICE, DOMODEL, or
             DORESID is true, then the program will pause after each
             row and request input from the terminal.  At that point,
             you may enter BAD to have the solution blanked or simply
             a RETURN to keep the answer.  The program will warn you
             if any of the fit parameters are way out of normal
             limits.  For NGAUSS > 1, one may also enter RETR to loop
             back and try again with a manually entered initial guess.
  PIXRANGE...Min,Max of Image intensity.  0,0 => min,max of EACH
             row (separately).
  LTYPE......Labelling type: 1 = border, 2 = no ticks, 3 = standard,
             4 = relative to center of row, 5 = relative to subimage
             (BLC, TRC) center 6 = pixels in original map
  PIXVAL.....Plot row only if the peak value < PIXVAL.  Limits the
             plots to those of uncertain intensities.
  NITER......Maximum function evaluations during the fit of each row.
             (< 10 -> 100 for NGAUSS > 1, < 100  -> 150 for 1
             Gaussian)
  NGAUSS.....Number of Gaussians to fit (between 1 and 4).
  GMAX.......Estimate of brightness of components 1 through 4.
             0 => use data at GPOS.  Ignored if NGAUSS = 1.
  GPOS.......Estimate of central pixel of comps 1 through 4 in
             pixels from the reference pixel (increases to the
             right).  Ignored if NGAUSS = 1.
  GWIDTH.....Estimate of the FWHM in pixels of comps 1 - 4.
             Ignored if NGAUSS = 1.  If NGAUSS > 1, the program will
             use either the user initial guess or the previous
             solution as the new initial guess - whichever has a lower
             rms.  To indicate that the program should always use the
             previous solution, set all GWIDTH to 0.  Of course, you
             may always enter a revised initial guess with the TEK/TV.
  DOMAX......<= 0. means hold this parm fixed (NGAUSS > 1 only).
  DOPOS......<= 0. means hold this parm fixed (NGAUSS > 1 only).
  DOWIDTH....<= 0. means hold this parm fixed (NGAUSS > 1 only).
  DOTV.......> 0 => use TV, otherwise the TEK emulator is used.  This
             emulator sometimes does not work well on LInux systems.
  GRCHAN.....TV graphics channel to use.  0 -> use more than one to
             allow color to contain extra meaning.
  BADDISK....Disk drives to avoid for scratch files.
----------------------------------------------------------------
