% @(#)filtereche.hlq	19.1 (ESO-IPG) 02/25/03 14:18:34 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      filtereche.hlq
%.AUTHOR     OS/DB, IPG/ESO
%.KEYWORDS   MIDAS, help files, FILTER/ECHELLE
%.PURPOSE    On-line help file for the command: FILTER/ECHELLE
%.VERSION    1.0  18-APR-1988 : Creation, OS/DB
%----------------------------------------------------------------
\se
SECTION./ECHE
\es\co
FILTER/ECHELLE				               18-APR-1988 OS/DB
\oc\su
FILTER/ECHELLE   input   output  
	filter echelle frame for cosmic ray hits and subtract background
\us\pu
Purpose:    
            Filter echelle spectrum for cosmic ray hits. Positions of the
            spectral orders must be defined in the auxiliary table order,
            e.g. as generated by the command DEFINE/ECHELLE. The background
            is also subtracted.
\up\sy
Syntax:     
            FILTER/ECHELLE  input  output  
\ys\pa
            input   = input image (normally a raw echelle spectrum or
                      a dark subtracted spectrum)
\ap\pa
            output  = filtered output image
\ap\no
Note:      
            The parameters which control this command are read from 
            echelle keywords in sections 2. (Background) and 3. (Filtering)
            as displayed by SHOW/ECHELLE. Parameters for the background
            subtraction are described in the help file of SUBTRACT/BACKGROUND.
            Filtering parameters are the following:

            widx,widy,no_iter = width of the filter box in x and y (max. 21,21
                      and the number of iterations for the filtering.
                      Recommended values: WX approximate inverse of spatial 
                      slope of orders, i.e., if for instance the orders climb 
                      by one pixel in Y every 15 pixels in X, WX should be 
                      around 15; WY somewhat larger than extraction slit 
                      length (i.e. about 9 or 11 for CASPEC), no_iter 
                      typically 3-4.  defaults: 15,11,3\\
                      The corresponding echelle keyword is CRFILT.

            ron,g,ethresh = read-out-noise (in e-), inverse gain factor 
                      (e-/ADU), and threshold (in units of the standard
                      deviation) for cosmic ray removal in the spectral
                      orders (recommended value: 4-5); defaults: 40,10,4.\\
                      The correcsponding echelle keyword is CCDFILT.

            radx,rady,mthresh = radius in x and in y and threshold used for 
                      initial global median filter (same as in command 
                      FILTER/MEDIAN, see note b) below). For large radii, 
                      a high contrast between spectral orders and inter-order 
                      region can lead to unsatisfactory results (recommended 
                      values are 1,1) defaults: 1,1,10.\\
                      The corresponding echelle keyword is MEDFILT.

            a) Command DEFINE/ECHELLE (or equivalent) must have been used
            previously in order to properly set up the table order.

            b) Algorithm:\\
            The filtering procedure as follows: First, the entire frame is
            filtered with a median filter (the command
                    `FILTER/MEDIAN input output radx,rady,mthresh NA'
            is executed). However, the results of this filter are retained
            only for the inter-order space. The regions around the spectral
            orders are treated separately and the results merged into frame
            output.
\\
            For each x-position and in all spectral orders, stripes of
            height widy pixels and centered on the respective order are
            considered. For each such stripe, the spatial profile (i.e.
            along the slit) is formed. The individual spatial profiles
            are normalized as to their integrals being unity. The 'true'
            local spatial profile is then formed by taking the median
            of all individual spatial profiles Bwithin a range widx
            centered on each stripe. The spatial profile of each stripe
            is compared with its associated local median profile. A pixel
            in a given stripe is rejected, if its deviation from the
            value of the corresponding pixel in the associated median is
            larger than ethresh times the expected r.m.s. error of the pixel.
            The expected error is computed from the characteristics of the
            CCD, read-out-noise ron and inverse gain factor g, and the
            flux in the pixel.
\\
            The algorithm is interative: If a pixel is rejected, the
            spatial profile is re-computed and the process is repeated,
            until no_iter iterations are completed.
\\
            After the global filtering by a median filter and prior to the
            special filtering of the spectral orders, smoothing spline
            polynomials of degree deg are fitted to the background and
            the result subtracted from the frame (command
               `BACKGROUND/ECHELLE input output  table  hwid  deg  smooth'
            is executed). In order that subsequent high-level routines
            do not unnecessarily repeat this very time consuming step,
            a descriptor BACKGROUND is appended to the frame and
            initialized to 'SUBTRACTED'. The background will not be
            modelled again at a later stage if the descriptor BACKGROUND
            is found present with this and only this value.

            c) This filter does not dilute or reshuffle the flux information
            along the dispersion axis. That is, the instrumental point
            spread function will be left unaltered everywhere.
\\
            d) The filter will work satisfactorily only on spectra of
            sources without spatial inhomogeneities along the slit. For
            that matter, any defects extending over the full height of
            an order will not be filtered out.
\\
            e) Another requirement is that the spatial slope of the orders
            (their tilt with respect to the x-axis) is small.
\\
            f) Because of the normalisation of the individual spatial
            profiles formed, it is essential to check that a proper
            background compensation has been obtained.
\on\exs
Examples:
\ex
            FILTER/ECHELLE raw filtered
\xe \sxe
