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
params
values*
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=matcherwhich 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>'
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>'
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 error
s
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>'
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>'
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>'
x
column
values differ by no more than error
.
matcher=2d values*='<x> <y>' params='<error>'
x
,y
) positions reckoned using
Pythagoras is less than error
.
matcher=Nd values*='<x> <y> ...' params='<error>'
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>'
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> ...'
matcher=2d_anisotropic
,
but specify matcher=3d_anisotropic
or whatever
and the corresponding number of entries in the values*
and params
parameters.
+
" 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>'
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
).