Next Previous Up Contents
Next: Algebraic Expression Syntax
Up: Crossmatching
Previous: Crossmatching

6.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....

To determine the matching criteria, you set the values of the following parameters of tmatch2:

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 7) 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.

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)'
It is clearly important that corresponding values are comparable (in the same units) between the tables being matched, and in geometrically sensitive cases such as matching on the sky, it's important that they are the units expected by the matcher as well. To determine what those units are, either consult the roster below, or run the following command:
   stilts tmatch2 help=matcher
which will tell you about all the known matchers and their associated params and values* parameters.

Here is a list of all the basic matcher types and the requirements of their associated params and values* parameters. The units of the required values are given where significant.

matcher=sky values*='<ra/degrees> <dec/degrees>'
            params='<max-error/arcsec>'
Comparison of positions on the celestial sphere with a fixed error radius. Rows are considred to match when the two ra, dec positions are within max-error arcseconds of each other along a great circle.
matcher=skyerr values*='<ra/degrees> <dec/degrees> <error/arcsec>'
               params='<max-error/arcsec>'
Comparison of positions on the celestial sphere with per-row error radii. Rows are considered to match when the separation between the two ra, dec positions is smaller than both the fixed max-error value and the sum of the two per-row error values. If either of the error values is blank, then any separation up to max-error is considered a match. According to these rules, you might decide to set max-error to an arbitarily large number so that only the sum of errors will determine the actual match criteria. However please don't do this, since max-error also functions as a tuning parameter for the matching algorithm, and ought to be reasonably close to the actual maximum acceptable separation.
matcher=sky3d values*='<ra/degrees> <dec/degrees> <distance>'
              params='<error/Units of distance>'
Comparison of positions in the sky taking account of distance from the observer. The position in three-dimensional space is calculated for each row using the ra, dec and distance as spherical polar coordinates, where distance is the distance from the observer along the line of sight. Rows are considered to match when their positions in this space are within error units of each other. The units of error are the same as those of distance.
matcher=exact values*='<matched-value>'
Comparison of arbitrary key values for exact equality. Rows are considered to match only if the values in their matched-value columns are exactly the same. These values can be strings, numbers, or anything else. A blank value never matches, not even with another blank one. Since the params parameter holds no values, it does not have to be specified.
matcher=1d values*='<x>'
           params='<error>'
Comparison of positions in 1-dimensional Cartesian space. Rows are considered to match if their x column values differ by no more than error.
matcher=2d values*='<x> <y>'
           params='<error>'
Comparison of positions in 2-dimensional Cartesian space. Rows are considered to match if the difference in their (x,y) positions reckoned using Pythagoras is less than error.
matcher=Nd values*='<x> <y> ...'
          params='<error>'
Comparison of positions in N-dimensional Cartesian space. As for matcher=2d, but specify matcher=3d or whatever and the corresponding number of entries in the values* parameters.
matcher=2d_anisotropic values*='<x> <y>'
                       params='<error-in-x> <error-in-y>'
Comparison of positions in 2-dimensional Cartesian space using an anisotropic metric. Rows are considered to match if their (x,y) positions fall within an error ellipse with radii error-in-x,error-in-y of each other. This kind of match will typically be used for non-'spatial' spaces, for instance (magnitude,redshift) space, in which the metrics along different axes are not related to each other.
matcher=Nd_anisotropic values*='<x> <y> ...'
                       params='<error-in-x> <error-in-y> ...'
Comparison of positions in N-dimensional Cartesian space using an anisotropic metric. As matcher=2d_anisotropic, but specify matcher=3d_anisotropic or whatever and the corresponding number of entries in the values* and params parameters.
In addition to those matching criteria listed above, you can build your own by combining any of these. To do this, take the two (or more) matchers that you want to use, and separate their names with a "+" character. The values* parameters of the combined matcher should then hold the concatenation of the values* entries of the constituent matchers, and the same for the params parameter. So for instance the following can be used:
matcher=sky+1d values*='<ra/degrees> <dec/degrees> <x>'
               params='<max-error/arcsec> <error>'
Comparison of positions on the sky with an additional scalar constraint. Rows are considered to match if both their ra, dec positions are within max-error arcseconds of each other along a great circle (as for matcher=sky) and their x values differ by no more than error (as for matcher=1d).
This example might be used for instance to identify objects from two catalogues which are within a couple of arcseconds and also 0.5 blue magnitudes of each other. Rolling your own matchers in this way can give you very flexible match constraints.


Next Previous Up Contents
Next: Algebraic Expression Syntax
Up: Crossmatching
Previous: Crossmatching

STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note 256
STILTS web page: http://www.starlink.ac.uk/stilts/
Author email: m.b.taylor@bristol.ac.uk