tgdetect

Synopsis

Detect and centroid the zero order image in a spatial sub-region of a grating event list.

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] [spectrum] [psffile] [units] [geompar] [expstk] [thresh]
[ellsigma] [expratio] [findpeaks] [eband] [eenergy] [celldetect_log]
[fixedcell] [fixedcell_cc_mode] [snr_diminution] [bkgfile] [bkgvalue]
[bkgerrvalue] [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

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.

Examples

Example 1

tgdetect root_evt1.fits NONE root_src1a.fits

This is an example of running tgdetect using no reference source list file.

Example 2

tgdetect root_evt1.fits root2_src1a.fits root_src1a.fits

This is an example of running tgdetect using a source list file as the reference file.

Parameters

Detailed Parameter Descriptions

Parameter=infile (string required filetype=input stacks=no)

Input L1 event file.

Although the tool won't complain when the user enters a stack of files to the infile parameter, only the first file in the stack will be used in the processing. The functionality of handling stack were added for pipeline usage. There are logical problems in using more than one input file in the list, therefore, only the first file is used in the input stack.

Parameter=OBI_srclist_file (string required filetype=input default=NONE stacks=no)

Input source position(s) file from previous OBI or NONE.

This file is used as a reference source list, in matching the detected sources from the "infile". When this file is not provided, the input source list is not matched against a reference source list; the results pertain strictly to the infile.

Although the tool won't complain when the user enters a stack of files to the OBI_srclist_file parameter, only the first file in the stack will be used in the processing.

Parameter=outfile (string required filetype=output)

Output source position(s) file name. (There are other intermediate files output, which may be deleted; see the "keeptemp" and "keepexit" parameters.)

Parameter=temproot (string not required filetype=output default=)

This parameter allows you to control the placement of the temporary and intermediate files created by this tool.

The tool will obey the following rules for this parameter:

1) If temproot == "" (default), temporary files will be created in the same directory as outfile and "" will be used as the "root" name for all temporary files. (ie, "_tgdetect.exit")

2) If temproot == <name>, temporary files will be placed in the same directory as outfile and <name> will be used as the "root" name. (ie, "<name>_sort_out.fits")

3) If temproot == <path>, temporary files will go into the directory <path> with "" as the "root" name. (ie, "<path>/_snr_select.fits")

4) If temproot == <path/name>, temporary files will be created in the directory <path> and <name> will be used as the "root" name. (ie, "<path>/<name>_cell_out.fits")

This parameter affects all temporary files (including tgdetect.exit file) but does not affect the output filename named in the "outfile" parameter.

Parameter=keeptemp (boolean default=no)

If set to "no" (default), temporary and intermediate files will be removed prior to the completion of this tool. If set to "yes", these files will not be removed.

This parameter affects the "cell_out", "snr_select", "sort_out" and "tgid_out" files, but does NOT affect the "tgdetect.exit" file; see the "keepexit" parameter for more information on the latter.

Parameter=keepexit (boolean default=no)

If set to "no" (default), the "tgdetect.exit" file will be removed prior to the completion of this tool. If set to "yes", this file will not be removed.

This parameter affects only "tgdetect.exit" file; see the "keeptemp" parameter for more information on other temporary and intermediate files created by this tool.

Parameter=zo_pos_x (real default=default)

Center X of grating zero order filter position in sky pixel coordinates. When run in the pipeline, the target RA position is retrieved from the header and converted to detector pixel location. If set to "default", a hard-wired location is used as the center of the filter area (see the TG_FILT description).

Parameter=zo_pos_y (real default=default)

Center Y of grating zero order filter position in sky pixel coordinates. When run in the pipeline, the target DEC position is retrieved from the header and converted to detector pixel location. If set to "default", a hard-wired location is used as the center of the filter area (see the TG_FILT description).

Parameter=zo_sz_filt_x (real default=default)

Size X of grating zero order filter in sky pixels.

If set to "default", the instrument determines the size, currently, the two known default are: ACIS => 400 pixels HRC => 1800 pixels

Parameter=zo_sz_filt_y (real default=default)

Size Y of grating zero order filter in sky pixels.

If set to "default", the instrument determines the size, currently, the two known default are: ACIS => 400 pixels HRC => 1800 pixels

Parameter=snr_thresh (real default=40 min=3 max=10000)

Signal to noise threshold level for zero order filtering. All detected sources below the snr_thresh will not be counted as zero order source detections and will be dropped from the source list.

Parameter=spectrum (file)

Spectral weights file

If a spectrum is input (two column file with energy (keV) vs. weights (renormlized to sum(weights)=1) then a spectrally weighted PSF map will be created.

Parameter=psffile (file filetype=input default=CALDB)

Image of PSF size data.

The PSF map used by celldetect to determine the detect cell size. The default value, CALDB, instructs tgdetect to run the mkpsfmap tool with the image that will be used as the celldetect infile.

Parameter=units (string not required default=arcsec)

Determines the units of the pixel values in the PSF map.

Valid units are "logical", "physical", or "arcsec"

Parameter=geompar (file filetype=input)

The pixlib geometry file name.

Parameter=expstk (string filetype=input default=none)

Input exposure map file or a list of exposure map files. It is a celldetect parameter. Enter "none" if there is no exposure map.

Parameter=thresh (real min=3 max=10000)

A celldetect parameter. Signal to noise threshold for source detection.

Parameter=ellsigma (real default=3.0)

Size of output source ellipses (in sigmas). A celldetect parameter.

Parameter=expratio (real default=0)

Cutoff ratio for source cell exposure variation. A celldetect parameter.

Parameter=findpeaks (boolean default=yes)

A celldetect parameter. If set to yes, celldetect will find the local maxima of contiguous detections. Otherwise, single sources might be identified multiple times.

Parameter=eband (real default=1.4967 min=0 units=keV)

A celldetect parameter. Photon energy at which to calculate the PSF (keV).

Parameter=eenergy (real default=0.8 min=0)

A celldetect parameter. Fraction (maximum value = 1.0) of PSF energy to be encircled by the detect cell.

Parameter=celldetect_log (string default=no)

A celldetect parameter. Make a celldetect log file?

Parameter=fixedcell (integer default=15 min=0 max=999)

A celldetect parameter, which specifies the mode and size of the "aperture" used to scan the image for sources.

If set to a non-zero value, celldetect will use a fixed size cell of the specified dimension over the entire field of view. This effectively disables the eenergy, x/yoffset, and eband parameters. Value must be divisible by three, or equal to one.

If this is set to zero, then the cell has a variable size and the psftable is also used. A fixedcell=15 works well for isolated sources. Fixedcell=6 works well for sources as close as 2 arcsec.

Parameter=fixedcell_cc_mode (integer default=15 min=0 max=999)

A celldetect parameter. Fixed cell size to use for ACIS CC mode.

CC-mode sky "images" are quasi-linear.

Parameter=snr_diminution (real default=1 min=0 max=1)

Evaluate detect cells with diminished SNR on finer grid.

If a detect cell is found to have a SNR = snr_diminution*thresh, then celldetect will recompute the SNR by recentering the detect cell on a finer grid. If the recentered cell is found to have a SNR above the threshold then it will be added to the source list.

Parameter=bkgfile (string filetype=input default=none)

Background file, a celldetect parameter.

The input background file will be ignored if bkgvalue is non-zero.

Parameter=bkgvalue (real min=0)

A celldetect parameter. Fixed value (counts/pixels) to use for the background. A non-zero value will override the normal background file option.

Parameter=bkgerrvalue (real min=0)

A celldetect parameter. Error in backgorund map or value. If unknown, set to 0.

Parameter=snrfile (string filetype=output default=none)

A celldetect parameter. snr output file (only set this parameter when convolve is "yes" ).

Parameter=convolve (boolean)

A celldetect parameter. If set to "yes", source detection is done using the convolution library instead of sliding cells.

Parameter=xoffset (integer default=INDEF min=INDEF max=INDEF)

A celldetect parameter. Offset of x-axis from optical axis. It is used to calculate the off-axis angle.

By default (when both xoffset and yoffset are set to INDEF, celldetect will calculate the off-axis angle using the nominal pointing of the input data file as the origin.

A typical scenario in which the users may select to use offsets is when their data file is a sum of two or more observations, with different pointings. The nominal pointing in such data file is usually poorly defined and the off-axis angle could be calculated from an undesired origin, leading to suboptimal selection of the detect cell size. The ability to set the origin explicitly with x/yoffset solves this problem.

Parameter=yoffset (integer default=INDEF min=INDEF max=INDEF)

A celldetect parameter. Offset of y-axis from optical axis. It is used to calculate the off-axis angle.

By default (when both xoffset and yoffset are set to INDEF, celldetect will calculate the off-axis angle using the nominal pointing of the input data file as the origin.

Parameter=cellfile (string filetype=output default=none)

A celldetect parameter. Output cell size image file.

Parameter=centroid (boolean default=yes)

A celldetect parameter. If set to "yes", celldetect will compute the source centroid positions. Otherwise, the center pixel of a source's detect cell is reported as the location of the source.

Parameter=snr_ratio_limit (real min=0.0 max=1.0)

A tgidselectsrc parameter. Value of SNR ratio to use as lower limit.

Parameter=setsrcid (boolean)

A tgidselectsrc parameter. Set src ids in output file?

Parameter=max_separation (real default=3 min=0 max=20 units=arcsec)

A tgmatchsrc parameter. Maximum allowed separation (arcsec) for sources to match.

Parameter=clobber (boolean default=no)

Overwrite existing output file or not?

If file is write protected and clobber=yes; program will exit. If file exists and clobber=no, program will also exit.

Parameter=verbose (integer default=0 min=0 max=5)

Verbose setting. Setting to zero is the least amount of output to the screen while setting of 5 is the most.

Changes in CIAO 4.15

The header of the new file (the outfile parameter) will now contain the parameter settings for this tool. It can be retrieved with the dmhistory tool or the get_history_records method of the pycrates python library.

Changes in CIAO 4.11

The celldetect changes in CIAO 4.11 are exposed by tgdetect. For most users, the default psffile=CALDB will create and use a PSF map using the mkpsfmap tool with the same energy and ECF parameters as earlier CIAO releases. Users can optionally specify their own PSF map via the psffile.

Changes in CIAO 4.17

• Improve warning when the initial SNR check fails to find a source to use for the zero order location.

Bugs

The tool cannot accept a Data Model virtual syntax specification.

Tool doesn't check for .gz files  (06 Mar 2007)

tgdetect will not locate a gzipped input file unless the ".gz" extension is explicitly given.

See Also

chandra

eventdef

tools::background

create_bkg_map

tools::composite

combine_grating_spectra

tools::detect

celldetect, vtpdetect, wavdetect, wrecon, wtransform

tools::gratings

detilt, dewiggle, symmetrize, tg_bkg, tg_choose_method, tg_create_mask, tg_findzo, tg_resolve_events, tgdetect2, tgextract, tgextract2, tgidselectsrc, tgmask2reg, tgmatchsrc, tgsplit

tools::region

rank_roi, regphystocel, roi, splitroi

tools::response

mktgresp

tools::table

dmtype2split