STScI Logo

lmatchsrc xray.xspatial.detect


NAME · USAGE · DESCRIPTION · PARAMETERS · FULL_DESCRIPTION
EXAMPLES · TIME_REQUIREMENTS · BUGS · SEE_ALSO

NAME

lmatchsrc -- match sources between and within different detect cell sizes

USAGE

lmatchsrc qpoe itablst otabroot

DESCRIPTION

LMATCHSRC consolidates detections from one or more runs of ldetect into unique sources in a field.

Distance between input detections are computed and those falling within a match tolerance are determined to be the same source.

Two table files are output. The first (_unq.tab) is a unique list of all input detections where each has a unique row reference; the second file (_mch.tab) is the output of the match. This file is a match reference list with one row for each source. Match columns refer to the detections listed in the _unq.tab file.

PARAMETERS

qpoe = "" prompt = Reference Qpoe file name

Name of the reference qpoe. The match examines pixel positions of the sources, and thus all input tables must be the result of ldetect run with the same qpoe file.

itablist = "" prompt = List of detect tables to match [_pos.tab]

List of table(s) that are the result of ldetect run(s). The "_pos" must be be specified, no default extension naming exists.

otabroot = "" prompt = Root name for Match Source table

The output table root. Two tables are written, _unq.tab is the merge of all input tables, and _mch.tab is a match table with match row references to the _unq.tab file.

(err_factor = 3.) [real]

Factor used to multiply distance errors to determine match tolerances. When hidden parameter overide = yes, the value of err_factor is the absolute match tolerance in pixels.

(overide = no) [bool]

Indicates whether to overide the tolerance calculation using the pconf column from the input table file. If yes, the err_factor parameter (above) is used as the tolerace distance in pixels for the match test.

(display = 2) [int]

Display info to screen. Integer of range 0-5. The higher the number more verbose the display.

(clobber = no) [boolean]

Boolean flag specifying whether or not the output Table file can be overwritten, if it already exists.

FULL DESCRIPTION

All detections, regardless of cell size, are merged into a single position-ordered list. Sources are defined as one or more detections whose positions are closer than a match tolerance and which do not match any previous detections in the list. A distance and distance error are computed between the position of each subsequent detection in the list and the average positions of all sources preceeding it. If the distance is less than the match tolerance, the detection is matched with the source, and a new average source position and position error is calculated. Average positions and position errors are weighted by the position errors (pconf) of of the contributing detections.

The match tolerance is determined in one of two ways. The default is to set the tolerance equal to the product of err_factor and the distance error described above. This results in a match tolerance which varies from source to source. Alternatively, the user may set overide=yes, and the err_factor to the desired absolute tolerance.

If a source detection falls within the match tolerance of more than one source, the detection is matched with the closest source and the user is *Warned* that other source matches are possible. If, many (greater than a set limit of 10) detections fall within the match tolerance of a single source, matching is completed for all detections, but only the 10 strongest (highest snr) are listed in the match output. Again, the user is *Warned* about the other matches.

It is necessary that the list of input files derive from runs of ldetect using the same QPOE file, since the match is performed using pixel positions, and only pixel positions from the same qpoe file will properly match the same sources. Also, conversion of units from pixels to ra/dec are done using the reference QPOE. Some error checking is performed, but not all possibilities are covered; the user is WARNED and the match proceeds.

Two table files are output. The first is a unique list of all input detections (_unq.tab) where each detection has a unique row reference. All input files are merged and sorted in increasing Y pixel position order. The columns are the same as the input files (_pos.tab). The second file is the result of performing the match (_mch.tab). This file is a match reference where each row represents a source. Match columns refer to the detection listed in the _unq.tab file. Other information listed in the _mch.tab file are:

	 Column description of _mch.tab:

	 avgra	  - average ra in degrees
	 avgdec   - average dec in degrees
	 avgx	  - average x posisiotn in pixels
	 avgy     - average y position in pixels
         avgerr   - average position error
	 bestx    - x position in pixels of source detection from 
		    match with highest SNR
	 besty    - y position in pixels of source detection from 
	            match with highest SNR
         cellx    - cell size of best x in arc-seconds
         celly    - cell size of best y in arc-seconds
	 m1	  - row reference of detection in _unq.tab
	 ...
	 mn	  - row reference of detection in _unq.tab

The matches are in columns m1 ... mn, where n is the maximum number of matched of all sources in the list with a limit of 10. The match references for a source are listed in decreasing signal-to-noise ratio order.

EXAMPLES

1. Match sources from 4 runs of ldetect at different detect cell sizes.
  
> lmatchsrc
Reference Qpoe file name: xdata$rh110267.qp
List of detect tables to match [_pos.tab]: rh12_pos,rh24_pos,rh36_pos,rh48_pos
Root name for Match Source table: rharlac

... Merging the list of input tables

... Sorting the list in y,x order

... Matching the detections into Sources

     Avg ra       Avg dec   Avg x     Avg y     Best x    Best y   Src ref
                           (physical pixels)    (physical pixels)  (row #)
-----------------------------------------------------------------------------
 1 22:08:38.4   45:31:24.3  2380.332  2829.285  2380.510  2829.540  3 2 1
 2 22:09:01.3   45:37:14.3  1902.477  3531.475  1902.477  3531.475  4
 3 22:08:41.4   45:44:33.4  2323.537  4407.728  2323.539  4407.733  6 8 7 5 9

Writing to Match Results table:  rharlac_mch.tab
Writing to Match Reference table: rharlac_unq.tab


2. Match sources from 4 runs of ldetect at different detect cell sizes.  The
   position tolerance is set to 10.0 in this example.

> lmatchsrc overide=yes err_factor=10.0
Reference Qpoe file name (xdata$rh110267.qp):
List of detect tables to match [_pos.tab] (rh12_pos,rh24_pos,rh36_pos,rh48_pos):

Root name for Match Source table : rharlac10

... Merging the list of input tables

... Sorting the list in y,x order

... Matching the detections into Sources

     Avg ra       Avg dec   Avg x     Avg y     Best x    Best y   Src ref
                           (physical pixels)    (physical pixels)  (row #)
-----------------------------------------------------------------------------
 1 22:08:38.4   45:31:24.3  2380.330  2829.283  2380.510  2829.540  3 2 1
 2 22:09:01.3   45:37:14.3  1902.477  3531.475  1902.477  3531.475  4
 3 22:08:41.4   45:44:33.4  2323.537  4407.728  2323.539  4407.733  6 8 7 5 9

Writing to Match Results table:  rharlac10_mch.tab
Writing to Match Reference table: rharlac10_unq.tab
.nf

TIME REQUIREMENTS

BUGS

SEE ALSO

Documentation on displaying the match regions. (help detmkreg )

Documentation on ldetect. (help ldetect )

Documentation giving an overview of the detect package and run order of tasks. (help using_detect )

Documentation on the detect algorithms and philosophy along with limitations in (help explain_detect ).


Source Code · Search Form · STSDAS