Next Previous Up Contents
Next: tmatchn: Crossmatches multiple tables using flexible criteria
Up: tmatch2: Crossmatches 2 tables using flexible criteria
Previous: Usage

### B.33.2 Examples

Here are some examples of using `tmatch2`:

    stilts tmatch2 in1=obs_v.xml in2=obs_i.xml out=obs_iv.xml \
                   matcher=sky values1="ra dec" values2="ra dec" params="2"

  Takes two input catalogues (VOTables), one with observations in the V band and the other in the I band, and performs a match to find objects within 2 arcseconds of each other. The result is a new table containing only rows where a match was found.

    stilts tmatch2 survey.fits ifmt2=csv mycat.csv \
                   icmd1='addskycoords fk4 fk5 RA1950 DEC1950 RA2000 DEC2000' \
                   matcher=skyerr \
                   params=10 values1="RA2000 DEC2000 POS_ERR"  values2="RA DEC 0" \
                   join=2not1 omode=count

  Here a comma-separated-values file is being compared with a FITS catalogue representing some survey results. Positions in the survey catalogue use the FK4 B1950.0 system, and so a preprocessing step is inserted to create new position columns in the first input table using the FK5 J2000.0 system, which is what the other input table uses. The survey catalogue contains a POS_ERR column which gives the positional uncertainty of its entries, so the `skyerr` matcher is used, which takes account of this; the third entry in the `values1` parameter is the POS_ERR column (in arcsec). Since the second input table has no positional uncertainty information, 0 is used as the third entry in `values2`. The `params` gives a rough idea of the scale of the object separations, but its value does not affect the result. The join type is `2not1`, which means the output table will only contain those entries which are in the second input table but not in the first one. The output table is not stored, but the number of rows it contains (the number of objects represented in the CSV file but not the survey) is written to the screen.

    stilts tmatch2 ifmt1=ascii ifmt2=ascii in1=cat-a.txt in2=cat-b.txt \
                   matcher=2d values1='X Y' values2='X Y' params=5 join=1and2 \
                   suffix1=_a suffix2=_b \
                   ocmd='addcol XDIFF X_a-X_b; addcol YDIFF Y_a-Y_b' \
                   ocmd'keepcols "XDIFF YDIFF"' omode=stats

  Two ASCII-format catalogues are matched, where rows are considered to match if their X,Y positions are within 5 units of each other in some Cartesian space. The result of the matching operation is a table of all the matched rows, containing columns named X_a, Y_a, X_b and Y_b (along with any others in the input tables) - the `suffix*` parameters describe how the input X and Y columns are to be renamed to avoid duplicate column names in the output table. To this result are added two new columns, representing the X and Y positional difference between the rows from one input table and those from the other. The `keepcols` filter then throws all the other columns away, retaining only these difference columns. The final two-column table is not stored anywhere, but (`omode=stats`) statistics including mean and standard deviation are calculated on its columns and displayed to the screen. Having done all this, you can examine the average X and Y differences between the two input tables for matched rows, and if they differ significantly from zero, you can conclude that there is a systematic error between the positions in the two input files.

    stilts tmatch2 in1=mgc.fits in2=6dfgs.xml join=1and2 find=all \
                   matcher=sky+1d params='3 0.5' \
                   values1='ra dec bmag' values2='RA2000 DEC2000 B_MAG" \
                   out=pairs.fits

  This performs a match with a matcher that combines `sky` and `1d` match criteria. This means that the only rows which match are those which are both within 3 arcsec of each other on the sky and and within 0.5 blue magnitudes. Note that for both the `params` and the `values1` and `values2` parameters, the items for the `sky` matcher (RA and DEC) are listed first, followed by those for the `1d` matcher (in this case, blue magnitude).

Next Previous Up Contents
Next: tmatchn: Crossmatches multiple tables using flexible criteria
Up: tmatch2: Crossmatches 2 tables using flexible criteria
Previous: Usage

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