Next Previous Up Contents
Next: Column Selection Boxes
Up: Common Features
Previous: Common Features
Match Criteria panel.
The details will differ depending on what match type is chosen.
The match criteria box allows you to specify what counts as a match
between two rows.
It has two parts.
First, you must select one of the options in the Algorithm
selector. This effectively selects the coordinate space in which rows
will be compared with each other. Depending on the chosen value,
a number of fields will be displayed below, which you must fill in
with values that determine how close two rows have to be in terms
of a metric on that space to count as a match.
The following match types (algorithm values) are offered:

Sky
 Comparison of positions on the celestial sphere.
In this case you will need to specify columns giving
Right Ascension and Declination
for each table participating in the match.
The Max Error value you must fill in is the
maximum separation of matched points around a great circle.

Sky with Errors
 The matching is like that for the Sky option above,
but an error radius (positional uncertainty) is given for each
row in the input tables, rather than just a single value for the whole
match.
Along with the Right Ascension and Declination columns,
you also specify an Error column which gives the error radius
corresponding to that position.
Two rows are considered to match when the separation between the
two RA,Dec positions is no larger than the sum of the two
Error values for the corresponding rows.
The Scale value should be set to a rough average of the perrow errors.
It is used only to set a sensible default for the Healpixk
tuning parameter, and its value does not affect the result.
If Healpixk is set directly (see Appendix A.8.1.3),
Scale is ignored.
Note: the semantics of this matcher have changed
slightly since version 3.8 of TOPCAT and earlier.
In earlier versions the single parameter was named Max Error
and provided an additional constraint on the maximum accepted separation
between matched objects. For most uses, the old and new behaviours are
expected to give the same results, but in cases of difference, the new
behaviour is more likely what you want.

Sky Ellipses
 Compares elliptical regions on the sky for overlap.
You will need to specify columns giving the central position,
major and minor radii, and position angle of the ellipse.
Two rows are considered to match if there is any overlap between the
ellipses. The goodness of match is a normalised generalisation of the
symmetrical case used by the Sky with Errors option above.
The position angle is measured from north to the semimajor axis,
in the direction towards the positive RA axis.
The Scale value should be set to a rough average of the major radii;
It is used only to set a sensible default for the Healpixk
tuning parameter, and its value does not affect the result.
If Healpixk is set directly (see Appendix A.8.1.3),
Scale is ignored.
The calculations are approximate since in some cases they rely on
projecting the ellipses onto a Cartesian tangent plane before evaluating
the match, so for larger ellipses the criterion will be less exact.
For objects the size of most observed stars or galaxies,
this approximation is not expected to be problematic.

Sky 3D
 Comparison of positions in the sky taking account of
distance from the observer.
In this case you will need to specify columns giving
Right Ascension and Declination in angular units,
as well as distance from the origin in arbitrary units
for each table participating in the match.
The Error value is a maximum separation in Cartesian space
of matched points in the same units as the radial distance.

Exact Value
 Requires exact matching of values.
In this case you will need to specify the column containing the match key
for each table participating in the match;
this might typically be an object name or index number.
Two rows count as matching if they have exactly the same entry in
the specified field, except rows with a null value in that column,
which don't match any other row. Note that the values must also
be of the same type, so for instance a Long (64bit) integer
value will not match an Integer (32bit) value.

Ndimensional Cartesian
 Comparison of positions in an isotropic Ndimensional Cartesian space.
In this case you will need to specify N columns giving
coordinates for each table participating in the match.
The Error value is the maximum spatial separation of matched points.
Currently the highest dimensionality you can select is 3d 
does anyone want a higher number?

Ndimensional Cartesian, Anisotropic
 Comparison of positions in an Ndimensional Cartesian space
with an anisotropic metric.
In this case you will need to specify N columns giving coordinates
for each table participating in the match,
and an error distance for each of these dimensions.
Points P1 and P2 are considered to match if P2 falls within
the ellipsoid with radii given by the error distances, centered on P1.
This kind of match will typically be used for non'spatial' spaces,
for instance (magnitude,redshift) space, in which the metrics in
different dimensions are not related to each other.
Currently the highest dimensionality you can select is 4d 
does anyone want a higher number?

Ndimensional Cuboids
 This matching is like that for Ndimensional Cartesian
above, but points are considered to match if they fall within the same
cuboid rather than ellipsoid. The error values are the halfaxis
lengths of the cuboid, like rectangular "radii".
This kind of match is suitable for grouping items into regularlyspaced
pixels, though it's not a very efficient way of doing that.

Ndimensional Cartesian with Errors
 The matching is like that for the Ndimensional Cartesian
option above, but an error radius (positional uncertainty) is given
for each row in the input tables, rather than just a single value
for the whole match.
Along with the Cartesian coordinate columns, you also specify an Error
column which gives the error radius corresponding to that position.
Two rows are considered to match when the separation between the
two positions is no larger than the sum of the two Error values
for the corresponding rows.
The Scale parameter should be approximately the characteristic size
of the perobject error values.
Its value, in conjunction with the Bin Factor tuning parameter,
affects the performance of the match but not the result.

2d Cartesian Ellipses
 Compares elliptical regions in the plane for overlap.
You will need to specify columns giving the central position,
major and minor radii, and orientation angle of the ellipse.
Two rows are considered to overlap if there is any overlap between the
ellipses. The goodness of match is a generalisation of the symmetrical
case used by the 2d Cartesian with Errors option above.
The orientation angle is measured anticlockwise from the Xaxis
to the ellipse major axis.
The Scale parameter should be set to a rough average of the major radii.
Its value, in conjunction with the Bin Factor tuning parameter,
affects the performance of the match but not the result.

Sky + X
 Comparison of positions on the celestial sphere with an additional
numeric constraint.
This is a combination of the Sky and
1d Cartesian matches above, so the columns you need
to supply are RA, Dec and one extra, and the errors are
angular separation on the sky and the error in the extra column.
A match is registered if it matches in both of the constituent tests.
You could use this for instance to match objects which are both close
on the sky and have similar luminosities.
The "distance" measure for Best* matches scales the
Sky distance and X distance by their maximum values and adds them in
quadrature, so they have equal weight
(d=sqrt([r/r_{max}]^{2}
+[dX/dX_{max}]^{2})).
Note that in TOPCAT versions 4.35 and earlier
a linear unscaled distance combination was used here,
which did not give very meaningful Best match results.

Sky + X with Errors
 Comparisons of positions on the celestial sphere
with an additional numeric constraint
that can itself vary per row.
This is a combination of the Sky and
1dimensional Cartesian with Errors matches above,
so the columns you will need to supply for each table are
RA, Dec, X (the additional coordinate), and
Error (the error on X).
The values in the Match Criteria box are Max Error giving the
sky position tolerance and Scale which should be approximately the
characteristic size of the X error values.
You could use this for instance to match tables by sky position and
redshift, where the redshift uncertainty varies per source.

Sky + XY
 Comparison of positions on the celestial sphere with two additional
numeric constraints.
This is a combination of the Sky and
2d Anisotropic Cartesian
matches above, so the columns you need to supply are
RA, Dec and two extra, and the errors are
angular separation on the sky and the error radii corresponding to
the extra columns.
A match is registered if it matches in all of the constituent tests.
You could use this for instance to match objects which are both close
on the sky and have similar luminosities and redshifts.
The "distance" measure for Best* matches scales the
Sky, X and Y distances by their maximum values and adds them in
quadrature, so they have equal weight
(d=sqrt([r/r_{max}]^{2}
+[dX/dX_{max}]^{2}
+[dY/dY_{max}]^{2})).
Note that in TOPCAT versions 4.35 and earlier
a linear unscaled distance combination was used here,
which did not give very meaningful Best match results.

HTM
 Performs sky matching in just the same way as the Sky
option above, but using a different algorithm (pixelisation of the
celestial sphere is performed using the Hierarchical Triangular Mesh
rather than the HEALPix scheme). The results in both cases
should be identical, but HTM is much slower. Hence, this option
is only useful for debugging. It may be withdrawn in future releases.
Depending on the match type, the units of the error value(s) you enter
may be significant. In this case, there will be a unit selector
displayed alongside the entry box. You must choose units which
are correct for the number you enter.
More information is available in the GUI as a tooltip by hovering with
the mouse pointer over the field in question.
See Appendix A.8.1.3 for information on optional
tuning parameters which are sometimes displayed in this panel.
The matching framework is capable of performing even more complicated
types of match, for instance Sky + 6dimensional anisotropic Cartesian.
These are not offered purely to avoid complicating the GUI.
More flexible matching requirements in this in and other respects
can be achieved by using the matching commands in
STILTS
instead.
Next Previous Up Contents
Next: Column Selection Boxes
Up: Common Features
Previous: Common Features
TOPCAT  Tool for OPerations on Catalogues And Tables
Starlink User Note253
TOPCAT web page:
http://www.starlink.ac.uk/topcat/
Author email:
m.b.taylor@bristol.ac.uk
Mailing list:
topcatuser@jiscmail.ac.uk