% @(#)merge_irsp.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:52:53 
% @(#)
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1992 European Southern Observatory
%.IDENT      rectifirsp.hlq
%.AUTHOR     E.Oliva, Arcetri (Florence)
%.KEYWORDS   MIDAS, help files, MERGE/IRSPEC
%.PURPOSE    On-line help file for the command: MERGE/IRSPEC
%.VERSION    1.0  22-SEP-1992 : Creation, E.Oliva
%----------------------------------------------------------------
\se
SECTION./IRSPEC
\es\co
MERGE/IRSPEC                                       22-SEP-1992 EO
\oc\su
MERGE/IRSPEC prefix_ima i1,i2[,i3] out_table [excl=\#pixels_excluded] 
             [corr=correct_option] [ref=\#reference_image] [plot=plot_option] 
             [format=i_format]
        Merge 1D spectra into a table forcing connection of overlapping regions
\us\pu
Purpose:    To merge (connect) overlapping 1D spectra (images) into a table.
            It also allows optimizing the connection on the overlapping
            parts and excluding a given number of pixels at both edges
            of each spectrum.
\up\sy
Syntax:     MERGE/IRSPEC prefix_ima i1,i2[,i3] out_table 
                         [excl=\#pixels_excluded] [corr=correct_option] 
                         [ref=\#reference_image] [plot=plot_option] 
                         [format=i_format]
\ys\pa
            prefix_ima  =
                       The 1D spectra to be connected must be named with
                       a prefix and a number, e.g. spec0001 spec0002 ...
                       prefix_ima is simply the image prefix ( - spec -
                       in the above example).
\ap\pa
            i1,i2[,i3] =
                       The command merges the frames "prefix"i1 to 
                       "prefix"i2 with step i3 (default=1), see the
                       examples. The spectra must be ordered in wavelength
                       from "i1" to "i2" (step "i3") and overlapping.
                       However, randomly distributed spectra may also be
                       handled if no correction is applied (see correction_
                       option below).
\ap\pa
            out_table =
                       Name of the output table containing the merged
                       spectrum. It can be transformed into a 1D image
                       using CONVER/TABLE.\\
\\
            Additional parameters and options.
\ap\pa
            \#pixels_excluded= \\integer number, larger or equal 0, default=0.
                       Can be used to exclude a fixed number o pixels at
                       both edges of each spectrum.
\ap\pa
            correct_option= \\ 0,1 default=1.
                       If equal to 1 (default) the command forces the spectra
                       to properly connect on the overlapping parts.
                       If equal to 0 it just merge together the spectra into
                       the table without any correction.
\ap\pa
            \#reference_image =\\ integer number, default=0.
                       In the process of forcing the connection of the
                       overlapping regions one of the 1D images (the
                       "reference image") is left untouched. 
                       If ref=0 (the default value) the reference image
                       is the central 1D frame of the i1,i2[,i3] list. 
                       Use ref=image_number to specify a different reference
                       image, e.g. if your images are spec0010 spec0011 ...
                       ref=11 will select spec0011 as reference.
\ap\pa
            plot_option = 0,1 default=1.
                        If equal to 1 (default) it plots the spectra during
                        all the phases of the procedure. Be careful to use 
                        SET/GRAP xaxis=... yaxis=... to properly include all 
                        spectra in the plot. If equal to 0 it works silently.
\ap\pa
            i_format = i"n" , default i4.
                        To be used in case the names of your images contain
                        numbers shorter/longer than 4 digits, e.g. for
                        spec01 spec02 ... use format=i2 (or just f=i2).
\ap\no
Note:       The connection between the spectra is optimized by applying
            a multiplicative factor to the spectra (N.B. the input spectra
            are left untouched).This implies that this command works 
            properly only with spectra with strong and well defined continua
            while it may produce totally unreliable results with spectra with
            faint continua affected by variable offsets.
\on\exs
Examples:
\ex
            MERGE/IRS a 12,24,2 outa
              merge spectra a0012,a0014,a0016..a0024 into table outa.
\xe\ex
            MERGE/IRS a 12,24,2 outa e=4
              as above but excluding 4 pixels at both edges of each spectrum.
\xe\ex
            MERGE/IRSP b 11,18 outb p=0 f=i2
              merge spectra b11,b12,b13...b18 into outb, works silently.
\xe\ex
            MERGE/IRSP c 50,5,-5 outc c=0 
              merge c0050,c0045,...c0005 into outc without applying 
              corrections.
\xe\sxe