% @(#)deblenline.hlq	19.1 (ESO-IPG) 02/25/03 14:28:41
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1993 European Southern Observatory
%.IDENT      deblenline.hlq
%.AUTHOR     Deutsches Astronetz Goettingen
%.KEYWORDS   MIDAS, help files, 
%.PURPOSE    On-line help file for the command: DEBLEND/LINE
%.VERSION    1.0  01-DEC-94 : Creation, PB
%----------------------------------------------------------------
\se
SECTION./LINE
\es\co
DEBLEND/LINE					      01-DEC-94  PB
\oc\su
DEBLEND/LINE  infile [fitim] [fitpar] [method] [contin] [input] [intab]
	multiple component Gaussian fitting of spectral lines
\us\pu
Purpose:    
            This routine provides de-blending of spectral lines by means of a 
            simultaneous fit of up to six Gaussian profiles to a selected 
            spectral region.

\up\sy
Syntax:     
            DEBLEND/LINE infile [fitim] [fitpar] [method] [contin] [input] [intab]
 \\
\ys\pa
              infile = the name of a wavelength-calibrated, one- or two- 
                       dimensional spectrum.  If the spectrum is two-
                       dimensional, one of the axis must have NPIX = 1
 \\
\ap\pa
              fitim  = the name of the output file in which the fit image
                       is to be stored (Default: mdtmp1.bdf)
 \\
\ap\pa
              fitpar = the name of the output table file where the fit 
                       parameters are stored (Default: mdfit.tbl)
 \\
\ap\pa
              method = 1 to 3 letters specifying the fit option to be used.
                       (default ABG)
                       available options:
                        first letter:
                         A: all fit parameters can be varied to get the best fit
                         W: center wavelengths held fixed at input values, 
                            heights and widths of lines can vary
                         F: widths of lines held fixed at given values, centers
                             and heights of lines can vary
                         S: all fit parameters can vary, but all lines are 
                            required to have the same width in the fit.
                        second letter:
                         B: non-weighted fit (ie. all points have equal weight)
                         P: Poisson-noise weighted fit:
                            weight(i) = 1/datavalue(i)
                        third letter:
                         G: fit with Gauss profiles
                         L: fit with Lorentz profiles
 \\
\ap\pa
              contin = continuum option. Option available:
                        P: continuum is defined by two points
 \\
\ap\pa
              input  =  C: all initial parameters input interactively using 
                           cursor (Default option).
                        T: all initial parameters read from an input table
                        B: (available for W and S fit options)  
                           For fit option = W, input wavelengths are read from 
                           input table, remaining parameters are input 
                           interactively using cursor.
                           For fit option = S, initial guess at full width half
                            max of lines is input as a number in P7, remaining 
                           parameters are input interactively.
 \\
\ap\pa
              intab  = input table name (Default ttemp.tbl also used to hold input 
                       values for p6 = C); see also under B input option
\\
\ap\sa
See also: 
            INTEGRATE/LINE, CENTER/GAUSS, CREATE/GUI ALICE, CONTINUUM/SPEC
\as\no
Note:       
        DBLEND is basically a simple program for deblending of spectral lines.
        In a specified spectral region, starting guesses for the centers,
        maximum values (heights) and full width half maxima (widths) of the
        lines are input for up to six lines, and a simultaneous least-squares 
        fit using the selected profile and a gradient search method is used to 
        obtain a fit to the lines.  The data points are continuum-subtracted 
        before the fit is made.  In all cases, the continuum is considered to 
        be a straight line between two points.  The data points can be 
        specified to all have equal weight (ie non-weighted fit, the default) 
        or to be Poisson weighted (w(i) = |y(i)|).  The centers, maxima,
        sigmas (when Gaussian profiles are fit), full widths at half maxima,
        integrated area under each curve, and the associated estimated 
        errors, of the fitted profiles are output in a table, and an image of 
        what the fit looks like is produced and stored in an image.  For all 
        options, DBLEND ends with a plot of the input image overplotted with 
        the image of the fit and the individual fitted profiles.
\\
        The complications in DBLEND arise through the many options for fitting
        methods and input of parameters.  First I will describe the treatment
        of the continuum, then I will return to the fitting and line paramter 
        input options.
\\
        The continuum is defined by either two or four points, depending on the
        "contin" option specified.  If "contin" = P, two points must be given, 
        and the continuum is considered to be a straight line passing through 
        these two points.  If "contin" = R, four points must be given.  These 
        points are considered to define two regions, each of which is a 
        continuum region.  From each region, a single continuum point is 
        derived.  Its X value is the average of the X values of the two 
        endpoints, and its Y value is the average of all the data values between
        the two endpoints, calculated from the spectrum itself.  The continuum
        is then considered to be a straight line passing through these two 
        "average" continuum points. 
\\
        The simplest but slowest way to use DBLEND is with the input = C option,
        where all information is input interactively.  First the input spectrum 
        is plotted to the screen.  Then the user is asked to mark two points 
        with the cursor, defining a region which is to be "zoomed in on".  This 
        limited region is then plotted, so that the line parameters can be 
        entered with greater accuracy.  Next the user is asked to use the cursor
        to mark two points defining the beginning and end of the spectral region
        to be used in the fit.  Then the cursor is used again to mark the two 
        or four continuum points, and finally the starting guesses for the line
        parameters must be marked.  For each line, the left half maximum point
        is marked, then the center, then the right half maximum point.  As many
        lines as desired can be marked, but only the first six will be used
        by DBLEND.  Note that all these points are automatically stored in a 
        table called TTEMP, which also has the correct format to be used as an 
        input table when DBLEND is run with the input = T option.  This table 
        is treated as a disposable temporary table by DBLEND, but is not 
        deleted at the end in case you want to save it.  If you do not choose 
        to save TTEMP, you will find that these files build up in your 
        directory, and you must be sure to delete them now and then.
\\
        The fastest way to run DBLEND is with input = T.  In this case it is 
        assumed that "intab" contains the name of a MIDAS table file containing 
        all the needed input information.  The difficulty with this method is 
        that the input table must be constructed ahead of time.  The columns in 
        the table should be, in this order: 1) the position in the spectrum of 
        the data point (in world coordinates) (X-axis value when plotted), 
        2) the data value of the data point (Y-axies when plotted), and 3) the 
        equivalent of (1) in pixels.  This is exactly the format output by 
        GET/GCURSOR (along with several additional columns), so the input table
        could be made by the user in a separate step using GET/GCURSOR.  The 
        points in the table, one per row, should be, in this order: 1) the 
        beginning of the spectral region to be fit, 2) the end of the spectral 
        region to be fit, 3) the first continuum point, 4) the second continuum 
        point, [3a) the third continuum point (if contin = R), 4a) the fourth 
        continuum point (if contin = R),] 5) the left half maximum point of the 
        first line, 6) the center of the first line, 7) the right half maximum 
        point of the first line; then 5) - 7) are repeated for all lines to be 
        fit, up to six lines total.  Note that if contin = R, the input table 
        is changed slightly in the course of the fit, as the four continuum 
        points are replaced by the two averaged continuum points derived from 
        them.
\\
        The final input option, input = B, is only valid for the W and S fitting
        options.  Its action is context-dependent and will be described below 
        along with the two applicable options.
\\
        The most general of the fitting options is method = A.  With this
        option, all the line parameters are allowed to vary freely to achieve
        the best fit.
\\
        The method = W option holds the positions of the line centers constant
        at the input values, while the heights and widths can vary to achieve 
        the best fit.  When the input = B option is used with this fitting 
        option, the line centers to be used are assumed to be in the input table
        whose name is given in the intab parameter.  The centers must be in a 
        column labeled :X, and some arbitrary label must be given in a column 
        labeled :IDENT.  The table may contain other columns as well, since the 
        columns to be used are identified by their labels, not their positions 
        in the table.  The positions should be given in the world coordinates of
        the spectrum.  The rest of the input parameters are then determined 
        interactively, as for the input = C option.  When the spectrum is 
        plotted, the positions given in the input table are also indicated, so 
        that the user can see which lines he has chosen for the fit.  Naturally,
        when the time comes to mark the line parameters with the cursor, only 
        the left and right half max points for each line need to be marked, not 
        the centers.  The initial guess for the height of the line center is 
        derived from the spectrum itself and need not be provided.
\\
        With the method = F option, the widths of the lines are not allowed to
        vary during the fit.  The width of each line is held fixed at the input
        value, while the other parameters are allowed to vary to achieve the
        best fit.
\\
        The method = S option forces all lines to have the same width.  The
        width is allowed to vary during the fitting process, but is set to the
        same value for all lines.  With input = C or input = T, the width
        given for the first line is used as the initial guess for the width of
        all the lines.  Any other widths that are entered are ignored.  With
        input = B, the initial guess for the width is entered as a number in
        the seventh parameter spot, where intab is normally given.  All other
        inputs are marked interactively, as for the input = C option, except
        that the left and right half max points of the lines need not be
        entered.  When the time comes to mark the input line parameters, only
        the line centers should be marked.  The widths of the lines will be
        calculated using the number entered as the seventh input parameter.
\\
        Any of these fitting options can be used together with Poisson-noise
        weighting of the data points during the least squares fit.  If the
        second character of the method parameter is P, a weight equal to the
        inverse of the data value is assigned to each data point, and a
        weighted least squares fit is made.
\\
        Two different choices for the line profiles are presently available.
        The G option (this is the default) causes Gaussian profiles to be
        fit, while the L option causes Lorentz profiles to be fit.
\\
        Known problems:
\\
          Due to a peculiarity of GET/GCURSOR, each time the cursor is re-
        started, it must be moved to the left side of the graphics area before
        any values are entered.  If any attempted entry returns the MIDAS
        warning CURSOR OUTSIDE GRAPHICS AREA, DBLEND will choke on that value.
        It is not yet smart enough to detect bad entries and reject them.(?)
\\
          If the data values in the input table are too small, differencing in
        the course of the fit can easily give values which are too close to
        zero, causing the fit to crash.  This generally shows up as an 
        arithmetic fault in subroutine SOLS at line 22.  If you run dblend and
        it gives this error message, try just multiplying your image by some
        number so that the data values are greater than about 10e-4.  The
        resulting fit values should still be valid, except for the maximum 
        height of the line.
 \\
\on\exs
Examples:
\ex
        DEBLEND/LINE spec4
          The input spectrum in file SPEC4.BDF will be treated.  The default
        options method = A (all parameters free to vary), contin = P (two
        points define continuum), input = C (interactive input) will be used.
        The image of the fit will be stored in file MDFIT1.BDF, and the final
        fit paramters will be stored in file MDPAR.TBL.
\xe\ex
        DEBLEND/LINE spec4 ? ? abl
          Same as above, but Lorentz curves will be fitted instead of Gauss
        curves.
\xe\ex
        DEBLEND/LINE spec4 sp4fit sp4par f ? t lines
          The spectrum SPEC4 will again be treated.  This time we have chosen
        to use method = F and input = T, with the input table being in the file
        LINES.TBL.  The continuum option is again defaulted to P.  
        The image of the fit will be stored in file SP4FIT.BDF, and the final
        fit paramters will be stored in file SP4PAR.TBL.
\xe\ex
        DEBLEND/LINE spec4 sp4fit sp4par s ? b 2.1
          This example is similar to the second example, except that method = S
        has been chosen, where all the lines in the fit will have the same
        line width.  All input will be given interactively, except for the 
        input line width, for which the value 2.1 (in world coordinates) 
        will be used.
\xe \sxe
