Documentation on gaufit

Task: gaufit
Purpose: Fits gaussians to profiles
Categories: image-analysis

 gaufit fits gaussians to a profile and can write the output to
 a miriad dataset, a logfile or the terminal.
 The current version is not very smart about initial estimates: they
 need to be given manually by the user and need to be reasonably close
 already. It is intented to do this right, eventually.
 Also, it has not been possible to rigorously test everything, and the
 algorithm used is not very robust, so divergent fits and so may occur
 every now and then. But in principle you should get good results.

Key: in
	Standard in keyword. Use `help in' for more information.

Key: region
	Standard region keyword. Use `help region' for more information.
  Note: the region=mask option is not implemented. The mask of the
  input dataset is used however. If there is one, the profile value
  at masked datapoints is set to zero before doing the fit.

Key: model
 Optional output dataset, to which theoretical (described by fit)
 profiles can be written.

Key: residual
 Optional output dataset, to whicht the difference between the profile
 and the fit can be written

Key: params
 Optional output dataset to which the fit parameters can be written.
 For each fitted component six planes are written, one with the
 amplitude (or integral), one with the position and one with the fwhm
 (or dispersion), and three more with the errors. The planes with
 errors come after the planes with all fit results. A final plane
 which contains the rms of the residual is added.
 Unfortunately, because MIRIAD very-deep-down disallows opening an
 existing dataset for writing, it is not possible to add new fits to
 an existing parameter set. So you have to refit the whole cube if
 one profile is not to your liking! Or do some fiddling with adding
 two cubes. It'll be complex anyway you do it.

Key: fitaxis
 This determines along which axis profiles are taken. The default is
 the velocity ('vel') axis. Other possible answers are 'x', 'y', 'z',
 'a', 'ra', 'dec', 'lon', 'lat', 'freq'.

Key: ngauss
 Number of gaussian components to fit (maximum 10, default 1).

Key: options
 Controls the output. Possible options are:
   noprint:      do not print the fit results on the terminal
   supbad:       suppress results for fits outside ranges given by
                 cutoff, crange and wrange and results for bad fits.
   wrprof:       write out a file with the data and the fit so that it
                 at least is possible to use plotting programs to
                 compare them; a kludge until gaufit itself can plot.
   integral:     write out integral of gaussian instead of amplitude
                 (also interpret input for cutoff and estim keywords
                 as integral)
   dispersion:   write out dispersion of gaussian instead of fwhm
                 (also interpret input for wrange and estim keywords
                 as dispersion)
   pixels:       write center and width in pixels, not in units along
                 axis
                 (also interpret input for cutoff, vrange, wrange and
                 estim keywords as pixels)
   average:      first make an average profile of the selected region
                 and then fit one single gaussian to this profile
   summed:       first make a summed profile of the selected region
                 and then fit one single gaussian to this profile
   fixvelo:      fix the velocities to the initial estimate during fit
   fixwidth:     fix the width to the initial estimate while fitting
                 (fixvelo and fixwidth can be combined)

Key: cutoff
 Give a cutoff for the amplitude/integral: fits that give as result an
 absolute value of the amplitude/integral below the given cutoff are
 not written out.
 Default: cut off amplitudes below 1 times the rms.

Key: crange
 Give a range (in units along the profile) between which the center
 should lie. Fits that result in centers outside this range are not
 written out.
 Default: cut off centers outside profile range.

Key: wrange
 Give 1 or 2 values: a lower limit or a range for the width (fwhm or
 dispersion). Fits giving widths outside this range are not written out.
 Default: cut off widths less than 0.5 pixel and larger than the length
 of the profile.

Key: estim
 Initial estimates. Give an estimate for the amplitude, velocity and
 fwhm for each component (if options=integral, pixels or dispersion
 is used, give integral instead of amplitude etc.). This is quite
 critical and should already be reasonably close. The same initial
 estimate will be used for all profiles. (This will change in the
 future).

Key: rmsest
 Give a value for the rms of the profile. Used by the fitting
 procedure.

Key: log
 If the name of a file is given, the results of the fitting are written 
 to this file instead of to the terminal