================================================================================
                        HELP FILE for ACIS_PROCESS_EVENTS
================================================================================

NAME 
----
     acis_process_events -- produce detector, tiled detector, and  
     corrected sky coordinates as well as perform pulse height summations,
     grading, and gain correction. 
    

USAGE
-----
     acis_process_events infile outfile acaofffile alignmentfile [obsfile]
        [logfile] [gradefile] [gainfile] [eventdef] [doevtgrade] [spthresh] 
        [time_offset] [docentroid] [calculate_pi] [tstart] [tstop] 
        [qp_internals] [qp_pagesize] [qp_bucketlen] [verbose] [stop] [instrume] 
        [telescop] [random] [rand_seed]  


DESCRIPTION
------------
     The acis_process_events function has a dual purpose. One objective of
     this tool is to produce various grade related information about events 
     read in from an input file. This grade information includes the
     flight/event grade, pulse height sum for a given event, and grade from
     the grade file (ACIS, ASCA, or user defined). The other objective of
     this tool is to convert the ccd coordinates of input events into detector 
     coordinates based upon the ccd id, x and y coordinates, and detector 
     system being used. The computed coordinates may take  offsets and 
     sim alignment corrections into consideration when determining sky 
     coordinates for flight data. Dither corrections are included in xrcf 
     processing when an appropriate alignment file is provided. Gain 
     correction is also performed as long as a gain file is provided and
     the calculate_pi parameter is set to 'yes'.  


PARAMETERS
----------
     Acis_process_events requires an input file (fits or qpoe) containing event
     data as well as a parameter file containing the parameters listed  below:

     infile     - (existing event file/stack - either qpoe or fits)
                - this is an auto parameter that is used to specify the input
                  event file from which acis_process_events will process data.
                  If the file is in fits format, the actual event information
                  must be in an extension named 'EVENTS'. Additional items 
                  are extracted from keywords in the primary and EVENTS 
                  extensions.

     outfile    - (nonexistent event file- either qpoe or fits) 
                - this is an auto parameter that is used to specify where the
                  processed events are to be written.

     acaofffile - (existing  .FITS file or NONE)
                -  offset file used to compensate for spacecraft movements
                  during an observation
 
     alignmentfile - (existing alignment .FITS file or NONE)
                - this is an auto paramater which is used to provide the tool
                  with values used to adjust the mirror position via sim
                  alignment (flight) or dither (xrcf) values.
 
     logfile    - (nonexistent text file or 'stdout')
                - This value specifies the name of the ascii text file
                  which acis_process_events will generate if the verbose param
                  (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)
 
     obsfile    - (existing observation parameter .PAR file or NONE)
                - This value specifies the name of the observation parameter
                  file to seed the output event file header with. If the value
                  is not "NONE", the keywords from the specified file are
                  copied to the output file's header.  

     gainfile   - (existing gain correction .FITS file or NONE) 
                - This value specifies the name of the gain correction file
                  to use when calculating pi/performing gain correction. The
                  calculate_pi parameter (see below) must be set to perform
                  gain correction.

     gradefile  - (existing grade .FITS file or NONE)
                - This value specifies the name of the grading file to use to
                  perform grading. The file is also used to determine how to
                  sum corner pixels for event pulse height summations. 

     eventdef   - (output format or redirect to pre-existing output format)
                - This field allows the user to specify the contents of
                  the input 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. 
 
     doevtgrade - (yes/no) 
                - option to calculate and output the flight grade and 
                  and pulse height sum of events in the input qpoe file.

     spthresh   - (0..32767) 
                - the user defined split threshold value used in determining 
                  centroid calculations as well as flight grade and pulse 
                  height sum values.

     time_offset - (real number)
                - offset which needs to be added to the event file to synch
                  it up with the alignment data.

     docentroid - (yes/no) 
                - option to adjust the location of the local maxima based
                  upon weighted values of surrounding pixel pulse heights above
                  a threshold value.

     calculate_pi - (yes/no)
                - option to calculate pi/perform gain correction based on the
                  values in the gain file (see above) which must also be 
                  provided. The computed piulse invarience is only written to
                  the output event file if it is specified in the output file's
                  eventdef ('l:pi'). 

     tstart     - (TSTART or some other keyword name)
                - The name of the header keyword containing the time of the 
                  first event in this file. It is used as the lowerbound of 
                  a temporal filter on the event file

     tstop     - (TSTOP or some other keyword name)
                - The name of the header keyword containing the time of the 
                  last event in this file. It is used as the upperbound of 
                  a temporal filter on the event file

     qp_internals - (yes, no, redirect to qpoe.par file)
                - This boolean parameter instructs acis_process_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 directory the function was invoked from, and is
                  named 'runlog'. 

     stop       - (chip, tdet, det, sky)
                - The end of the coordinate transformations. This determines
                  the extent of the coordinate transformations that are 
                  executed by acis_process_events. It should generally be set
                  to sky.

     instrume   - (acis)
                - This specifies the instrument that the data was collected 
                  with. It should be set to acis.

     telescop   - (name of telescope parameter file or blank)
                - This tells what telescope parameter file to utilize
  
     random     - (yes, no)
                - This parameter controls whether a randomization factor is
                  added into coordinates when they are written out to 
                  compensate for any aliasing which may occur due to 
                  float to integer truncation. 
 
     rand_seed  - (0 or positive value)
                - This value specifies the random seed which is to be applied
                  to randomizations. A value of 0 causes the code to utilize a
                  time based pseudo-random seed. A non-zero value should
                  produce identical results on multiple runs of the same data.

     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.
 
     cclev1     - (output event definition string)
                - This event definition specifies the default output columns tha
                  will be written to the output file if the eventdef variable is
                  redirected here. It is primarily intended for coninous
                  clocking mode data.


EXAMPLES
--------

     Before running, the system environment should be set up. Type "setascds".

     Acis_process_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 acis_process_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 = test3.qp   Input QPOE file
              outfile = out.qp     Output file name
           acaofffile = NONE        offset file ( NONE | <filename>)
        alignmentfile = NONE       sim/fam alignment file ( NONE | <filename>)
             (obsfile = NONE)      obs.par file for output file keywords 
             (gradefile = asca_grades.fits) grade mapping file
             (logfile = acis_process_events.log) debug log file
            (eventdef = )stdlev1 -> {d:time,i:expno,s:frame,s:chipx,s:chipy}
          (doevtgrade = yes)       Determine event grade?
            (spthresh = 20)        Split threshold level
                   :
                   .

 
     Values enclosed in parentheses, such as obsfile, 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 the grading file to ACIS type:

           pset acis_process_events.par gradefile=acis_grades.fits

     Alternatively the parameter file editor pedit may be used.

     Once all of the parameters have been set to the desired values, the
     routine may be invoked by simply typing "acis_process_events". The routine
     will prompt the user for the input (infile) qpoe file, the output (outfile)
     qpoe file,  (acaofffile) and alignment file (alignmentfile)  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 debug runlog 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. 

           acis_process_events infile=test3.qp acaofffile=NONE alignmentfile=NONE  outfile=out.qp gradefile=acis_grades.fits  
 
     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 acis_process_events.

     A) For the events in qpoe file "simudata.qp" compute detector coordinates
        using the centroid algorithm. Also compute flight grade,
        ASCA grade, pulse height summations, and pulse invarience (pi).. Log 
        the run with an intermediate amount of information. Use the parameter 
        file to set options.
 
        1) set parameters- use pedit or pset
           i.e. type:
                pset acis_process_events infile=simudata.qp
                pset acis_process_events acaofffile=NONE
                pset acis_process_events alignmentfile=NONE
                pset acis_process_events outfile=example1.qp
                pset acis_process_events gainfile=new_gain.fits
                pset acis_process_events docentroid=yes
                pset acis_process_events doevtgrade=yes
                pset acis_process_events calculate_pi=yes
                pset acis_process_events gradefile=asca_grades.fits
                pset acis_process_events verbose=3 
                pset acis_process_events stop=det

        2) verify that the eventdef contains the desired output columns,
           if it does not, add them in.
           i.e. the eventdef should look something like:
              "{d:time,i:expno,s:chipx,s:chipy,s:tdetx,s:tdety,s:detx,s:dety,
               s:phas1,s:phas2,s:phas3,s:phas4,s:phas5,s:phas6,s:phas7,
               s:phas8,s:phas9,s:ccd_id,l:pha,l:pi,s:grade,s:fltgrade,s:status,
               s:ccd_node} 

        3) invoke acis_process_events
           i.e. type:
                acis_process_events

        4) accept the current input qpoe file value
           i.e. hit <return>

        5) accept the current output qpoe file value
           i.e. hit <return>

        6) accept the current  file value
           i.e. hit <return>

        7) accept the current alignment file value
           i.e. hit <return>

        8) examine results


     B) For the events in fits file "testdata.fits" compute sky coordinates
        using the centroid algorithm. Also compute flight grade,
        ACIS grade, and pulse height sums. Log the run with as much detail as 
        possible. Use the parameter file to set options.
  
        1) set parameters- use pedit or pset  
           i.e. type: 
                pset acis_process_events infile=testdata.fits 
                pset acis_process_events outfile=example2.fits 
                pset acis_process_events acaofffile=NONE
                pset acis_process_events alignmentfile=NONE
                pset acis_process_events docentroid=yes 
                pset acis_process_events doevtgrade=yes 
                pset acis_process_events gradefile=acis_grades.fits
                pset acis_process_events verbose=5
                pset acis_process_events stop=sky
     
        2) invoke acis_process_events
           i.e. type:
                acis_process_events 

        3) accept the current input fits file value
           i.e. hit <return> 

        4) accept the current output fits file value
           i.e. hit <return> 

        5) accept the current  file value
           i.e. hit <return>

        6) accept the current alignment file value
           i.e. hit <return>

        7) examine results


     C) For the events in qpoe file "testdata.qp" compute detector coordinates
        without using the centroid algorithm. Do not perform
        any grading operations and do not log the run data. Use command line
        arguments to run.

        1) invoke acis_process_events with values set in command line. 
           ie. type:
               acis_process_events infile=testdata.qp outfile=example3.fits acaofffile=NONE alignmentfile=NONE docentroid=no doevtgrade=no gradefile=NONE verbose=0 stop=sky
 
        2) examine results
 
 

IV.  NOTES 
--------------------------

     Dependencies-
        In the event that an option is selected for which all of the data
        dependencies are not met, the program will print a message to the 
        screen indicating that an error has been detected. Processing will
        terminate and the output file will not contain event data. If a run
        log is being produced, an error indication will also be written to
        the file. If an error has occurred there is no guarranty as to contents
        of the output file.  

        It does not matter what fields the input qpoe file contains provided 
        that all data dependencies for the selected options are met. A brief 
        summary of dependencies is listed below by option.
 
          docentroid - 
              requires the existence of the appropriate number of pulse
              height columns in the input file (ie 3 for faint cc mode,
              9 for faint te and faint w/ bias)
 
          doevtgrade - 
              requires the existence of the appropriate number of pulse
              height columns in the input file.
 
          gradefile - 
               If a grade scheme file is provided to grade events, one
               of the following three conditions must be satisfied:
 
               1) doevtgrade is selected and all dependencies for it are met
 
               2) doevtgrade is not selected but the pulse height columns
                  exist
 
               3) doevtgrade is not selected but the fltgrade column exists
                  in the input file

          calculate_pi -
               requires the calculate_pi parameter be set to yes, a gain
               file, and the following data from the input event file:
               ccdid, (ccdnode or chipx), and (pha, or phas1-phas9)
 
     General-
        It is the user's responsibility to ensure that the parameters are
        correctly set. That is, the user must be certain that if they want
        asca grades and flight grades that the appropriate parameters are
        set (ie. evtgrade=yes, gradefile=asca_grades.fits).

        This tool outputs an event file containing the data fields specified in 
        the acis_process_events.par eventdef parameter field. If data fields 
        are specified in the eventdef and are not computed by this routine, 
        they should have default initialization values of zero. 

        For fits files, the events are expected to be contained in the
        "EVENTS" extension. Header keywords are generally read from the
        principal extension ("EVENTS"). 

        WCS information is added to the output coordinate columns if they
        are specified using vectored output columns. This is achieved by
        using the following keywords in the eventdef:
 
              s:chip  instead of s:chipx,s:chipy  (for chip coordinates)
              s:tdet  instead of s:tdetx,s:dety   (for tiled detector coords) 
              f:det   instead of f:detx,f:dety    (for detector coords) 
              f:sky   instead of f:x,f:y          (for sky coordinates)
   

SEE ALSO
--------
     For more information on parameter files please refer to the documentation
     found in:

               /proj/ascds/docs/guides/Dev_Guide

     For more information on event files please refer to the documentation
     found in:

               /proj/ascds/staff/scidev/doc/evtlib.ps 


     For information regarding the data contained in the input/output files
     used by this task, please see: 

               Level 0 to ASC Archive ICD (rev 2.7  07-27-98)  
               Level 1 to ASC Archive ICD (rev 1.3  07-28-98)



DATE
----
     09-15-98 

