Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/tgmatchsrc.html
Jump to: Description · Example · Parameters · Bugs · See Also


AHELP for CIAO 4.16

tgmatchsrc

Context: Tools::Gratings

Synopsis

Match sources between two source lists by their 2-D separation files.

Syntax

tgmatchsrc infile refsrcfile outfile max_separation [clobber] [verbose]

Description

`tgmatchsrc' attempts to reconcile two source lists: an input source list, and a reference source list. It is assumed that there will not be multiple matches between the lists, so once a match is found, no further matches are searched for, and both sources are removed from future match searches. A match is determined by comparing the distance between the sources with the threshold separation parameter (in arcsec).

All reference sources are written to the output with the same ID, but if there is a match, the output data will be for the highest SNR of the two. Unmatched input sources are appended to the output with new sequential IDs. Then any unmatched new sources are appended to the end of the file; they also have new source ids assigned to them.

It should be noted that if refsrcfile is set to none, NONE, or "", then a copy of the infile will be made.

This tool is used by tgdetect for determining zero-order sources over multiple observation intervals. It is not normally run independently.

DATA FORMATS:

Both of the input files should share the same format. This is important in that the output file is going to be defined to have the same structure as the infile, and rows are going to be written to the outfile from both the infile and the refsrcfile. In particular though, the following columns are required, and if they cannot be found in both source files, the task will exit with an error:

RA in decimal degrees
DEC in decimal degrees
SNR
TG_SRCID

The output file name will have an extension name of SRCLIST.

If there are any errors the task will return -1 and print the errors that occurred to the screen. Otherwise zero will be returned.

ALGORITHMS:

The Source Matching algorithm works as follows:

if source_separation <= separation threshold then the sources match,

where source_separation is determined as follows:

sqrt((ref_src_RA - new_src_RA)**2 + (ref_src_DEC - new_src_DEC)**2)

Note that the RA and DEC are in decimal degrees while the input separation threshold is in arcsec. The later is converted to decimal degrees within the code.


Example

tgmatchsrc tgmatchsrc_new_src.fits tgmatchsrc_ref_src.fits . 1
clobber=yes verbose=4

Match sources between tgmatchsrc_new_src.fits and the reference file, tgmatchsrc_ref_src.fits, setting the separation threshold to one arcsecond.


Parameters

name type def min max units reqd autoname
infile file         yes  
refsrcfile file NONE       yes  
outfile file .       yes yes
max_separation real 3 0 20 arcsec yes  
clobber boolean no          
verbose integer 0 0 5      

Detailed Parameter Descriptions

Parameter=infile (file required)

New sources file to compare with the reference table.

Parameter=refsrcfile (file required default=NONE)

Reference sources file.

Parameter=outfile (file required default=. autoname=yes)

Output file name

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

Maximum allowed separation (arcsec) for sources to match.

Parameter=clobber (boolean default=no)

Overwrite existing output file, or don't.

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

Control amount of diagnostic chatter from none (0) to most (5).


Bugs

There are no known bugs for this tool.

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, tgdetect, tgdetect2, tgextract, tgextract2, tgidselectsrc, tgmask2reg, tgsplit
tools::region
rank_roi, regphystocel, roi, splitroi
tools::response
mktgresp
tools::table
dmtype2split