% @(#)associimag.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:49:59
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1993 European Southern Observatory
%.IDENT      associima.hlq
%.AUTHOR     05-MAY-93, IPG/ESO
%.KEYWORDS   MIDAS, help files, 
%.PURPOSE    On-line help file for the command: ASSOCIATE/IMA
%.VERSION    1.0  MP : Creation, 05-MAY-93
%----------------------------------------------------------------
\se
SECTION./IMA
\es\co
ASSOCIATE/IMA					   MP  05-MAY-93
\oc\su
ASSOCIATE/IMA ost exptype rule_table outtable [flag] [nexp]
	 associates to scientific exposures a set of suitable calibration images
\us\pu
Purpose:    
	 associates to scientific exposures a set of suitable calibration images
\up\sy
Syntax:     
            ASSOCIATE/IMA ost exptype rule_table outtable [flag] [nexp]

\ys\pa
            ost        = Observation Summary Table 
\\ 
\ap\pa
            exptype    = type of exposure to be associated (e.g DARK, FF, etc)

\ap\pa
            rule_table = table containing the rules for the association process
\\
\ap\pa
            outtable   = output table 
\\
\ap\pa
            flag       = creation flag: (C)reate a new table or (A)ppend the
                         new columns to an existing table. Defaulted to C
\\
\ap\pa
            nexp       = maximum number of exposures to be associated.
                         Defaulted to 1 
\ap\sa
See also: 
            CREATE/OST, SELECT/TABLE 
\as\no
Note:       1) The association process uses as input an Observation Summary
               Table created by the command CREATE/OST. This table must
               contain a character column labeled :EXPTYPE containing for
               each frame its exposure type. This column may be created
               by the association process (CREATE/CRULE, CLASSIFY/IMAGE) \\
\\
            2) The association process selects for each scientific exposure
               of the OST all calibration frames matching a set of user defined
               selection criteria .
               The relevant calibration frames are  ranked by applying 
               weights to each criterion and the 'nexp' best ones
               are selected. The search may be expanded by submitting a "second
               choice" set of criteria when less than nexp frames match 
               the original one.
               The exposures matching the "first choice" set of criteria will 
               be flagged with a quality flag of 1 while the images matching
               only the "second choice" set of criteria  will be flagged
               with the quality 2.\\
\\                
            3) The association process creates a output table that 
               contains the following columns:
               - a character column labeled :SCI and containing the names
                 of the scientific frames. 
                 Each name is repeated in nexp rows.
               - a character column labeled  'exptype' (i.e DARK,FF, etc)
                 and containing the name of the associated exposures.
               - an integer column QUAL_'exptype' (i.e QUAL_DARK, QUAL_FF,etc) 
                 containing for each associated frame its quality flag.\\
\\          
           4) The rule_table must contain the following columns:
               - FUNCTION -character column (max 256 char)
               - RANGE_1  -character column (max 256 char)
               - RANGE_2  -character column (max 256 char)
               - WEIGHT   -R*4 column, \\
\\
               The column :FUNCTION shall contain mathematical expressions 
               defining the different selection criteria in which the variables
               may be the  columns of the OST. The expression may
               contain arithmetic and logical operators as well as mathematical
               functions.  On top of the operators and functions supported
               by the SELECT/TABLE command, a new function REFVAL is available.
               REFVAL(:col) will return the value of the column 'col' for the
               corresponding scientific exposure.
               Column :RANGE_1 and :RANGE_2 shall contain the ranges defining
               the "first choice" and the "second choice" set of criteria, 
               respectively.
               Column :WEIGHT shall contain the weighting factors for the 
               different selection criteria.\\
\\
               For instance, a "first choice" selection criteria may in
               natural language be:
               " Find for each  scientific image  all calibration frames 
                 which have been observed within 3 days and 
                 for which the detector mean temperature does not differ by 
                 more than 1 degree "
               The "second choice" selection criteria  may in that case be:
               " Find for each  scientific image  all calibration frames 
                 which have been observed within 15 days and  for which 
                 the detector mean temperature does not differ by more than 
                 10 degrees"
               These criteria  would  in the rule_table be expressed as:\\
\\{\tt
                FUNCTION                       RANGE_1 RANGE_2 WEIGHT
\\
                --------------------------     ------- ------- ------
\\
                ABS(:DATE-REFVAL(:DATE))       <=3     <=15       0.7
\\
                ABS(:DETTEMP-REFVAL(:DETTEMP)  <=1     <=10       0.3
\\
                --------------------------     ------- ------- ------
\\}
\on\exs
Examples:
\ex         ASSOCIATE/IMA ost DARK dark_asso ntt_asso C 3 
            associates to each scientific frame listed in the table ost
            at most 3 DARK exposures fullfilling  the criteria defined in the
            table dark_asso and stores the results in the table ntt_asso
\xe\sxe