% @(#)skysubirsp.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, SKYSUB/IRSPEC
%.PURPOSE    On-line help file for the command: SKYSUB/IRSPEC
%.VERSION    1.0  23-SEP-1992 : Creation, E.Oliva
%----------------------------------------------------------------
\se
SECTION./IRSPEC
\es\co
SKYSUB/IRSPEC                                     23-SEP-1992 EO
\oc\su
SKYSUB/IRSPEC ima_obj ima_sky out factor[,shift[,deltax,deltay]]
              [sky=sky_table] [force=force_sky_to_zero]
              [cuts=cuts_values] [debug=debug_option]
        Perform obj-sky correcting for variation and shift of sky lines.
\us\pu
Purpose:    In most of the infrared the sky emission contains bright emission
            lines, OH transitions up to 2.3 microns and molecular bands
            (CO_2, CH_4 and others) at longer wavelengths. The intensity of
            the OH transitions varies with time, which implies that you are
            never sure that your "obj-sky" frame will be free of residual
            sky lines. Besides, it sometimes occurs that the grating moves
            by tiny amounts and produces very small shifts - usually within
            a few hundreds of a pixel - of the lines. Even though small,
            these shifts deteriorate the quality of the final image where
            the detector noise is often well below the 1 percent of the
            sky line intensity. This command is intended to correct the
            "obj-sky" frame both for the time variation of the sky line
            and for the shift. The way it does it is to multiply the sky
            frame by a given quantity ("factor") and to X-shift the object 
            frame by a given amount ("shift"). These parameters can be chosen
            automatically by the program, interactively - with the graphic
            cursor - or just entered manually; all depending on the value
            of "factor" you enter (use TUTORIAL/SKYSUB for a thorough
            explanation).
\up\sy
Syntax:     SKYSUB/IRSPEC ima_obj ima_sky out factor[,shift[,deltax,deltay]]
                          [sky=sky_table] [force=force_sky_to_zero]
                          [cuts=cuts_values] [debug=debug_option]
\ys\pa
            ima_obj  = Input object frame, must have the original X,Y
                       sizes; untouched on exit. It could also be an 
                       arithmetic expression between images (last example).
\ap\pa
            ima_sky  = Input sky frame, must have the original X,Y
                       sizes; untouched on exit. It could also be an 
                       arithmetic expression between images (last example).
\ap\pa
            out      = Output frame, which is "obj-sky" cleaned by bad pixels,
                       flat-fielded and corrected for sky lines according to
                       the user's choice.
\ap\pa 
            factor[,shift[,deltax,deltay] =\\
                       factor controls whether the values of "factor" and
                       "shift" are defined automatically, manually or
                       interactively. Please use TUTORIAL/SKYSUB to get
                       a full description of all the possibilities and to
                       to get examples of the uses of the 4 parameters.
\ap\pa
            sky_table =
                       optional table containing the regions of the image
                       which do not contain any object emission (use
                       TUTORIAL/SKYSUB for more information).
\ap\pa
            force_sky_to_zero = \\
                       Normally is 0, if set to 1 subtracts from the final
                       image the average value of the pixels in the sky
                       regions (use TUTORIAL/SKYSUB for more information).
\ap\pa
            cuts     = cuts to be used in loading the images (as in LOAD/IMA),
                       use cuts=n to force the command to work silently
                       (this is not always possible...)
\ap\pa
            debug    = normally is 0, to be set to 1 only for reporting
                       errors in case the command does not work properly
                       in the automatic mode.
\ap\no
Note:       The output frame is also flat-field and cleaned of the bad pixels,
            this means that you may find it convenient to use SKYSUB even for
            making a straight image subtraction (see second example).
\\
            A flat and a dark must be previously stored using SET/IRSPEC,
            the dark being necessary for the fact that when you multiply 
            the sky by a number different the unity your final image will 
            have a residual "dark" which has to be corrected for. Obviously,
            when working beyond 2.3 micron the dark has little sense because
            of the strong thermal background which dominates over the internal
            dark.
\\
            The effect of line shift cannot be always corrected as a grating
            movement during an integration also makes the lines broader.
            If you have several sky frames it may help to use a suitable
            combination of the sky frames (see last example).
\\
            The values of "factor" and "shift" used are stored in the output
            frame as descriptors IRS_FACTOR, IRS_SHIFT. Use READ/DESC to
            access them.
\on\exs
Examples:
\ex
            SKYS/IRS a0012 a0013 subtr1 0 cuts=-50,50
               defines automatically "factor" and "shift"
\xe\ex
            SKYS/IRS a0018 a0019 subtr2 1,0 cuts=n
               straight subtraction + cleaning and flat-field, works silently 
\xe\ex
            SKYS/IRS (a0101+a0104)/2  a0103*0.6+a0104*0.4 -1,0 f=1 sky=tabsky
               example of the use of arithmetic expressions.
               For more information use TUTORIAL/SKYSUB
\xe\sxe