================================================================================
                       HELP FILE for TG_RESOLVE_EVENTS
================================================================================

NAME
----
     tg_resolve_events -- computes grating diffraction coordinates and adds 
                          columns to the event file.


USAGE
-----
     tg_resolve_events infile outfile regionfile [acaofffile]
        [alignmentfile] [logfile] [rmfile] [grating] [instrument] 
        [sigma_lo_adj] [sigma_hi_adj] [time_offset] [random] [rand_seed]
        [eventdef] [qp_internals] [qp_pagesize] [qp_bucketlen] [verbose]
        [stdlev1] [mode] 


DESCRIPTION
-----------
     The tg_resolve_events tool is utilized to perform level 1.5 processing
     on gratings data. This involves taking an input event list, a gratings  
     region mask, and a response matrix table and computing coordinates
     (dispersion/cross-dispersion, grating diffraction pixel coords) and 
     other gratings related data- ie. wavelength, order (acis only), and 
     part (HEG, MEG, LEG) ids. Unless the eventdef parameter is modified,
     the following columns are added by default: tg_r, tg_d (dispersion and
     cross dispersion angles), tg_part, tg_mlam, tg_m, tg_lam, and srcid.

 
PARAMETERS
---------- 
     Tg_resolve_events requires a fits or qpoe input file containing event data,
     a region file containing one or more grating region discriptors, a response
     matrix table, and a parameter file containing the following parameters:
 
     infile     - (input event file- either qpoe or fits bin table)
                - this is an auto parameter that is used to specify the input
                  event file from which tg_resolve_events will process data.
 
     outfile    - (output event file- either qpoe or fits bin table) 
                - this is an auto parameter that is used to specify where the
                  processed events are to be written. The type of the output
                  file is determined by the extension (.fits or .qp) of the
                  file name provided. If no extension is provided, the file 
                  type defaults to fits bin-table.  

     regionfile - (input region files)
                - this is an auto parameter that specifies the grating masks

     acaofffile - (input aspect offsets files- fits bin table format)
                - this is a hidden parameter that is used to specify the
                  aspect offsets file for gratings coordinate transformations.

     alignmentfile - (input alignment files- fits bin table format)
                - this is a hidden parameter that is used to specify the
                  sim/fam alignment needed for coordinate transformations.
 
     logfile    - (output text file or 'stdout')
                - This value specifies the name of the ascii text file
                  which this tool will generate if the verbose parameter (see
                  below) is set to a value other than 0. If the value is set to
                  "stdout", the output will be redirected to standard output
                  (typically the screen)
 
     rmfile     - (input table file- fits bin table format)
                - This is the name of the energy limit table, created from a
                  response matrix, that is used to resolve orders (acis only).

     grating    - (HETG, HEG, MEG, LETG) 
                - This parameter specifies the grating type so that the 
                  appropriate values (such as grating period) can be read in
                  from the appropriate grating parameter file.  

     instrument - (acis, hrc-s, hrc-i)
                - The instrument with which this data was collected. This
                  parameter specifies the instrument parameter file to read
                  in order to configure the instrument specific information
                  used by tg_resolve_events. 
 
     sigma_lo_adj - (real number)
                - This parameter specifies the lowerbound tolerance factor to  
                  apply to the PI limit given in the response table for 
                  calculating orders. The lo-limit in the rmfile table is
                  increased by this factor. (The default value is 3.0.)  

     sigma_hi_adj - (real number)
                - This parameter specifies the upperbound tolerance factor to  
                  apply to the PI limit given in the response table for 
                  calculating orders. The hi-limit in the rmfile table is
                  increased by this factor. (The default value is 2.0.)  

     time_offset - (real number)
                 - Offset to add to event time to synch w/ alignment data.

     random     - (yes, no)
                - This parameter controls whether a randomization factor is
                  added to detector pixel coordinates to anti-alias the result.
                  (The default is no.)
 
     rand_seed  - (0, positive integer)
                - Random seed (for pixlib), 0 = use time dependent seed 
                 (The default is 0.)
 
     eventdef   - (output format string)
                - This field allows the user to specify the contents of
                  the output file. The value may either be set to a desired 
                  list of columns and data types by the user, or a redirect to
                  predefined event definitions may be utilized via the redirect
                  command. 
 
     qp_internals - (yes, no, redirect to qpoe.par file)
                - This boolean parameter instructs tg_resolve_events whether
                  or not to use the the page and bucket length values specified
                  in the input file or to use the default values.
 
     qp_pagesize - (integer or redirect to qpoe.par file)
                - allows the user to specify the qpoe page size
 
     qp_bucketlen - (integer or redirect to qpoe.par file)
                - allows the user to specify the qpoe bucket length
 
     verbose    - (0..5) 
                - Option which allows the user to request a varying level of
                  textual output based upon the program execution. Levels range
                  from 0 to 5 with 0 representing no information and 5 
                  representing as detailed a log as possible. the log is 
                  written out to the value specified in the logfile 
                  parameter (see above).
 
     stdlev1    - (output event definition string)
                - This event definition specifies the default output columns
                  that will be written to the output file if the eventdef
                  variable is redirected here.
 

EXAMPLES
--------
     Tg_resolve_events may be executed utilizing either a parameter file or 
     command line arguments. When using command line arguments, parameters not
     explicitly specified will default to the values contained in the parameter
     file. Use "plist tg_resolve_events" to view the current parameter values.
     This will cause all parameters and their respective values to be echoed to
     the screen. The data will resemble the following:

          infile =        Input event file or stack
         outfile =        Output event file or stack
      regionfile =        Region file stack
     (acaofffile = NONE)  aspect offset file ( NONE | none | <filename>)
  (alignmentfile = NONE)  sim/fam alignment file ( NONE | none | <filename>)
        (logfile = tg_resolve_events.log) debug log file
         (rmfile = )       RM lookup table for order resolving (acis only)
        (grating = )      Grating type (HETG|HEG|MEG|LETG|TOGA)
     (instrument = )      Detector type: ACIS|HRC|HSI
   (sigma_lo_adj = 3.0)   D offset
   (sigma_hi_adj = 2.0)   R offset
    (time_offset = 0)     Offset to add to event time to synch w/ alignment data
         (random = no)    allow randomized digitation of floating point numbers
      (rand_seed = 0)     random seed (for pixlib), 0 = use time dependend seed
       (eventdef = )stdlev1 -> {d:time,i:expno,l:gdpx,s:gdpy,d:tg_r,d:tg_d,s:chipx,s:chipy,s:tdetx,s:tdety,s:detx,s:dety,s:x,s:y,s:ccd_id,l:pha,l:pi,s:grade,s:fltgrade,s:status,s:ccdnode,s:tg_m,d:tg_lam,d:tg_mlam,s:tg_srcid,s:tg_part,s:tg_smap}) output format definition
   (qp_internals = )qpoe.qp_internals -> yes) prompt for qpoe internals?
    (qp_pagesize = )qpoe.qp_pagesize -> 8192) page size for qpoe file
   (qp_bucketlen = )qpoe.qp_bucketlen -> 16384) bucket length for qpoe file
        (verbose = )file.display -> 1) level of debug detail (0=none, 5=most)
        (stdlev1 = {d:time,i:expno,l:gdpx,s:gdpy,d:tg_r,d:tg_d,s:chipx,s:chipy,s:tdetx,s:tdety,s:detx,s:dety,s:x,s:y,s:ccd_id,l:pha,l:pi,s:grade,s:fltgrade,s:status,s:ccdnode,s:tg_m,d:tg_lam,d:tg_mlam,s:tg_srcid,s:tg_part,s:tg_smap}) event format definition string
         (mode = ql)              

 
     Values enclosed in parentheses, such as random, must be changed prior to 
     execution or on the command line if the specified value is not desired.  
     Values not enclosed in parentheses, such as outfile, are auto parameters
     which the user will be prompted to either input or hit <return> to accept
     the current value. To change the value of a parameter type 
     "pset file parameter=value", ie. to change grating to HETG type:
 
           pset tg_resolve_events.par grating=HETG
 
     Alternatively the parameter file editor pedit or any text editor may 
     be used.
 
     Once all of the parameters have been set to the desired values, the
     routine may be invoked by simply typing "tg_resolve_events". The routine
     will prompt the user for the input (infile) event file, the output 
     (outfile) event file, and the region file (regionfile) names. 
     The user may either accept the suggested value by pressing <return>
     or may enter a new value. The routine will then execute. Upon completion
     the output event file will be written out, as well as a logfile if the 
     verbose parameter is nonzero.
 
     To run with command line arguments, simply type the routine name followed 
     by parameter assignments. The format is
     "function_name par1=val1 par2=val2 ... parn=valn", ie. 
 
           tg_resolve_events infile=test3.qp outfile=out.qp regionfile=mask.reg
 
     If the auto parameters are specified on the command line the routine will
     not prompt the user to accept or modify the values of these parameters.
 
     Following are a list of examples illustrating some of the various 
     processing options available with tg_resolve_events.
 
     A) Process the hetg file grating1.qp using the region mask 2_src.reg and
        the response matrix ccdsigma.fits. Randomize the output coords to 
        reduce aliasing, and print out a detailed log to the file run.log   
         
        1) set up the hidden parameters

           pset tg_resolve_events.par grating=HETG
           pset tg_resolve_events.par rmfile=ccdsigma.fits 
           pset tg_resolve_events.par instrument=acis 
           pset tg_resolve_events.par random=yes 
           pset tg_resolve_events.par debug=5  
           pset tg_resolve_events.par logfile=run.log  

        2) invoke the tool

           tg_resolve_events  

        3) When prompted for the "Input event file stack", 
           enter grating1.qp

        4) When prompted for the "Region file stack", 
           enter 2_src.reg

        5) When prompted for the "Output event file stack",
           enter test_out.qp    

        6) examine results 

 
NOTES 
-----
     General-
        It is the user's responsibility to ensure that the parameters are
        correctly set. 
  
        The requirements/algorithms for dealing with the drake flat are
        TBD are are not currently supported in tg_resolve_events

        If event files are in fits bin-table format, the event data is
        read from or written to the "EVENTS" extension. Necessary header
        keywords (ie. SIM_Z) are read from the principal header (also
        the EVENTS extension).

        WCS information is added to output coordinate columns if they are
        specified as vectored output coordinate pairs in the output
        eventdef (ie. "s:det" instead of "s;detx,s;dety" or "s:sky instead
        os "s:x,s:y").

 
SEE ALSO
--------
     For information regarding the data contained in the input/output files
     used by this task, please see: 
 
        Acis Data Products:    Level 1 to ASC Archive ICD   (rev 1.3  07-28-98) 
        Hrc Data Products:     Level 1 to ASC Archive ICD   (rev 1.4  06-15-98) 
        Grating Data Products: Level 1.5 to ASC Archive ICD (rev 1.4  07-02-98)  
 
DATE
----
     09-16-98

