Next Previous Up Contents
Next: Internal Match Window
Up: Pair Match Window
Previous: Pair Match Window

#### A.8.2.1 Output Rows Selector Box

Pair match Output Rows Selector Box

When the match is complete a new table will be created which contains rows determined by the matches which have taken place. The Output Rows selector box allows you to choose on what basis the rows will be included in the output table as a function of the matches that were found.

In all cases each row will refer to only one matched (or possibly unmatched) "object", so that any non-blank columns in a given row come from only rows in the input tables which match according to the specified criteria. However, you have two choices to make about which rows are produced.

The Match Selection selector allows you to choose what happens when a row in one table can be matched by more than one row in the other table. There are four options:

All matches
  Every match between the two tables is included in the result. Rows from both of the input tables may appear multiple times in the result.
Best match, symmetric
  The best pairs are selected in a way which treats the two tables symmetrically. Any input row which appears in one result pair is disqualified from appearing in any other result pair, so each row from both input tables will appear in at most one row in the result.
Best match for each Table 1 row
  For each row in table 1, only the best match from table 2 will appear in the result. Each row from table 1 will appear a maximum of once in the result, but rows from table 2 may appear multiple times.
Best match for each Table 2 row
  For each row in table 2, only the best match from table 1 will appear in the result. Each row from table 2 will appear a maximum of once in the result, but rows from table 1 may appear multiple times.

The "best" match in these options generally means "closest" - it is the one with the lowest match score, where the definition of this score is determined by the match criteria you have selected. The differences between the various Best match... options are a bit subtle. In cases where it's obvious which object in each table is the best match for which object in the other, choosing between these options will not affect the result. However, in crowded fields (where the distance between objects within one or both tables is typically similar to or smaller than the specified match radius) it will make a difference. In this case one of the asymmetric options is usually most appropriate, but you'll need to think about which of them suits your requirements. The performance (time and memory usage) of the match may also differ between these options, especially if one table is much larger than the other.

The Join Type selector allows you to choose what output rows result from a match in the input tables.

1 and 2
  The output table contains only rows which have an entry from both of the input tables, so that every output row represents an actual matched pair. This corresponds to an SQL inner join.
All from 1
  All of the matched rows are present in the output as for 1 and 2, but additionally the unmatched rows from the first table are present with the columns from the second table blank. This corresponds to an SQL left outer join.
All from 2
  As for All from 1 but the other way round. This corresponds to an SQL right outer join.
1 or 2
  Every row, matched and unmatched, from both of the input tables appears in the output. This is the union of rows from All from 1 and All from 2. This corresponds to an SQL full outer join.
1 not 2
  This presents all the rows in the first table which do not have matches in the second table. Consequently, it only contains columns from the first table, since all the entries from the second one would be blank in any case.
2 not 1
  The same as 1 not 2 but the other way round.
1 xor 2
  The "exclusive or" of the match - the output only contains rows from the first table which don't have matches in the second table and vice versa. It is the union of 1 not 2 and 2 not 1.

Note that the choices of which Match Selection and Join Type to use are somewhat interlinked, and some combinations may not be very meaningful.

In most cases (all the above except for 1 not 2 and 2 not 1), the set of columns in the output table contains all the columns from the first table followed by all the columns from the second table. If this causes a clash of column names, offending columns will be renamed with a trailing "`_1`" or "`_2`". Depending on the details of the match however, some additional useful columns may be added:

Match Score
  For rows that represent a match, a numeric value representing how good the match was will usually be present. This is typically a separation in real or notional space - for instance for a Sky match it is the distance between the two matched celestial positions in arcseconds along a great circle. It will always be greater than or equal to zero, and a smaller value represents a better match. The name and exact meaning of this column depends on the match criteria - examine its description in the Columns Window for details.
GroupSize, GroupID
  If some of the rows match more than once (which may happen for any of the Match Selection options above apart from BEST), two columns named GroupID and GroupSize will be added. These allow you to identify which matches are multiple. In the case of rows which represent a unique match, they are blank. But for rows which represent a set of multiple matches, the GroupSize value tells you how many rows participate in this match, and the GroupID value is an integer which is the same for all the rows which participate in the same match. So if you do a sort on the GroupID value, you'll see all the rows in the first non-unique match group together, followed by all the rows in the second non-unique group... and after them all the unique matches.

Here is an example. If your input tables are these:

          X          Y         Vmag
          -          -         ----
       1134.822    599.247     13.8
        659.68    1046.874     17.2
        909.613    543.293      9.3

and

         X           Y         Bmag
         -           -         ----
       909.523     543.800     10.1
       1832.114    409.567     12.3
       1135.201    600.100     14.6
        702.622   1004.972     19.0

then a Cartesian match of the two sets of X and Y values with an error of 1.0 using the 1 and 2 option would give you a result like this:

         X_1       Y_1         Vmag    X_2        Y_2         Bmag    Separation
         ---       ---         ----    ---        ---         ----    ----------
       1134.822    599.247     13.8   1135.201    600.100     14.6     0.933
        909.613    543.293      9.3    909.523    543.800     10.1     0.515

using All from 1 would give you this:

         X_1       Y_1         Vmag    X_2        Y_2         Bmag    Separation
         ---       ---         ----    ---        ---         ----    ----------
       1134.822    599.247     13.8    1135.201   600.100     14.6     0.933
        659.68    1046.874     17.2
        909.613    543.293      9.3     909.523   543.800     10.1     0.515

and 1 not 2 would give you this:

         X         Y           Vmag
         -         -           ----
        659.68    1046.874     17.2

Next Previous Up Contents
Next: Internal Match Window
Up: Pair Match Window
Previous: Pair Match Window

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: topcat-user@bristol.ac.uk