Next Previous Up Contents
Next: Multi-Object Matches
Up: Match Criteria
Previous: Custom Matchers

#### 7.1.12 Matcher Combinations

In addition to the matching criteria listed in the previous subsections, 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. Two rows are then considered to match if the the match is successful for all of their constituent matchers.

A variant form where the names are separated with a "`*`" character instead of "`+`" may also be used. In this case an additional constraint is applied requiring that the distance measure (see below) is less than or equal to unity, thus requiring the points in the notional scaled parameter coordinate space to be within a unit hypersphere rather than a unit hypercube.

So for instance the matcher "`sky+1d`" could be used with the following syntax:

    matcher=sky+1d values*='<ra/deg> <dec/deg> <x>'
                   params='<max-error/arcsec> <error>'
                   tuning='<healpix-k> <bin-factor>'

> `values*`:
>   - `ra/deg`: Right Ascension
>   - `dec/deg`: Declination
>   - `x`: Cartesian co-ordinate #1
> `params`:
>   - `max-error/arcsec`: Maximum separation along a great circle
>   - `error`: Maximum Cartesian separation for match
> `tuning`:
>   - `healpix-k`: Controls sky pixel size. Legal range 0 - 29. 0 is 60deg, 20 is 0.2".
>   - `bin-factor`: Scaling factor to adjust bin size; larger values mean larger bins

This would compare 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`). Using `matcher=sky*1d` instead would work the same way but restrict the matches a bit further.

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 quite flexible match constraints.

When identifying the closest match (e.g. `find=best1` in `tmatch2`) the "distance" measure is obtained by scaling the distances from each of the constituent matchers and adding these scaled distances in quadrature, so that each element of the matcher has approximately equal weight. Scaling is generally done using the maximum permissible match radius (or equivalent), so the distance measure looks something like d = sqrt([dA/max(dA)]2 + [dB/max(dB)]2). However the details are a bit dependent on which matchers you are combining. If the "`*`" separator is used instead of "`+`" in the matcher specification as described above, this distance will always be <=1 for successful matches.

Note that in STILTS v3.0-9 and earlier, a linear unscaled distance measure was used here instead, which did not give very meaningful Best match results.

Next Previous Up Contents
Next: Multi-Object Matches
Up: Match Criteria
Previous: Custom Matchers

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