================================================================================ 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 | ) alignmentfile = NONE sim/fam alignment file ( NONE | ) (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 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 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 5) accept the current output qpoe file value i.e. hit 6) accept the current file value i.e. hit 7) accept the current alignment file value i.e. hit 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 4) accept the current output fits file value i.e. hit 5) accept the current file value i.e. hit 6) accept the current alignment file value i.e. hit 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