% @(#)combinccd.hlq	19.1 (ESO-SDAG) 02/25/03 14:14:59
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1993 European Southern Observatory
%.IDENT      combineccd.hlq
%.AUTHOR     RHW, IPG/ESO
%.KEYWORDS   MIDAS, ccd package, COMBINE/CCD
%.PURPOSE    On-line help file for the command: COMBINE/CCD
%.VERSION    930407 RHW created
%.VERSION    930517 RHW documentation improved
%.VERSION    931101 RHW Released
%.VERSION    950113 RHW Changes according to the DO output format
%.VERSION    980309 SW  Add new method: mmedian = mean-median
%---------------------------------------------------------------------
\se
SECTION./CCD
\es\co
COMBINE/CCD                                                      1-Nov-1993 RHW
\oc\su
COMBINE/CCD exp [in_spec] [out_fram] 
	Combined a number of CCD frames of the same exposure type
\us\pu
Purpose:    
	Combined a number of CCD frames of the same exposure type
\up\sy
Syntax:     
        COMBINE/CCD exp [in_spec] [out_fram] 
\ys\pa
        exp =     exposure code of the frames to be combined. Options area:\\
                  BS for BIAS frames;\\
                  DK for DARK frames;\\
                  FF for FLAT field frames;\\
                  SK for SKY frames;\\
                  OT for OTHER frames.\\
                  The parameter `exp' determines which keyword setting will be
                  used for the combining (see below). 
\ap\pa 
        in_spec = a) name of a MIDAS table (with the extension `.tbl'), or//
                  b) name of a MIDAS catalogue, or
                  c) string of input single calibration frame, separated by
                     comma's.
                  By default the input is taken from the keyword CCD_IN. 

\ap\pa
        out_fram= resulting combined output frame. No default output.
\ap\no
Note:
        In case a MIDAS table is used the command expects the name of the
        output master calibration frames in the column which name should 
        be available from the keyword `exp'_COL. The name of this output
        master calibration frame should conform to the Data Organizer/CCD 
        naming convention. Obviously, the individual calibration frames must
        available.\\

        The parameters needed for the combining are read from the CCD keyword 
        structure. This keyword setting can be consulted by the command 
        SHOW/CCD `exp_typ', where `exp' can be BS, DK, FF, or SK. The 
        listing shows these keywords, their options and meaning:\\
        CCD_IN   \ \ \ input spec       - input table or catalogue\\
        `exp'_SIG\ \ \ yes/no           - create sigma and pixel count image?\\
        `exp'_TYP\ \ \ all/exp. type    - exposure time descriptors allowed\\
        `exp'_MET\ \ \ method           - method of combining (see below)\\
        `exp'_RAN\ \ \ value1,value2    - range of pixel values allowed \\
        `exp'_DEL\ \ \ yes/no           - delete input frames afterwards?\\
        `exp'_EXP\ \ \ yes/no           - scale by exposure time?\\
        `exp'_STA\ \ \ mean/median/mode - statistics for scaling or offset\\
        `exp'_SCA\ \ \ yes/no           - scaling required?\\
        `exp'_OFF\ \ \ yes/no           - offset correction required?\\
        `exp'_WEI\ \ \ yes/no           - use a weighted average?\\
        `exp'_SEC\ \ \ area             - area for computing the statistics\\
        `exp'_CLP\ \ \ value1,value2    - low/high sigma clipping factor\\
        `exp'_BLA\ \ \ value            - blank value for rejections\\

        The combining will be done according to the method contained in the 
        keyword `exp'_MET. Currently, the following methods are supported:\\
        sum             - simple sum of all input input images;\\
        ave(rage)       - input images are combined by averaging;\\
        median          - input images are combined by medianing each pixel;\\
        mmedian         - same as median but take the mean in a given interval;\\
        min(reject)     - reject the minimum value from the average;\\
        max(reject)     - reject the maximum value from the average;\\
        minmax(reject)  - reject the minimum and maximum from the average;\\
        sig(clip)       - apply sigma clipping algorythm to each pixel;\\
        avsig(clip)     - apply sigma clipping algorythm together with minmax                            rejection;\\
        For more details about the various methods, please refer to Chapter 
        Direct Imaging in Volume B of the ESO-MIDAS Users' Guide.\\

        Before the combining is done the exposure type descriptors of the 
        input frame are compared with the descriptor type stored in the 
        keyword `exp'_TYP. In case this keyword is filled with `*' or `?' all 
        exposure types are allowed. Else, a fatal error will follow if the  
        the keyword content is not equal to one or more frame exposure types.

        The first and second element of descriptor LHCUTS, containing the 
        real minimum and maximum of the frame are updated. In addition,
        the descriptor MEAN, MODE and MEDIAN contain the corresponding values
        of the pixels values within the area defined by the keyword IM_SEC,
        the useful image section.\\

        To generate the output combined frame only those input pixels will
        be used that have intensities within the range stored in the keyword 
        `exp'_RAN. The sigma frame, if created, also has the rejected pixels 
        excluded.\\

        In case the mmedian method is used the interval for averaging has to
        be specified by the `exp'_CLP keyword. This method does the same as
        in AVERAG/IMAGE using options=median,low,high. For further informations
        please refer to this help-page. Negative `exp'_CLP values indicate
	index intervals.

        In case the keyword `exp'_SIG is set two additional frame will be 
        created: one containing the number of frames used for the combining 
        result; a second contains the standard deviation around the mean 
        result.
\on\see
See also:   
        SET/CCD, SHOW/CCD, AVERAGE/IMAGE, AVERAGE/WINDOW
\ees\exs
Examples:
\ex
        COMBINE/CCD ff ost_asso.tbl
        Create all master flat frames which names are stored the master 
        flat column in the table ost_assoc.tbl. 
\xe\ex  
        COMBINE/CCD bs myflats.cat
        Created the combined flat from all the frames in the catalogue 
        myflats.
\xe\ex
        COMBINE/CCD bs myflat1,myflat1,myflat2
        Created the combined flat from the three input frames.
\xe\ex
        COMBINE/CCD bs
        Combine bias frames. The input in taken from the keyword CCD_IN. 
        Depending on the input continue like in one the above example.
\xe \sxe



