SUBJECT(grt_lev15) CONTEXT(pipes) SYNOPSIS Level 1.5 grating pipeline for processing grating science data DESCRIPTION This is the level 1.5 grating pipeline for processing both ACIS and HRC data. The three main tools in the pipeline are tgdetect, tg_create_mask, and tg_resolve_events. The pipeline runs tgdetect to identify zero order sources. Then it runs tg_create_mask to create a grating mask file that defines the zero-order source region, and the grating arm region. Then tg_resolve_events is run to calculate dispersion and cross dispersion coordinates, wavelength and order for each event. The following tools and scripts are run within the `grt_lev15.ped' pipeline. See the individual documentation for more details on each tool. o) dmmakepar - creates a header parameter file of the EVENTS extension. o) grt_lev15_calib - set the calibration files for the pipeline. o) build_stk_filters - adds GTI (Good Time Interval) command line filter to the input event list. o) gti_filter_events - runs dmcopy to copy events that lie within the GTI. o) acis_filter_events/hrci_filter_events/hrcs_filter_events - if the observation is acis, dmcopy is used to copy events that have STATUS=0, GRADE=0,2,3,4,6. If the observation is hrc-i, dmcopy is used to copy events that have STATUS=xxxxxx00xx000xxx00000000x0000000. If the observation is hrc-s, dmcopy is used to copy events that have status=xxxxxx00xx000xxx00000000x00000xx. o) dmcoords - determines the sky coordinates of the target from the values of the RA_TARG and DEC_TARG header keyword. If RA_TARG and DEC_TARG keywords are absent, the values of RA_NOM and DEC_NOM will be used to determine the target in sky coordinates. o) tgdetect - a script that first creates a filter region about the target position of the GTI, STATUS (or GRADE as well for acis observation) filtered event file. Then it runs celldetect on that region to find all the zero-order sources. o) tg_create_mask - creates a region file to define grating arm and zero-order part boundaries in sky coordinates. tg_create_mask will use the zero-order source location found by tgdetect to determine the grating arm and zero-order part boundaries. If tgdetect detects no source, tg_create_mask will use the sky coordinates of the target pointing to determine the grating arm and zero-order part boundaries. The output region file created by tg_create_mask will help tg_resolve_events determine if an event belongs to zero-order or diffracted order, and whether a diffracted event belongs to HEG, MEG, or LEG part. o) set_tg_resolve_events_eventdef - set the output event def for tg_resolve_events to the appropriate values depending on whether it's an ACIS or HRC observation. o) tg_resolve_events - examinates each photon from the original event file(s) (i.e before any GTI, STATUS or GRADE filtering) to see whether it belongs to the heg, meg, letg, zero-order, or background part. The dispersion and cross dispersion coordinates, wavelength and order of each event will also be calculated. An input order-sorting table is needed for resolving the order of the ACIS data. tg_resolve_events can be run on either dithered data sets or not-dithered data sets. For dithered data sets, aspect files are needed. o) update_revision - runs dmhedit to update the value of the REVISION keyword in the output files of this pipeline. o) caldb_update_version - adds the CALDBVER keyword with value to the header of the output files that used calibration files. o) remove - removes any temporary files that we don't need. PARAMETERS name type ftype def min max units reqd stacks autoname ================================================================================================ clobber boolean no verbose integer 0 0 5 zo_sz_filt_x string default zo_sz_filt_y string default snr_thresh real 40 3 10000 expstk string none thresh real 10 3 10000 ellsigma real 3.0 expratio real 0 findpeaks boolean )celldetect.findpeaks celldetect_log boolean )celldetect.log psftable string fixedcell integer )celldetect.fixedcell0 999 fixedcell_cc_mode integer 99 0 99 bkgfile string none bkgvalue real 0 counts/pixel bkgerrvalue real 0 eband real )celldetect.eband acis_eenergy real 0.925 hrc_eenrgy real 0.9 snrfile string none convolve boolean no cellfile string none centroid boolean yes kernel string fits snr_ratio_limit real setsrcid boolean yes max_separation real 1 0 20 arcsec input_psf_tab string radius_factor_zero real 50 1 400 width_factor_arms real )hetg_width_factor1 200 hetg_width_factor real 20 1 200 letg_width_factor real 40 1 200 stdlev1_ACIS string stdlev1_HRC string aspectcorr string SOLUTION rmfile string energy_lo_adj real 1.0 0 10 energy_hi_adj real 1.0 0 10 eventdef string )stdlev1 rand_pix_size real 0.5 0.0 0.5 pixel stdlev1 string DETAILED PARAMETER DESCRIPTIONS clobber type=boolean def=no Clobber output files? verbose type=integer def=0 min=0 max=5 Controls amount of verbose output about each processing step. zo_sz_filt_x type=string def=default see tgdetect zo_sz_filt_y type=string def=default see tgdetect snr_thresh type=real def=40 min=3 max=10000 see tgdetect expstk type=string def=none see celldetect thresh type=real def=10 min=3 max=10000 see celldetect ellsigma type=real def=3.0 see celldetect expratio type=real def=0 see celldetect findpeaks type=boolean def=)celldetect.findpeaks see celldetect celldetect_log type=boolean def=)celldetect.log see celldetect psftable type=string see celldetect This parameter is set by grt_lev15_calib in the pipeline. fixedcell type=integer def=)celldetect.fixedcell min=0 max=999 see celldetect fixedcell_cc_mode type=integer def=99 min=0 max=99 see celldetect bkgfile type=string def=none see celldetect bkgvalue type=real def=0 units=counts/pixel see celldetect bkgerrvalue type=real def=0 see celldetect eband type=real def=)celldetect.eband see celldetect acis_eenergy type=real def=0.925 see celldetect hrc_eenrgy type=real def=0.9 see celldetect snrfile type=string def=none see celldetect convolve type=boolean def=no see celldetect cellfile type=string def=none see celldetect centroid type=boolean def=yes see celldetect kernel type=string def=fits Output file format. snr_ratio_limit type=real see tgdetect This parameter is currently not being used in the pipeline. setsrcid type=boolean def=yes see tgdetect This parameter is currently not being used in the pipeline. max_separation type=real def=1 min=0 max=20 units=arcsec see tgdetect input_psf_tab type=string see tg_create_mask This parameter is set by grt_lev15_calib in the pipeline. radius_factor_zero type=real def=50 min=1 max=400 see tg_create_mask width_factor_arms type=real def=)hetg_width_factor min=1 max=200 see tg_create_mask hetg_width_factor type=real def=20 min=1 max=200 see tg_create_mask letg_width_factor type=real def=40 min=1 max=200 see tg_create_mask stdlev1_ACIS type=string see tg_resolve_events This parameter is currently not being used in the pipeline. stdlev1_HRC type=string see tg_resolve_events This parameter is currently not being used in the pipeline. aspectcorr type=string def=SOLUTION see tg_resolve_events rmfile type=string see tg_resolve_events This parameter is set by grt_lev15_calib in the pipeline. energy_lo_adj type=real def=1.0 min=0 max=10 see tg_resolve_events energy_hi_adj type=real def=1.0 min=0 max=10 see tg_resolve_events eventdef type=string def=)stdlev1 see tg_resolve_events rand_pix_size type=real def=0.5 min=0.0 max=0.5 units=pixel see tg_resolve_events stdlev1 type=string see tg_resolve_events stdlev1 is set internally by the pieline, please do not change this parameter. INPUT FILES The following are the lists of input files and stacks of files needed to run the pipeline. o) ACIS or HRC L1 event files: [root]_evt1.lis (list of level 1 event files, '*_evt1.fits') o) L1 files specify GTI: [root]_flt1.lis (list of GTI files, '*_flt1.fits') o) aspect files: either [root]_asol1.lis OR [root]_aoff1.lis for dithered data set depending on what is avaliable in the data set. No aspect files are needed for non-dithered dataset. ([root]_asol1.fits: list of aspect solution files, '*_asol1.fits' [root]_aoff1.fits: list of aspect offset files, '*_aoff1.fits') o) sim offset files: [root]_soff1.lis. It is only needed if aspect offset files are used for the dithered data sets. ([root]_soff1.fits: list of sim offset files, '*_soff1.fits') OUTPUT PRODUCTS The following are the archived output products produced by the pipeline. Primary Output Products o) acis / hrc L1.5 events: [root]_evt1a.fits Secondary Output Products o) Zero-order source list: [root]_src1a.fits The pipeline log file will also be created but not archieved. It includes not only the actual execution of the pipeline, but all the retrevial and archive steps. PIPELINE ARGUMENTS The following arguments are needed to instanciate the pipeline to be run for a particular obsid. o) root name: Root name of the observation o) input directory: Directory that contains all the required input files. o) output directory: Directory that all the output files will be written to. o) template name: Template name of the L15 pipeline, grt_lev15.ped. o) revision: Revision number The above parameters should be specified as "-r [root name]=[value] -i [input directory]=[value] -o [output directory]=[value] -t grt_lev15.ped -a [revision]=[value]" to pbuilder.pl or flt_run_pipe.pl VERSION DS6.0.0 LAST MODIFIED 8 May 2001