Next Previous Up Contents
Next: sky: Sky Matching
Up: Crossmatching
Previous: Crossmatching

### 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)'

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`, `values*` and `tuning` parameters.

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

Next Previous Up Contents
Next: sky: Sky Matching
Up: Crossmatching
Previous: Crossmatching

STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note256
STILTS web page: http://www.starlink.ac.uk/stilts/
Author email: m.b.taylor@bristol.ac.uk
Mailing list: topcat-user@jiscmail.ac.uk