; SLFIT
;---------------------------------------------------------------
;! Task to fit gaussians to slice data.
;# TASK ANALYSIS ONED MODELING
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2000, 2009-2010, 2014, 2016
;;  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
;-----------------------------------------------------------------------
SLFIT     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
SLFIT:  Task to fit gaussians to slice data.
INNAME                             Image name (name)
INCLASS                            Image name (class)
INSEQ           0.0      9999.0    Image name (seq. #)
INDISK          0.0         9.0    Disk drive #
INVERS          0.0     46655.0    Version # of SL file. 0=>last
BDROP           0.0      9999.0    Drop slice pts from beginning
EDROP           0.0      9999.0    Drop slice pts from end
NGAUSS          0.0         4.0    No of gaussian components.
LTYPE                              Units to use for GPOS values.
                                   See HELP LTYPE
ORDER          -1.0         2.0    Fit baseline order (-1 none)
GMAX                               Initial guess of max values.
GPOS                               Initial guess of positions.
GWIDTH                             Initial guess of halfwidths.
         @                         Fit model parameters
FMAX     @                         Peak of component (JY)
         @                           0-> Use maximum value
FPOS     @                        (X,Y) position (pixels)
         @                           0-> Use position of max
FWIDTH   @                         (BMAJ, BMIN, PA) of comp.
         @                           (pixels,pixels,deg)
         @                           0->Use clean beam
DOMAX    $                         Solve for GMAX?  >0 -> yes
         $                           returns the error
DOPOS    $                         Solve for GPOS?  >0 -> yes
         $                           returns the error
DOWIDTH  $                         Solve for GWIDTH? >0-> yes
         $                           returns the error
----------------------------------------------------------------
SLFIT
Type: Task
Use:  Accept an initial guess of the parameters of up to 4 Gaussian
      components of a curve and produce new values of the parameters
      corresponding to a least squares fit of slice file data points.
Adverbs:
  INNAME......Image name (name).       Standard defaults.
  INCLASS.....Image name (class).      Standard defaults.
  INSEQ.......Image name (seq. #).     0 => highest.
  INDISK......Disk unit #.             0 => any.
  INVERS......Version # of SL file.    0 => highest version #
  BDROP.......No of slice pts to omit from beginning of slice.
  EDROP.......No of slice points to omit from end of slice.
  NGAUSS......No of gaussian components.
  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.
              *******  Here it is used to tell the program what units
              are used for the GPOS, GMAX, and GWIDTH.  Don't change
              this after doing TVSET and/or TV1SET (or TKSET and/or
              TK1SET if you can get them to work).
  ORDER.......Order of fit baseline: -1 none, 0 constant, 1 plus slope
              2 plus curvature
  GMAX........Initial guess of maximum amplitudes.
  GPOS........Initial guess of positions of the components in
              GPOS(1,i).  GPOS(2,i) not used.
  GWIDTH......Initial guess of widths at 1/2 max amplitude in
              GWIDTH(1,i).  GWIDTH(2,i) and GWIDTH(3,i) are not used.
              Note that the units of GMAX, GPOS, and GWIDTH are those
              in the plot (e.g. mJy, arc sec or Jy, degrees or ??).
  FMAX........The peak value fit for each component is returned.
  FPOS........The position (X,0) fit for components is returned.  The
              values are in pixels in the order
              (X1,0, X2,0, X3,0, X4,0).
  FWIDTH......The full width at half maximum fit for components are
              returned.  FWIDTH(2,i) and FWIDTH(3,i) are not used.
              Note that the units of FMAX, FPOS, and FWIDTH are those
              in the plot (e.g. mJy, arc sec or Jy, degrees or ??).
  DOMAX.......Flags for GMAX: if > 0 fit this parameter, else hold
              fixed.  Returned value is uncertainty in the fit
              parameter.
  DOPOS.......Flags for GPOS: if > 0 fit this parameter, else hold
              fixed.  Returned value is uncertainty in the fit
              parameter.
  DOWIDTH.....Flags for GWIDTH: if > 0 fit this parameter, else hold
              fixed.  Returned value is uncertainty in the fit
              parameter.
----------------------------------------------------------------
SLFIT: Task to fit Gaussian components to a 1D slice.
DOCUMENTOR: G. A. Fickling, Eric Greisen   NRAO/Charlottesville
RELATED PROGRAMS: SETSLICE, SLICE, TVSLICE, TVASLICE, TVGUESS,
                  TVAGUESS, TVMODEL, TVAMODEL, TVRESID, TVARESID,
                  TKSLICE, TKSET, TK1SET, TKGUESS, TKASLICE,

                           PURPOSE

    SLFIT fits up to four Gaussian-shaped components to a selected
part of a one dimensional slice.  An initial guess must be provided
for the parameters.  Because of the many different units that can be
used, the only practical way to do this is interactively using the
TV screen with verb TVGUESS.. Solution and error estimates are
generated and the solution and residuals can be plotted on the
Tektronics, TV. or line-printer.  An arbitrary selection of parameters
may be held constant in the solution.

    The fitting algorithm is based on the subroutine LMDER in the
Argonne National Laboratory Subroutine Package.  It uses a linearized
least-square solution to obtain the parameters.  It assumes a baseline
at zero intensity across the slice.

    Assuming that the usual GETNAME step has been done, a typical
session would go like:

INEXT 'SL'; EXTL       to list the parameters of the slice files.
INVERS n               to select the n th file for analysis.
TVSLICE                to plot the slice on the TV
EDROP 840; BDROP 700   to select a subsection to fit.
TVSLICE                to replot just the subsection.
NGAUS  2               to fit 2 Gaussians.
TVSET                  to set the initial guess of the solution

   The last verb will prompt you to

Put cursor at center & height of Gaussian comp 1 press button

Move the TV sursor to the required position and press any TV button.
(A, B, C, D).  The terminal then requests you to

Put cursor at halfwidth of Gaussian component 1 press button

Move the TV cursor until it is at the half-intensity point of the
component and press any TV button.  The process continues until all
components have been entered.  Then type:

TVAGUESS             to plot the guess on top of the slice plot.

If everything looks ok, then type:

GO SLFIT             to run the task.

The TVxxxxx verbs are shown here.  There are TKxxxxx verbs as well,
but the TK cursor reading sometimes does not work well on X windows
screens.

     When the task gets an answer, it will be displayed on the AIPS
monitor, recorded in the message file, and recorded in the slice file
itself.  You may therefore wish to print out your message file before
running SLFIT (see PRTMSG), to separate the SLFIT results from earlier
work.  The answers are now printed both in slice units and in proper
physical units.

To get a hard copy of the answers:

PRTMSG                to print the message file.

To display the results on the TV, enter:

TVSLICE               to replot the slice.
TVAMODEL              to add the model results to the plot.
TVARESID              to add the residuals (data - model) to
                      the plot.

To get a higher quality plot of the results:

DORES TRUE; DOMOD TRUE  to request the model and the residuals.
DOSLICE FALSE           to leave the slice data out of the plot.
TASK 'SL2PL' ; GO       to make a plot file.
INVERS 0                to select the latest plot file.
GO  PRTPL               to display it on the printer/plotter.


