% @(#)responirsp.hlq	19.1 (ESO-IPG) 02/25/03 14:23:16 
% @(#)
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1992 European Southern Observatory
%.IDENT      rectifirsp.hlq
%.AUTHOR     E.Oliva, Arcetri (Florence)
%.KEYWORDS   MIDAS, help files, RESPONSE/IRSPEC
%.PURPOSE    On-line help file for the command: RESPONSE/IRSPEC
%.VERSION    1.0  24-SEP-1992 : Creation, E.Oliva
%----------------------------------------------------------------
\se
SECTION./IRSPEC
\es\co
RESPONSE/IRSPEC                                      24-SEP-1992 EO
\oc\su
RESPONSE/IRSPEC in_ima flux_table out_response_ima [yrows=y1,y2,y3,y4]
                [obs=observation_mode] [norm=normalize_option]
                [rect=rectify_option]
        Create a response frame from a standard star 2D spectrum and
        a flux table.
\us\pu
Purpose:    To a create a (1D) response frame which contains the conversion
            from counts/sec to flux units for the measurements taken at 
            a given central wavelength (grating position). It requires 
            a "sky-subtracted" and wavelength calibrated 2D frame of a
            "standard" star plus a flux table - previously created with 
            STANDARD/IRSPEC - containing the intrinsic star fluxes.
            It automatically takes into account, and correct for, the
            on chip integration time so that the output response frame
            will contain the counts/sec given by a given flux unit.
\up\sy
Syntax:     RESPONSE/IRSPEC in_ima flux_table out_response_ima 
                [yrows=y1,y2,y3,y4] [obs=observation_mode] 
                [norm=normalize_option] [rect=rectify_option]
\ys\pa
            in_ima   = Input 2D frame containing the observed spectrum(a)
                       of the reference star. It must be cleaned, flat 
                       fielded  "sky-subtracted" (e.g. the result
                       of SKYSUB/IRSPEC, see also the observing_mode below)
                       and wavelength calibrated (see CALIBRATE/IRSPEC).
                       It must not be normalized unless you use the
                       normalize_option (see below). The command also
                       rectify the image if you have forgotten it, unless
                       you used rect=0 (see below).
                       N.B. the input frame is untouched on exit.
\ap\pa
            flux_table =
                       Input table - created using STANDARD/IRSPEC - 
                       containing wavelengths and star fluxes 
                       (columns :wl  :flux).
                       In case you are only interested in equivalent widths
                       or normalized spectra and you do not want to be 
                       bothered with flux calibration you can set this
                       parameter to - 0 - (see last example). Note that
                       in such a case the average value of your response 
                       frame will be forced to unity.
\ap\pa 
            out_response_ima =\\
                       Output 1D image containing the instrumental response
                       (counts/sec per unit flux) or just the 1D star 
                       spectrum, if you set the flux_table to 0. It will
                       be used in FLUX/IRSPEC.\\
\\
            Additional parameters and options
\ap\pa
            yrows    = Y-positions (rows) which has to be summed to obtain
                       the 1D stellar spectrum. You need 4 numbers because
                       the program expects to have 2 star spectra - one
                       positive and one negative - in the 2D frame. If
                       you do not specify anything you will be asked to
                       define the four positions with the display cursor.
                       In case your star observations were of the type
                       "object-sky" (see parameter obs=... below) you still
                       need 4 row (cursor) positions, 2 to define the star
                       and 2 to define the sky.
\ap\pa
            observing_mode = \\ "ab" or "os", default=ab.
                       The most usual and recommended observing procedure 
                       is to take "object" and "sky" frames with reference  
                       to the star set at two different positions along the
                       slit. In this case you will have 2 spectra, one
                       positive and one negative, in your frame. For these
                       kind of frames use   obs=ab  (default).
                       If you have just one spectrum in your 2D image
                       you must use obs=os (o=o is enough) otherwise
                       the response values will be a factor of 2 too low.
\ap\pa
            normalize_option = \\ 0,1, default=1.
                       The command automatically takes into account, and 
                       corrects for, the on-chip integration time so that 
                       the output response frame will contain the counts/sec 
                       given by a given flux unit (in short it "normalizes"
                       the observed counts). 
                       Use norm=0 (or just n=0) to force the comma to skip
                       the automatic, normalization procedure.
\ap\pa
            rectify_option = \\ 0,1, default=1.
                       The command automatically checks if the input 2D image
                       was rectified - using RECTIFY/IRSPEC - and performs
                       this operation in case this was not previously done.
                       Use rect=0 (or just r=0) to skip this control.
\ap\no
Note:       To normalize the frame to counts/sec the command reads the 
            on-chip integration time which is stored in the original frames
            as a descriptor. If you get strange error messages (e.g. 
            descriptor not present) it probably means that your input image
            is the result of a series of non standard operations in which
            the descriptor got lost. Use\\
                COPY/DD original_ima *,3 your_image \\
            to recover it. A similar argument applies to the "rectify-control"
            which may not recognize that the image was already rectified if
            the proper descriptor got lost into non standard operations after
            the the RECTIFY/IRSPEC command. Use COPY/DD ... *,3 .... in this
            case too.
\\
            The Y-positions of the rows that you have defined with the
            cursor are stored in the output frame in the descriptor 
            IRS_YROWS, to look at them use\\
               READ/DESC frame_name IRS_YROWS\\
            In case the reference star has obvious, intrinsic features
            you should correct them in the response file. There is no
            - or at least I could not find - a standard approach to it.
            You may fit gaussian to the absorption line but this works 
            easily only for strong and isolated features in regions of 
            good atmospheric transmission, in which case modifying 
            the data manually using MOD/GCURS may give similarly good results.
            A convenient approach could be that of having two response files 
            from stars which you can assume not to have lines in common 
            (e.g. a very hot and a fairly cool type) in which case by
            dividing the two frames you should be able to recognize and
            correct the star features as they appear in absorption or in 
            emission depending to which of the two stars they belong.
            But this means that you should have already planned your
            observations in advance and, indeed, "lost" quite a bit
            of time just looking at the stars...
\on\exs
Examples:
\ex
            RESP/IRSP bgdiff hr4138 bgresp 
                Create response frame "bgresp" from 2D image "bgdiff"
                and flux table "hr4138" using the cursor to specify the
                Y-positions of the star spectra
\xe\ex
            RESP/IRSP bgdiff hr4138 bgresp y=23,28,44,49
                Same as above but with the explicit specification of the
                Y-positions (note that y=... is enough).
\xe\ex
            RESP/IRSP bgdiff hr4138 bgresp y=23,28,44,49 obs=o
                As above but with the original frame containing just one
                star spectrum (i.e. with the star out of the slit in the
                original sky frames).
\xe\ex
            RESP/IRSP pbstd 0 pbrnoflux y=19,25,48,53 
                Create a "non-flux-calibrated" response frame called
                "pbrnoflux" which just contains the observed star spectrum
                (in counts/sec). 
\xe \sxe


