7.1 Match Criteria

Determining whether one row represents the same item as another is done by comparing the values in certain of their columns to see if they are the same or similar. The most common astronomical case is to say that two rows match if their celestial coordinates (right ascension and declination) are within a given small radius of each other on the sky. There are other possibilities; for instance the coordinates to compare may be in a Cartesian space, or have a higher (or lower) dimensionality than two, or the match may be exact rather than within an error radius....

If you just need to match two tables according to sky position with fixed errors you are recommended to use the simplified tskymatch2 task. For other cases, this section describes how to specify much more flexible match criteria for use with tmatch1, tmatch2 or tmatchn by setting the following parameters:

matcher

Name of the match criteria type.

params

Fixed value(s) giving the parameters of the match (typically an error radius). If more than one value is required, the values should be separated by spaces.

values*

Expressions to be compared between rows. This will typically contain the names of one or more columns, but each element may be an algebraic expression (see Section 10) rather than just a column name if required. If more than one value is required, the values should be separated by spaces. There is one of these parameters for each table taking part in the match, so for tmatch2 you must specify both values1 and values2.

tuning

Fixed value(s) supplying tuning parameters for the match algorithm. If there is more than one value, they should be separated by spaces. This value will have a sensible default, so you do not need to supply it, but providing adjusted values may make your match run faster or require less memory (or the reverse). Adjusting tuning parameters will not change the result of any match, only the resources required to run it. Looking at the progress output of a match will indicate what tuning values have been used; adjusting the value a bit up or down is a good way to experiment.

For example, suppose we wish to locate objects in two tables which are within 3 arcseconds of each other on the sky. One table has columns RA and DEC which give coordinates in degrees, and the other has columns RArad and DECrad which give coordinates in radians. These are the arguments which would be used to tell tmatch2 what the match criteria are:

   matcher=sky
   params=3
   values1='RA DEC'
   values2='radiansToDegrees(RArad) radiansToDegrees(DECrad)'

   stilts tmatch2 help=matcher

The following subsections list the basic matcher types and the requirements of their associated params, values* and tuning parameters. The units of the required values are given where significant.

• 7.1.1 sky: Sky Matching
• 7.1.2 skyerr: Sky Matching with Per-Object Errors
• 7.1.3 skyellipse: Sky Matching of Elliptical Regions
• 7.1.4 sky3d: Spherical Polar Matching
• 7.1.5 exact: Exact Matching
• 7.1.6 1d, 2d, ...: Isotropic Cartesian Matching
• 7.1.7 2d_anisotropic, ...: Anisotropic Cartesian Matching
• 7.1.8 2d_cuboid, ...: Cuboid Cartesian Matching
• 7.1.9 1d_err, 2d_err, ...: Cartesian Matching with Per-Object Errors
• 7.1.10 2d_ellipse: Cartesian Matching of Elliptical Regions
• 7.1.11 Custom Matchers
• 7.1.12 Matcher Combinations