================================================================================ 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 | ) (alignmentfile = NONE) sim/fam alignment file ( NONE | none | ) (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 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 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