tgdetect infile OBI_srclist_file outfile [temproot] [keeptemp]
[keepexit] [zo_pos_x] [zo_pos_y] [zo_sz_filt_x] [zo_sz_filt_y]
[snr_thresh] [expstk] [thresh] [ellsigma] [expratio] [findpeaks]
[celldetect_log] [psftable] [fixedcell] [fixedcell_cc_mode] [bkgfile]
[bkgvalue] [bkgerrvalue] [eband] [eenergy] [snrfile] [convolve]
[xoffset] [yoffset] [cellfile] [centroid] [snr_ratio_limit] [setsrcid]
[max_separation] [clobber] [verbose]

Description

Tgdetect detects point sources in a specifiable rectangular region and produces a sorted source table. If there are multiple observation intervals (OBIs), a detect is run on each independently, and then resulting tables are merged into a sorted list of unique sources.

Tgdetect is a wrapper script which sets up and executes several filter/copy tools, celldetect, and two grating specific tgdetect sub-tools. The functionality can be broken down into the following steps:

TG_FILT: A box region about the specified position is created. This filter string is based on the input parameters: zo_pos_x, zo_pos_y, zo_sz_filt_x, zo_sz_filt_y.

When tgdetect is run in the grating L1.5 pipeline, the parameters zo_pos_x and zo_pos_y are the RA_TARG and DEC_TARG of the observation, translated into pixel coordinates. If RA_TARG and DEC_TARG are absent from the header, RA_NOM and DEC_NOM will be used instead. However, if you run tgdetect as a stand alone tool and set zo_pos_x and zo_pos_y to "default", the tool will use hard-wired numbers to locate the center of the box for searching zero order sources. For ACIS, the hard-wired center is (4096.5,4096.5); for HRC-S, it is (32768.5,32768.5); for HRC-I, it is (16384.5,16384.5).

The parameters zo_sz_filt_x and zo_sz_filt_y are both set to 400 pixels for ACIS and 1800 pixels for HRC. This box region is passed to celldetect in order to detect at least the target zero order source.

The user can choose to enter their own center position and box dimensions using these same four parameters. If any of these parameters are not set to ``default'', then the number values are interpreted and default values are not used.

Example: instrument = ACIS, RA_NOM = # deg, DEC_NOM = # deg pix ra_nom = 4096.5, pix dec_nom = 4096.5 zo_pos_x=default, zo_pos_y=default zo_sz_filt_x=default, zo_sz_filt_y=default creates the filter: ``file[EVENTS][bin x=3800:4200,y=3820:4180]''

Example: if user specifies all the values: zo_pos_x=4000, zo_pos_y=4000 zo_sz_filt_x=400, zo_sz_filt_y=360 This creates filter: ``file[EVENTS][bin x=3800:4200,y=3820:4180]''

CELLDETECT: The 2D detection tool, ``celldetect'' is executed on the section of the event list designated in the filter above. Celldetect outputs positions of all sources detected in that region.

If no sources are found by celldetect, a blank table is output (table contains header/columns but no rows). Since there are three possible outcomes to running tgdetect: sources found, no sources found, error in processing; the exit status of tgdetect is output into a file called 'tgdetect.exit'. This file is used in pipeline processing. If no sources are found, the tool is still successful in running, but further processing with a blank table is impossible; the pipeline stops execution with a success status. In the other two cases, the pipeline continues to process the sources found (or, ends with failure since tgdetect failed to run successfully).

Since celldetect finds all 'sources' in the region of interest, these sources must be filtered for zeroth order detections. Most of the tgdetect processing steps below are filtering steps to find zeroth orders' sources by weeding out any possible contaminants.

SOURCE SELECT SNR: The output from celldetect is filtered by signal to noise threshold. The parameter snr_thresh is used as the filter on the sources; all sources less than snr_thresh are filtered out of the source list. If the snr filter is too high and all of the sources are filtered out, the value of snr_thresh will be reduced in half and the new value will be applied to filter the celldetect output file again. This is repeated until at least one source is found to be equal to or greater than the current setting for the snr_thresh level. If no sources are found when snr_thresh = 10, then the program exits. It is assumed that no zeroth order sources have been found when the snr of all detects is that low.

If one or more sources are found, they are sorted in order of highest to lowest signal to noise.

TGIDSELECTSRC: The snr selected and sorted source list is filtered once more on snr_ratio_limit. This step uses the highest snr as the reference snr for the creation of ratios. A ratio of the (source snr / highest snr) is calculated for each source; the parameter snr_ratio_limit is the cut off limit as to whether the source is left in the source list or filtered out. A snr_ratio_limit=0, allows for all source to match the limit criteria; a snr_ratio_limit=1 allows only the highest snr to match the criteria and filters out the rest of the sources in the list.

Example: snr_ratio_limit=0.5

source #	snr	ratio	include or exclude
1	100	1	include
2	80	0.8	include
3	50	0.5	include
4	49	0.49	exclude
5	10	0.1	exclude

A source ID column gets added to the resultant ratio filtered source list. The highest snr gets id=1; the id's increment by 1, for each source in the list.

TGMATCHSRC: The detected and filtered sources can be matched to a previous OBI's source list. This allows the source ID's to be matched to previous results, in case the SNR's were different for same source detections. If a reference OBI source list is not provided, the output source list from tgmatchsrc is simply a copy of the input source list to tgmatchsrc.

If sources are matched to another source list, the output source list is a combination of the current source list and the reference source list. All the sources in the reference list are matched within the max_separation tolerance. All matched source are output; all un-matched sources are appended to the end of the list.

If the reference OBI source list is empty (no rows), then the current source list is copied as the output resultant list. No matching is performed since there is no reference to match to.

tgdetect root_evt1.fits NONE root_src1a.fits

tgdetect root_evt1.fits root2_src1a.fits root_src1a.fits